package home
_content_ {

<h2>How to make your own Greenstone home page</h2>

<h3>Question</h3>
<ul>
    How can you specify a different opening page for Greenstone?  Does it
    work with the Local Library?  Does it work if I put the  collection onto
    CD-ROM?  Can I have other links in it?
</ul>

<h3>Answer</h3>
<ul>
    It's easy!  And the answers to the other questions are yes, yes, yes.
</ul>

<h3>Example</h3>
<ul>
<table>
<tr align=left><th>Where to go</th><th>Incantation</th><th>Check this!</th>
<tr valign=top><td>Search page for the demo collection<br>(Replace "demo" by your collection name)</td>
    <td>\_httpquery\_&c=demo</td>
    <td><a href="_httpquery_&c=demo">Click here</a></td></tr>

<tr><td>"About" page for the demo collection</td>
    <td>\_httppageabout\_&c=demo</td>
    <td><a href="_httppageabout_&c=demo">Click here</a></td></tr>

<tr><td>Preferences page for the demo collection</td>
    <td>\_httppagepref\_&c=demo</td>
    <td><a href="_httppagepref_&c=demo">Click here</a></td></tr>

<tr><td>Home page</td>
    <td>\_httppagehome\_</td>
    <td><a href="_httppagehome_">Click here</a></td></tr>

<tr><td>Help page</td>
    <td>\_httppagehelp\_</td>
    <td><a href="_httppagehelp_">Click here</a></td></tr>

<tr><td>Administration page</td>
    <td>\_httppagestatus\_</td>
    <td><a href="_httppagestatus_">Click here</a></td></tr>

<tr><td>The Collector</td>
    <td>\_httppagecollector\_</td>
    <td><a href="_httppagecollector_">Click here</a></td></tr>

</table>
</ul>

<h3>How to do it</h3>
<ul>
    <p>What generates the Greenstone home page is in the file home.dm.
    It's actually the thing called "package home" that is defined in that file.
    You could edit this file, or create a new file that defined "package
    home" in a different way.

    <p>When you make a different opening page, you have to have some way of
    linking in to the Greenstone pages.  The solution that we adopt is to use
    "macros".  That's why the home-page file is called ".dm"
    and not ".html" -- it's a "macro" file rather than a regular html file.
    But don't quail: the macro file basically contains just html, sprinkled
    with a few mystical incantantations.

    <p>The best way to see is with an example.  So this file is an example!
    The text you are reading is in a file called yourhome.dm, and it's a
    template for creating your own specialized Greenstone home page.  Replace
    this text with your own to create a home page tailored to your own needs.
    The text is regular html; you can include links and all the other stuff
    that html provides.

    <p>Most of this file just the html that is used to create this page.  To
    link in with other Greenstone pages, use the appropriate magic spell
    (surrounded by underscores) -- such as \_httppagehome\_, \_httppagehelp\_,
    \_httppagepref\_, etc.
</ul>

<h3>How to make it work</h3>
<ul>

    <p>You have to tell Greenstone about the new home page yourhome.dm.
    Greenstone reads in the macro files that are specified in the main
    configuration file main.cfg, so if you create a new one you must include it
    there.  Name clashes are handled sensibly (most recent definition takes
    precedence), and reported in an error log on startup.

    <p>Thus to make the Greenstone digital library software use this home page
    instead of the default, first put this file into the appropriate place,
    which is $GSDLHOME$gsdl/macros/yourhome.dm.  Then edit the
    gsdl/etc/main.cfg configuration file to replace the home.dm macro file with
    yourhome.dm in the list of macro files that are loaded at startup.
</ul>

<h3>Advanced stuff</h3>
<ul>

    <p>The other macros in this file (\_httppagehome\_, \_httppagehelp\_,
    \_httppagepref\_, etc.) are defined in the base macro file base.dm.

    <p>With the \_httpquery\_, \_httppageabout\_ and \_httppagepref\_ macros,
    you need to append an extra argument naming the collection you require
    (&c=collectionname).  Check base.dm for the definition of these macros

    <p>The whole of the current file, yourhome.dm, is defined as the body of
    the \_content\_ macro of the "home" package -- that is what the very first
    and last lines of this file do.

    <p>This macro definition (\_content\_) is just plain html.  Any standard
    html code may be placed within a macro definition.  However, the special
    characters '\{', '\}', '\\', and '\_' must be escaped with a backslash to
    prevent them from being processed by the macro language interpreter.

    <p>As you can see if you look at the file, the \_content\_ macro definition
    does not contain any html header or footer.  If you want to change the html
    within the header or footer of your home page you may define a \_header\_
    and a \_footer\_ macro.  Defining a new macro is a simple case of adding it
    to the yourhome.dm macro file in the form

    <p><ul>\_macroname\_ \{ 
           <ul>...</ul>
           \}
    </ul>

    <p>where \_macroname\_ is \_header\_, \_footer\_ etc.
</ul>

<h3>Really advanced stuff</h3>
<ul>

    <p>You may be surprised to find example that \_httpquery\_ is not used in
    home.dm.  The reason is that the list of collection names is generated 
    dynamically (by a C++ function) to reflect the collections that are present
    on your system.  The \_homeextra\_ macro in home.dm is where this is
    invoked.  Of course, in your application you will know the collection name,
    so you can use the appropriate &c=... argument -- just as we have used
    "demo" in this file.

</ul>
}

# if you hate the squirly green bar down the left-hand side of the page,
# uncomment these lines:

# _header_ { 
#          }