GeneWeb - Customization of pages

This part indicates how to customize the welcome pages and the other
pages and to put associated pages. It is written for people having
handled {GeneWeb} already and who want
to go into the details.

<ul>

<li> <a href="#Wel">Welcome page</a>

<li> <a href="#Mac">Macros</a>

<li> <a href="#Ass">Associated pages</a>

<li> Customization of <a href="#All">all the pages</a>

</ul>


<a name="Wel"></a>
== Welcome page ==

The welcome page is built from text files, the files "start.txt"
provided with the distribution of {GeneWeb}. It is possible to
modify these files and/or make a specific version for a given
database.

<p>

These files contain HTML mixed with "macros" (see following section).
If you want to create such files or modify them, do not use an HTML
editor, but a normal text editor.

<p>

To build the welcome page of the base "foo", {GeneWeb} will
look for the following files, in this order:

<ul>

<li>bdir/lang/lg/foo.txt

<li>hdir/lang/lg/foo.txt

<li>bdir/lang/foo.txt

<li>hdir/lang/foo.txt

<li>bdir/lang/lg/start.txt

<li>hdir/lang/lg/start.txt

<li>bdir/lang/start.txt

<li>hdir/lang/start.txt

</ul>

where:

<ul>

<li>"bdir" = value of "-bd" of the command "gwd" (default: current
directory).

<li>"hdir" = value of "-hd" of the command "gwd" (default: current
directory).

<li>"lg" = current language.

</ul>

<p>

The files "hdir/lang/lg/start.txt" are provided with the distribution.
To make the custom file, the simplest way is to start from a copy of a
file "start.txt" which you will arrange as you want. If the
presentation of the files "start.txt" do not suit you, you can also
change them directly.

<p>

Warning however: from a version of {GeneWeb} to the other, the
files "start.txt" may have been improved. If you take a new version
and want to benefit from the improvements, look at the files
"start.txt" to see where they have been modified and include their
modifications in your customized files.


<a name="Mac"></a>
== Macros ==

As indicated previously, the files of welcome pages are not pure HTML.
They hold "macros". They are sequences beginning with the character
"%" and followed by a letter. Examples: "%s", "%x", etc.

<p>

These macros is replaced by values which depend on the context: name
of the base, language, number of persons in the base, etc.

<p>

There is also a particular processing for the brackets "[" and "]": if
the text between hooks is translated in the current language from the
lexicon (file "lexicon.txt") with the following modifications:

<ul>

<li>If there is a star after the opening bracket, the first letter of
the translation is capitalized.

<li>If the closing bracket is followed of a number, that correspond to
the N-2nd occurrence of translation (starting with 0), the occurrences
being separated by slashes. If this occurrence does not exist, the
first one is taken.

</ul>

<p>

To understand how the macros are used, the best is to look at the
files "start.txt" provided in the distribution.

<p>

Here the meanings of the macros "%":

<ul>

<li><strong>Base.</strong><br>

<ul>

<li>"<font size=+1><tt>%t</tt></font>": name of the base.

<li>"<font size=+1><tt>%f</tt></font>": in server mode, name of the
base, followed by the possible password (ex: "foo_xyzzy"); in CGI
mode, name of CGI command (ex: "gwd.exe").

<li>"<font size=+1><tt>%g</tt></font>": in server mode, like "%f"; in
CGI mode, name of CGI command followed by "?b=", the name of the base
and a semicolon (ex: "gwd.exe?b=foo;").

<li>"<font size=+1><tt>%s</tt></font>": value of "%f" followed by a
question mark and contextual variables (see below) followed by a
semicolon.  Ex: "foo?lang=it;iz=8233;".

</ul>

<li><strong>Count.</strong><br>

<ul>

<li>"<font size=+1><tt>%c</tt></font>": number of accesses to the
welcome page.

<li>"<font size=+1><tt>%q</tt></font>": number of requests.

<li>"<font size=+1><tt>%d</tt></font>": date of the first
consultation.

</ul>

<li><strong>Conditionals.</strong><br>

Conditionals start with "<font size=+1><tt>%I</tt></font>" followed by
a boolean expression (true or false) and end with "<font size=+1><tt>%E</tt></font>". The text between these two macros is
displayed if and only if the boolean expression is true. A boolean
expression is either:

<ul>

<li>"<font size=+1><tt>f</tt></font>" : we are "friend"

<li>"<font size=+1><tt>w</tt></font>" : we are "wizard"

<li>"<font size=+1><tt>j</tt></font>" : we are "wizard" just "friend"
(cf [[[start#Cnf/file a.gwf]]], "wizard_just_friend")

<li>"<font size=+1><tt>c</tt></font>" : we are in cgi mode

<li>"<font size=+1><tt>h</tt></font>" : there is a history file

<li>"<font size=+1><tt>l</tt></font>" : the browser does not treat tables

<li>"<font size=+1><tt>n</tt></font>" : there are notes for the database

<li>"<font size=+1><tt>t</tt></font>" : there is a search by nobility titles

<li>"<font size=+1><tt>z</tt></font>" : there is a person selected as
Sosa reference (see macro "<font size=+1><tt>%u</tt></font>")

<li>"<font size=+1><tt>a</tt></font>" : there is a [[[access#DBA/global access restriction]]] for the database

<li>"<font size=+1><tt>N</tt></font>" : contrary of the following expression

<li>"<font size=+1><tt>|</tt></font>" : logical "or" between the two
following expressions

<li>"<font size=+1><tt>&amp;</tt></font>" : logical "and" between the
two following expressions

</ul>

Examples:

<ul>

<li> display the text if there is a search by title: <font size=+1><tt>%It...%E</tt></font>

<li> display the text if we are neither "wizard" nor "friend": <font size=+1><tt>%I&amp;NwNf...%E</tt></font>

</ul>

<li><strong>Others.</strong><br>

<ul>

<li>"<font size=+1><tt>%r</tt></font>" followed by a name and a
new line: inclusion of the file "name.txt".

<li>"<font size=+1><tt>%b</tt></font>": value of the variable
"body_prop" of the file "foo.gwf" for the base "foo".

<li>"<font size=+1><tt>%h</tt></font>": contextual variables (see
below) in the form "&lt; input type=hidden name=var value=val&gt;".

<li>"<font size=+1><tt>%l</tt></font>": language.

<li>"<font size=+1><tt>%n</tt></font>": number of persons in the database.

<li>"<font size=+1><tt>%u</tt></font>" : person selected as Sosa reference.

<li>"<font size=+1><tt>%%</tt></font>": only one "%".

<li>"<font size=+1><tt>%[</tt></font>": "[".

<li>"<font size=+1><tt>%]</tt></font>": "]".

</ul>

</ul>

<p>

Some macros refer to <strong>contextual variables</strong>. They are:

<ul>

<li>b: in CGI mode, database name.

<li>lang: language.

<li>iz: number of the person taken as Sosa reference if any.

</ul>

<p>


<a name="Ass"></a>
== Associated pages ==

In your customized welcome page, you can put links to associated files
which will be treated by {GeneWeb} in the same way: the macros
will be transformed.

<p>

For example, if you want to put a special page of the famous persons
of your base, make a file named "famous.txt" in the directory
"bdir/lang/lg" or in the directory "bdir/lang" (see first section).

<p>

The request of access to "famous.txt" is: "m=H;v=famous". In the
welcome page, you will thus put:

<pre>
   &lt;a href="%sm=H;v=famous"&gt;Famous&lt;/a&gt; persons of my
   database.
</pre>

<p>

In "famous.txt", you can put links to persons of your base, independently
from his name and from the context, using the appropriate macros.

<p>

The particularly interesting macros are:

<ul>

<li>"<font size=+1><tt>%b</tt></font>" you can put in the tag
"&lt;body&gt;" writing it "&lt;body%b&gt;".

<li>"<font size=+1><tt>%s</tt></font>" you can use in links.

</ul>

Example of sentence in "famous.txt":

<pre>
   See my cousin &lt;a href="%sp=louis;n=de+bourbon;oc=5"&gt;
   Louis XIV&lt;/a&gt; and my
   &lt;a href="%sem=R;ep=john;en=smith;m=NG;n=louis+xiv;t=PN"&gt;
   relationship links&lt;/a&gt; with him.
</pre>

<p>

See how to make correct [[[links/links]]] to {GeneWeb}
pages as well.

<p>

Notice that the "advanced request" works like an associated file named
"advanced.txt".

<p>


<a name="All"></a>
== All the pages ==

The pages, the welcome page included, can be customized in three places:

<ul>

<li>You can add a file named <b>base.hed</b> (if "base" is the name
of your database) which will be inserted in all the headers of the pages
(between &lt;head&gt; and &lt;/head&gt;). Allow you to insert style sheets
for example. To be put in the directory "lang" and/or if you want that it
be different for the language "xy" in the directory "lang/xy".

<li>In the same way, you can add a file named <b>base.trl</b> which will
be inserted behind the GeneWeb copyright at each page.

<li>At last, you can set the variable <tt>body_prop</tt> of your file
<b>base.gwf</b> which will be inserted in the tag "&lt;body&gt;" of all
the pages. Useful to put a background color or image or to change the
colours of the displayed texts. See this [[[start#Cnf/section ]]] of the chapter "how to start with GeneWeb".

</ul>

<p>

<br>
<center>Return to [[[diruse/Directions for Use]]]</center>

