1 | package home
|
---|
2 | _content_ {
|
---|
3 |
|
---|
4 | <h2>How to make your own Greenstone home page</h2>
|
---|
5 |
|
---|
6 | <h3>Question</h3>
|
---|
7 | <ul>
|
---|
8 | How can you specify a different opening page for Greenstone? Does it
|
---|
9 | work with the Local Library? Does it work if I put the collection onto
|
---|
10 | CD-ROM? Can I have other links in it?
|
---|
11 | </ul>
|
---|
12 |
|
---|
13 | <h3>Answer</h3>
|
---|
14 | <ul>
|
---|
15 | It's easy! And the answers to the other questions are yes, yes, yes.
|
---|
16 | </ul>
|
---|
17 |
|
---|
18 | <h3>Example</h3>
|
---|
19 | <ul>
|
---|
20 | <table>
|
---|
21 | <tr align=left><th>Where to go</th><th>Incantation</th><th>Check this!</th>
|
---|
22 | <tr valign=top><td>Search page for the demo collection<br>(Replace "demo" by your collection name)</td>
|
---|
23 | <td>\_httpquery\_&c=demo</td>
|
---|
24 | <td><a href="_httpquery_&c=demo">Click here</a></td></tr>
|
---|
25 |
|
---|
26 | <tr><td>"About" page for the demo collection</td>
|
---|
27 | <td>\_httppageabout\_&c=demo</td>
|
---|
28 | <td><a href="_httppageabout_&c=demo">Click here</a></td></tr>
|
---|
29 |
|
---|
30 | <tr><td>Preferences page for the demo collection</td>
|
---|
31 | <td>\_httppagepref\_&c=demo</td>
|
---|
32 | <td><a href="_httppagepref_&c=demo">Click here</a></td></tr>
|
---|
33 |
|
---|
34 | <tr><td>Home page</td>
|
---|
35 | <td>\_httppagehome\_</td>
|
---|
36 | <td><a href="_httppagehome_">Click here</a></td></tr>
|
---|
37 |
|
---|
38 | <tr><td>Help page</td>
|
---|
39 | <td>\_httppagehelp\_</td>
|
---|
40 | <td><a href="_httppagehelp_">Click here</a></td></tr>
|
---|
41 |
|
---|
42 | <tr><td>Administration page</td>
|
---|
43 | <td>\_httppagestatus\_</td>
|
---|
44 | <td><a href="_httppagestatus_">Click here</a></td></tr>
|
---|
45 |
|
---|
46 | <tr><td>The Collector</td>
|
---|
47 | <td>\_httppagecollector\_</td>
|
---|
48 | <td><a href="_httppagecollector_">Click here</a></td></tr>
|
---|
49 |
|
---|
50 | </table>
|
---|
51 | </ul>
|
---|
52 |
|
---|
53 | <h3>How to do it</h3>
|
---|
54 | <ul>
|
---|
55 | <p>What generates the Greenstone home page is in the file home.dm.
|
---|
56 | It's actually the thing called "package home" that is defined in that file.
|
---|
57 | You could edit this file, or create a new file that defined "package
|
---|
58 | home" in a different way.
|
---|
59 |
|
---|
60 | <p>When you make a different opening page, you have to have some way of
|
---|
61 | linking in to the Greenstone pages. The solution that we adopt is to use
|
---|
62 | "macros". That's why the home-page file is called ".dm"
|
---|
63 | and not ".html" -- it's a "macro" file rather than a regular html file.
|
---|
64 | But don't quail: the macro file basically contains just html, sprinkled
|
---|
65 | with a few mystical incantantations.
|
---|
66 |
|
---|
67 | <p>The best way to see is with an example. So this file is an example!
|
---|
68 | The text you are reading is in a file called yourhome.dm, and it's a
|
---|
69 | template for creating your own specialized Greenstone home page. Replace
|
---|
70 | this text with your own to create a home page tailored to your own needs.
|
---|
71 | The text is regular html; you can include links and all the other stuff
|
---|
72 | that html provides.
|
---|
73 |
|
---|
74 | <p>Most of this file just the html that is used to create this page. To
|
---|
75 | link in with other Greenstone pages, use the appropriate magic spell
|
---|
76 | (surrounded by underscores) -- such as \_httppagehome\_, \_httppagehelp\_,
|
---|
77 | \_httppagepref\_, etc.
|
---|
78 | </ul>
|
---|
79 |
|
---|
80 | <h3>How to make it work</h3>
|
---|
81 | <ul>
|
---|
82 |
|
---|
83 | <p>You have to tell Greenstone about the new home page yourhome.dm.
|
---|
84 | Greenstone reads in the macro files that are specified in the main
|
---|
85 | configuration file main.cfg, so if you create a new one you must include it
|
---|
86 | there. Name clashes are handled sensibly (most recent definition takes
|
---|
87 | precedence), and reported in an error log on startup.
|
---|
88 |
|
---|
89 | <p>Thus to make the Greenstone digital library software use this home page
|
---|
90 | instead of the default, first put this file into the appropriate place,
|
---|
91 | which is $GSDLHOME$gsdl/macros/yourhome.dm. Then edit the
|
---|
92 | gsdl/etc/main.cfg configuration file to replace the home.dm macro file with
|
---|
93 | yourhome.dm in the list of macro files that are loaded at startup.
|
---|
94 | </ul>
|
---|
95 |
|
---|
96 | <h3>Advanced stuff</h3>
|
---|
97 | <ul>
|
---|
98 |
|
---|
99 | <p>The other macros in this file (\_httppagehome\_, \_httppagehelp\_,
|
---|
100 | \_httppagepref\_, etc.) are defined in the base macro file base.dm.
|
---|
101 |
|
---|
102 | <p>With the \_httpquery\_, \_httppageabout\_ and \_httppagepref\_ macros,
|
---|
103 | you need to append an extra argument naming the collection you require
|
---|
104 | (&c=collectionname). Check base.dm for the definition of these macros
|
---|
105 |
|
---|
106 | <p>The whole of the current file, yourhome.dm, is defined as the body of
|
---|
107 | the \_content\_ macro of the "home" package -- that is what the very first
|
---|
108 | and last lines of this file do.
|
---|
109 |
|
---|
110 | <p>This macro definition (\_content\_) is just plain html. Any standard
|
---|
111 | html code may be placed within a macro definition. However, the special
|
---|
112 | characters '\{', '\}', '\\', and '\_' must be escaped with a backslash to
|
---|
113 | prevent them from being processed by the macro language interpreter.
|
---|
114 |
|
---|
115 | <p>As you can see if you look at the file, the \_content\_ macro definition
|
---|
116 | does not contain any html header or footer. If you want to change the html
|
---|
117 | within the header or footer of your home page you may define a \_header\_
|
---|
118 | and a \_footer\_ macro. Defining a new macro is a simple case of adding it
|
---|
119 | to the yourhome.dm macro file in the form
|
---|
120 |
|
---|
121 | <p><ul>\_macroname\_ \{
|
---|
122 | <ul>...</ul>
|
---|
123 | \}
|
---|
124 | </ul>
|
---|
125 |
|
---|
126 | <p>where \_macroname\_ is \_header\_, \_footer\_ etc.
|
---|
127 | </ul>
|
---|
128 |
|
---|
129 | <h3>Really advanced stuff</h3>
|
---|
130 | <ul>
|
---|
131 |
|
---|
132 | <p>You may be surprised to find example that \_httpquery\_ is not used in
|
---|
133 | home.dm. The reason is that the list of collection names is generated
|
---|
134 | dynamically (by a C++ function) to reflect the collections that are present
|
---|
135 | on your system. The \_homeextra\_ macro in home.dm is where this is
|
---|
136 | invoked. Of course, in your application you will know the collection name,
|
---|
137 | so you can use the appropriate &c=... argument -- just as we have used
|
---|
138 | "demo" in this file.
|
---|
139 |
|
---|
140 | </ul>
|
---|
141 | }
|
---|
142 |
|
---|
143 | # if you hate the squirly green bar down the left-hand side of the page,
|
---|
144 | # uncomment these lines:
|
---|
145 |
|
---|
146 | # _header_ {
|
---|
147 | # }
|
---|
148 |
|
---|
149 |
|
---|