User Tools

Site Tools


Personalizing your Installation

Probably the first thing you will want to do once your Greenstone installation is up and running is personalize the home page. The file that generates the Greenstone home page is called, and is located in the macros subdirectory of the directory into which you installed Greenstone. (The default for Windows systems is C:\Program Files\gsdl.) This is a plain text file that you will have to edit to create a new home page. Instead of editing it, we recommend creating a new file, say This will be like but will define “package home”—which is the bit that does the actual work—in a different way.

When you make a different home page, there must be some way of linking in to the digital library pages so that you can search and browse the collections on your system. The solution that Greenstone adopts 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 which are explained below. The macro language is a powerful facility, and only a small part of it is described below—see the Greenstone Digital Library Developer's Guide for more information.


<imgcaption figure_your_own_greenstone_home_page|%!– id:264 –%Your own Greenstone home page ></imgcaption>

Figure <imgref figure_your_own_greenstone_home_page> shows an example of a new digital library home page. Each of the “Click here” links takes you to the appropriate Greenstone facility. This page was generated by the file called shown in Figure <imgref figure_yourhome_dm>.

<imgcaption figure_yourhome_dm|%!– id:266 – used to create Figure <imgref figure_your_own_greenstone_home_page> ></imgcaption>

package home
_content_ {
<h2>Your own Greenstone home page</h2>
<tr valign=top><td>Search page for the demo collection<br></td>
      <td><a href="_httpquery_&c=demo">Click here</a></td></tr>
<tr><td>"About" page for the demo collection</td>
      <td><a href="_httppageabout_&c=demo">Click here</a></td></tr>
<tr><td>Preferences page for the demo collection</td>
      <td><a href="_httppagepref_&c=demo">Click here</a></td></tr>
<tr><td>Home page</td>
      <td><a href="_httppagehome_">Click here</a></td></tr>
<tr><td>Help page</td>
      <td><a href="_httppagehelp_">Click here</a></td></tr>
<tr><td>Administration page</td>
      <td><a href="_httppagestatus_">Click here</a></td></tr>
<tr><td>The Collector</td>
      <td><a href="_httppagecollector_">Click here</a></td></tr>
# if you hate the squirly green bar down the left-hand side of the
# page, uncomment these lines:
# _header_ {
# }

You can use Figure <imgref figure_yourhome_dm> as a template for creating your own specialized Greenstone home page. Basically, it defines a macro called content. Inside the curly braces is ordinary html. You could insert additional text, along with any html formatting commands, to put the content that you want to see on the page. The text is regular html; if you want you can include hyperlinks and use all the other facilities that html provides.

To make your new home page link in with other digital library pages, you need to use an appropriate magic spell. In this macro language, magic spells are words flanked by underscores. You can see these in Figure <imgref figure_yourhome_dm>. For example, _httppagehome_ takes you to the home page, _httppagehelp_ to the help page, and so on. In some cases you need to include a collection name. For example, _httpquery_&c=demo specifies the search page for the demo collection; for other collections you should replace demo by the appropriate collection name.

The definition of the macro called _content_ is 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.

Note that the _content_ macro definition does not contain any html header or footer. If you want to change the header or footer of your home page, you should define _header_ and/or _footer_ macros, adding them to the file in the form

_macroname_ {

For example, the squirly green bar down the left-hand side of Greenstone pages is defined in the _header_ macro, and making this macro null will remove it, as indicated at the end of Figure <imgref figure_yourhome_dm>.

How to make it work

You have to tell Greenstone about the new home page The system 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: the most recent definition takes precedence.

Thus to make the Greenstone digital library software use the home page in Figure <imgref figure_your_own_greenstone_home_page> instead of the default, first put the file in Figure <imgref figure_yourhome_dm> into the macros directory. Then edit the main.cfg configuration file to replace with in the list of macro files that are loaded at startup.

Redirecting a URL to Greenstone

You may want to redirect a more convenient URL to your Greenstone cgi program. For example, on our system the URL (which is shorthand for is redirected to . The Apache webserver accomplishes this with the Redirect directive. Along with other directives, this goes into the C:\Program Files\Apache Group\Apache\conf\httpd.conf configuration file. To redirect the URL to , put this line into httpd.conf:

Redirect /index.html

Then you will reach your digital library system directly from the URL . Instead, if you wanted a URL like to be redirected to , include in the httpd.conf file

Redirect /greenstone

If your computer doesn't have a domain name (like the “” above), just replace by localhost in the lines above. So long as the browser is running on the same machine as the webserver—which it surely is if your computer doesn't have a domain name—this has the same effect as the above redirections.

Instead of putting redirect directives into the file httpd.conf, you can equally well put them into a file called .htaccess within your server's document root directory. In fact, doing so has two advantages. First, changes to .htaccess take effect immediately, whereas you have to restart the Apache webserver to see the effect of changes to httpd.conf. Second, on Unix systems you usually have to be logged in as the “root” user to edit httpd.conf, whereas you don't to edit .htaccess.

legacy/manuals/en/install/personalizing.txt · Last modified: 2023/03/13 01:46 by