Links in Geneweb
Jean Vaucher (sept 2010)
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.
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.
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:
The URL for the crest is:
http://www.iro.umontreal.ca/~vaucher/Genealogy/Secrets/Armoiries_Vaucher_W.jpgThese 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=255Note 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:
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.
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=255Geneweb 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.htmlRemember 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.
file:///Users/jean/Documents/Genealogy/Secrets/Armoiries.htmlOn a PC (remember, I'm no expert), it might read:
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.
Typical content of "bases"
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=255If 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=255In 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.
<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"
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 (!!!).
- 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:
Note: For simplicity (and coherence) I suggest only using the m=SRC option.
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)
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:
changing: <img src="Armoiries_JV_w.jpg">
to: <img src="%sm=IM;s=Armoiries_JV_w.jpg" >
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.txt2) Within Index.txt, you should use the simplified wiki syntax for links, as in:
[[pierre/mouchon/Pierre Mouchon]] : Author of the Index to the Encyclopedia3) 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.txtand 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;"