Links in Geneweb

Jean Vaucher (sept 2010)

Index

Here we consider how best to add photographs and pointers to other resources in the Notes for individuals. Using standard HTML to access files already available on the WEB is relatively easy but integrating your own local resources in a portable way is surprisingly difficult.

Ideally, you would like to use relative links and references so that you don't need to change them when you move a database or change the mode of operation (stand-alone/web). Unfortunately, the techniques that work with normal web pages don't always apply to Geneweb which employs its own mechanisms. Unfortunately, those are badly documented. Reading messsages on the User Group and through trial and error, I've come to understand how Geneweb works and I will explain how to integrate local HTML files and images (JPG, GIF, etc...) in a seamless manner.

But I've also come to understand Geneweb's limitations. The mechanisms provided appear to have been designed to facilitate customization of the basic templates. They are perfect to incorporate images in Notes and to add arbitrary links between individuals. They also make it easy to add simple HTML files which index interesting people. But, for different types of files and anything of any complexity, the best solution is to put the files on a web server and access them via normal URLs.

First, we consider obvious approaches and explain why they don't always work. Then, we will introduce Geneweb's special macros and conventions.

Using Absolute URLs

Since Geneweb uses HTML, the same code used to display images or create LINKs in other HTML documents should work when used in Notes. This is true BUT only when absolute URL addresses are used. For our purposes, an absolute URL starts with "http://" and has the following syntax:
    http://path_to_host[:port]/path_to_web_file[?parameters]
Some parts are optional. If ":port" is absent, port 80 is used by default and parameters are only used when the destination file is a program to be executed instead of data to be returned. The path_to_host uses "." as delimiter whereas path_to_web_file uses the slash ("/"). Typical uses of URLs are for images or links.

For example, I've included the Geneweb TREE icon in the header to this page by using the following HTML code... and this would work similarly if written in the Note field.

    <img src="http://pauillac.inria.fr/~ddr/GeneWeb/images/gwlogo.png">
The following sets up a link to Geneweb pages on someone else's database (using the <a href=... HTML code). It links to my eldest known ancestor and this code could appear in Notes on your database (should you so wish...).
    <a href="http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi?b=jv1;
        p=jehan+vaulchie;n=du+pasquier"> The first Vaucher </a>
You can link to people on ROGLO, the same way:
    <a href="http://roglo.eu/roglo?p=albert;n=einstein"> Einstein </a>
Try it here: Einstein

Nothing stops you from using the same techniques to accessing resources on your own server (if you have one). You can put all your pertinent photos and documents in a web folder and refer to them using absolute URLs.

However, absolute URLs are too rigid. If you move to another server; you have to change the address in every link that you added. On traditional web sites, the solution is to use relative links for local resources: partial paths from the current file to the resource. These don't change when the database is moved as long as the resource folder is moved as well.

Using Relative URLs

To explain how this works, I have a folder called "Secrets" in my usual Genealogy Web directory:
	http://www.iro.umontreal.ca/~vaucher/Genealogy/Secrets/
This folder contains an (abridged) HTML document about our family crest as well as some images referenced in that document. You can see the folder contents by clicking here.

The URL for the document is:

    http://www.iro.umontreal.ca/~vaucher/Genealogy/Secrets/Armoiries.html

The URL for the crest is:

    http://www.iro.umontreal.ca/~vaucher/Genealogy/Secrets/Armoiries_Vaucher_W.jpg
These are absolute URLs. In "Armoiries.html", we use a shorter Relative URL to access the images. It is equivalent to the longer one above:
	<img src="Armoiries_Vaucher_W.jpg">
Note: a Relative URL is missing the "http://path_to_host_file" beginning. Browsers use the Absolute path of the enclosing document to complete Relative URLs and obtain the equivalent absolute address.

Relative URLs in Notes are interpreted the same way. For example, the (absolute) URL used to access individual 255 in my database (jv1) is:

    http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi?b=jv1;i=255
Note that both the Geneweb request and the URL to Secrets have the same beginning (because the CGI is in the same directory). Therefore, if we use the relative addresses below in person #255's Notes:
    ...More on the  <a href="Secrets/Armoiries.html">Vaucher </a> crest...
The browser would interpret it as:
     <a href="http://www.iro.umontreal.ca/~vaucher/Genealogy/Secrets/Armoiries.html">

which is correct and would not need to be changed if we moved the database elsewhere.... as long as we moved the "Secrets" folder as well.

Stand-alone operation

Unfortunately, when we move a Geneweb database (and its multimedia resources) from a server to a PC (or MAC) in stand-alone mode, the relative links stop working.

This is because, in this mode, the URL of a Geneweb page does not designate a starting (cgi) file from which a relative path could be applied; rather it points to the internet port (#2317) on the local host where Geneweb is waiting for requests. Take the previous example, accessing my "jv1" database - but, this time, running in stand-alone mode. The request would read:

    http://localhost:2317/jv1?i=255
Geneweb receives the string "jv1?i=255"... And, since Geneweb always takes the first identifier in the received parameter string to be the name of the database, it interprets this (correctly) as a request to return an HTML document with the information on individual #255 in database "jv1". Now assume a relative link to "Secrets/Armoiries.html" is present in the Notes. The browser combines this relative URL with the URL of the containing document to get:
    http://localhost:2317/Secrets/Armoiries.html
Remember that this is not sent to a web server (which normally listens on port 80); it is sent to Geneweb which will interpret it an operation to be done on database "Secrets"... which doesn't exist. Hence, producing an error.

Use of "file" URLs

When people only use Geneweb locally to manage their genealogical information, they can use a different form of absolute URL which points directly to local files. These URLs start with "file:///..." instead of the usual Internet URL which starts with "http://..." [Note the extra slash !!!]. On my MAC, the local URL for my Family Crest file is:
   file:///Users/jean/Documents/Genealogy/Secrets/Armoiries.html
On a PC (remember, I'm no expert), it might read:
   file:///c:/Genealogy/Secrets/Armoiries.html

The Geneweb solution

The solution lies in the use of a special macro "%s" along with conventions which permit "relative addressing" of files in selected "bases" directories. By placing your photos and other files in these special directories, you can have links that will work independly of mode or where the "bases" directory is placed.

As mentioned in my notes on files and directories , Geneweb uses 2 basic directories: "gw" for the common system stuff (programs, utilities and templates) and "bases" for all user data and index files. Initially, if you aren't careful, you can start creating databases in the system directory, so that effectively "gw" and "bases" are one and the same. To avoid confusion, the two directories should be kept distinct. In addition, it is best to retain their usual names.

  • src: is the main directory where images and user-written HTML files should be placed. Actually they would be in a sub-directory bearing the name of the database (like jv1)
  • lang: is another directory where user-written HTML files can be placed

Typical content of "bases"

The "%s" Macro

As explained in the documentation macros are character sequences, like "%s" that are replaced by a value when Geneweb generates a page to be sent sent to the browser. Geneweb has many such macros but the most useful one for users is "%s". Normally, it is used at the beginning of an address field for an image (src="%s...") or a link (href="%s..."). "%s" will be replaced by the beginning ot the URL for the enclosing file. This includes the path to the host, the database name as well as any context information (such as language). The form of "%s" will differ depending on the mode.

In the two following examples the value of "%s" would be the coloured part of the invoking URL. First, consider an individual #255 accessed from a server:

    http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi?b=jv1;i=255
If the same individual is accessed in stand-alone mode, "%s" takes on a different value. This example also has French as selected language:
    http://localhost:2317/jv1?lang=fr;i=255
In conclusion, "%s" represents the current database, path and context of a request. But the replacement ONLY occurs in pages that are sent by Geneweb: those created from a template - including the Notes field.

Links to individuals

In requests to Geneweb, "%s" only specifies context. To indicate what we want Geneweb to do, "%s" must be followed by other parameters. For example, in a user-created list of Famous people, we could combine "%s" with the identification of a person to create links:
	<a href="%si=255">The first Vaucher</a>	
	<a href="%sp=pierre;n=mouchon">Pierre Mouchon</a>	
using either a person's number (i=255) or his name.

Starting with Geneweb 5.00, there is an even easier way to create links - using Wiki syntax

The syntax [[first_name/surname/oc/text]] makes a link to the individual with key (firstname, surname, oc) with 'text' displayed. Simplified syntaxes: if oc = 0, [[fn/sn/t]] can be used, and [[fn/sn]] is equivalent to [[fn/sn/0/fn sn]].

This is the best way to reference "Pierre Mouchon"

		[[pierre/mouchon/Pierre Mouchon]]

Access to local data

To access local files or photographs, you must use the parameter "m" which indicates the type of document (i.e. m=IM for an image), followed by the file name: s=... or v=.... Examples show how this works:

   Display of an IMAGE: "photo.jpeg"
       1)  <img src="%sm=IM;s=photo.jpeg">
   Link to same IMAGE:
       2)  <a  href="%sm=IM;s=photo.jpeg"> ... </a>

   Link to an HTML File: "Bio.html or Famous.html"
       3)  <a href="%sm=SRC;v=Bio"> ... </a>
       4)  <a href="%sm=H;v=Famous"> ... </a>

Geneweb's way of specifying the name of an HTML file is peculiar: the name written has no (.html) extension and your HTML file must use the ".txt" extension, as in "Bio.txt" instead of "Bio.html". One can only guess that the ".txt" file serves a input to the dynamic generation process which transforms it into an ".html" file which is then returned to the user.

Note: the only types of files for which this local access works are images (jpg, gif, png,..) or html files. I have had no success with other types like: pdf, mov or even plain text (!!!).

Where to put the local files ?

In order for the preceding requests to work, the files must be placed in specific directories whose path depends on the name of the database. Below, <db_name> will represent this name.

  - Image files should be placed in:

	..../bases/src/<db_name>/images
  - Depending on the "m" parameter, html files can be put in 2 different places:

m=SRC : ..../bases/src/<db_name>
m=H : ..../bases/lang

Note: For simplicity (and coherence) I suggest only using the m=SRC option.

Provision for multiple languages

Geneweb's convention is to allow multiple sub-directories - one per language - wherever ".txt" or "html" files are stored. The directories are named according to the language of the files they contain (fr for French, en for English, ru for Russian, etc...). The convention is to have one (default) copy of a file outside the directories and to have translated versions (with the same name) in the corresponding sub-directories.

For example, to have versions of our Famous people file in English (default), French and German, we would create 2 directories named "fr" and "de" in the "..../bases/src/<db_name>" folder [No need for "en" since it will be the default]. Then we would create the 3 versions of the "Famous.txt" file and place them in the following places:

	.../bases/src/<db_name>/Famous.txt	    (English default)
	.../bases/src/<db_name>/fr/Famous.txt	    (French)
	.../bases/src/<db_name>/de/Famous.txt	    (Deutsch)

Adapting a web document to Geneweb

Let's get back to our example of Armoiries.html with references to 2 images. Usually, the 3 files would be in the same directory; but if we want to make them local to Geneweb, several things would need to be done:

  1. the two images should be placed in the ".../bases/src/<db_name>/images" directory
  2. the Armoiries.html file should be renamed Armoiries.txt and placed in ".../bases/src/<db_name>" - a different directory
  3. all the "<img>" local references in Armoiries.txt all need to be changed by inserting "%sm=IM;s=" in the src field:

    changing: <img src="Armoiries_JV_w.jpg">
    to: <img src="%sm=IM;s=Armoiries_JV_w.jpg" >

Comment: The bother of fitting even this trivial document (and its illustrations) into the Geneweb mold led us to conclude that most external documentation for a database should be stored independently on a web server. The exceptions being illustrations and indexes pointing to important people.

Making your own index

When your database grows past a certain size, it becomes useful to create your own index of key individuals: oldest ancestors, prominent people or first immigrants. The index will be an HTML file with descriptive text and links to the individuals.

By now, you have most of the information necessary to do this. Let us assume that your database is called MYBASE and the index will be called "Index"

1) You will need an HTML file which you will call "Index.txt" and which you will place in directory:

.../bases/src/MYBASE/Index.txt
2) Within Index.txt, you should use the simplified wiki syntax for links, as in:
      [[pierre/mouchon/Pierre Mouchon]] : Author of the Index to the Encyclopedia
3) All that remains is allowing users to access the index.

The best way is to place a link on the HOME page of your database, just like ROGLO with its "personnes célèbres"

But where is the template which serves as your HOME page. The standard documentation on customization gives some indication here and here.

In my own installation, I use custom templates where the HOME page is called "welcome.txt". These templates are placed in a sub-directory of "bases" which has the name of my database. In our example (MYBASE), the page would be in:

	.../bases/etc/MYBASE/welcome.txt
and it contains a reference to the index thus:
   <div align="center">
   <a href="%prefix;m=SRC;v=notables">Index of Important People</a> 
   </div>
In another quirk to discourages users, "%s" doesn't appear to work in templates, the macro to use is "%prefix;"