====== 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 //home.dm//, 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 //yourhome.dm//. This will be like //home.dm// 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. ===== Example ===== {{..:images:install_fig_3.png?395x227&direct}} Figure 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 //yourhome.dm// shown in Figure . > package home _content_ {

Your own Greenstone home page

} # if you hate the squirly green bar down the left-hand side of the # page, uncomment these lines: # _header_ { # } You can use Figure 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 . 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 //yourhome.dm// 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 . ===== How to make it work ===== You have to tell Greenstone about the new home page //yourhome.dm//. 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 instead of the default, first put the //yourhome.dm// file in Figure into the //macros// directory. Then edit the //main.cfg// configuration file to replace //home.dm// with //yourhome.dm// 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 // http:%%//%%nzdl.org // (which is shorthand for // http:%%//%%nzdl.org/index.html) // is redirected to // http:%%//%%nzdl.org/cgi-bin/library //. 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 // http:%%//%%www.yourserver.com // to // http:%%//%%www.yourserver.com/cgi-bin/library //, put this line into //httpd.conf//: Redirect /index.html http://www.yourserver.com/cgi-bin/library Then you will reach your digital library system directly from the URL // http:%%//%%www.yourserver.com //. Instead, if you wanted a URL like // http:%%//%%www.yourserver.com/greenstone // to be redirected to // http:%%//%%www.yourserver.com/cgi-bin/library //, include in the //httpd.conf// file Redirect /greenstone http://www.yourserver.com/cgi-bin/library If your computer doesn't have a domain name (like the “www.yourserver.com” above), just replace // www.yourserver.com // 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//.