| Geneweb Secrets
Links to Local Files
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. Geneweb relies on different mechanisms which, unfortunately, are badly documented. From messages sent to 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. Its mechanisms 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 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.
For example, in the header of this page, I've included the Geneweb TREE icon from the site at INRIA by using the following reference using the icon's absolute URL:
<img src="http://pauillac.inria.fr/~ddr/GeneWeb/images/gwlogo.png">The same code used in the Notes field of a person will display the same icon.
Let's take this one step further. Assume that an HTML document (doc1.html) and an image (Crest.jpg) are in my web folder for Genealogy along with the CGI script that invokes Geneweb:
Generically, images, data files and programs are called resources and the (absolute) URLs for the resources above might be:
The document: http://www.iro.umontreal.ca/~vaucher/Genealogy/doc1.html The image: http://www.iro.umontreal.ca/~vaucher/Genealogy/Crest.jpg The script: http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgiImages or photos - such as the one at right - are added to a web page (in html format) by using an "img" instruction, with the URL of the image in the src field. The simplest format being:
<img src="URL">This is not a tutorial on HTML so we won't explain how to format HTML pages or what the other parameters do; but this is the code used for the crest (at right):
<img src="http://www.iro.umontreal.ca/~vaucher/Genealogy/Crest.jpg" align=right width="150">It uses the long URL we showed above. This <img...> code is also what we would type in the Notes field of a person to make the crest appear.
Most other resources, aren't meant to be displayed inside other pages or Notes; usually they are other pages whose content replaces that of the current page or is displayed in a new seperate window. In that case, we create a LINK through an ANCHOR (or <a...> instruction) which appears as underlined text in a different colour and will cause the new page to be feteched if the user clicks on the LINK. For example, the code for this LINK is shown below:
<a href="http://www.iro.umontreal.ca/~vaucher/Genealogy/doc1.html" target="other">LINK</a>Here the URL appears in the "href" field.
Note that we can have a link to an IMAGE... and much discussion on the Geneweb User site deal with that option ( <a href=... ):
<a href="http://www.iro.umontreal.ca/~vaucher/Genealogy/Crest.jpg" target="other">Show Crest</a>as in Show Crest which shows the image in a seperate window. But if you want the images to be part of your Notes, you must use <img src=... > and not <a href=... >
To be complete, a LINK to the CGI script is possible:
<a href="http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi" target="other">Geneweb</a>but without extra parameters, it doesn't do much... A form requesting more information would be returned:
Normally, the script request would include extra parameters to specify the database and a person ID:
<a href="http://www.iro.../~vaucher/Genealogy/geneweb.cgi?b=jv1;i=255"> ...</a>
So far our examples have relied on absolute URLs. These are necessary when a file on one computer needs to access something in another location. When both source and target are in the same directory on the same computer, we can use shorter relative URLs. For example, in our document (doc1.html), this shorter relative URL would be sufficient to access the image (Crest.jpg):
|Note: a Relative URL is missing the "http: //path_to_host_file" beginning. To complete a relative URL and obtain the absolute equivalent, browsers take the missing prefix from the URL of the enclosing document.|
Similarly, a link to person #255 in "doc1.html" could be written as:
<a href="geneweb.cgi?b=jv1;i=255"> ...</a>and the "Crest" could be included in the Notes of that person by writing:
<img src="Crest.jpg">Not only does relative addressing make for shorter references, it also makes a system more flexible. If the Genealogy folder is moved to another machine or directory, the absolute links need to change but the relative ones stay the same.
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"... In a request, the first identifier is assumed to be the name of the database. Geneweb interprets the string (correctly) as a request to return an HTML document with the information on individual #255 in database "jv1". Now assume a relative link to "doc1.html" is present in the Notes. The browser completes this relative URL with the starting part of the absolute URL above to obtain:
http://localhost:2317/doc1.htmlRemember that this is not sent to a web server (which normally listens on port 80); it is sent to Geneweb which will assume "doc1" to be one of its databases... which it isn't. Hence, an ERROR.
file:///Users/jean/Documents/Genealogy/Crest.jpgOn 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 page returned for person #255 from database "jv1" accessed from a server, the value of "%s" would be the coloured part of the invoking URL:
http://www.iro.umontreal.ca/~vaucher/Genealogy/geneweb.cgi?b=jv1;i=255The URL for a stand-alone request is different and "%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.
|"%prefix;":As Geneweb has evolved through several versions, macro names and conventions have changed. In some templates, "%s" doesn't work and one should use "%prefix;".|
<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. How to specify individuals is covered in more details in the chapter on Handling People's Names.
Starting with Geneweb 5.00, there is an even easier way to create links to persons in the same database.
|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]]If Pierre Mouchon is actually Pierre Henri Mouchon, the first names can be seperated by spaces; but other delimiters (like "_" or "-" or "+") have also been found to work. Assuming further that our man was oc=2 of several Pierre Henri Mouchons, we would need to specify him thus:
[[pierre henri/mouchon/2/Pierre Mouchon]] or [[pierre_henri/mouchon/2/Pierre Mouchon]]
Including an IMAGE: "photo.jpg" 1) <img src="%sm=IM;s=photo.jpg">
and placing the file in a common directory
..../bases/src/imagesor a private directory associated to a given database ( <db_name> ) :
..../bases/src/<db_name>/images ..../bases/src/jv1/images ( for our "jv1" example )
Geneweb looks for files in the private directory first then the common one.
You can also create LINKs to these local images. This is useful if the image is too large to fit into the Notes.
Link to same IMAGE: 2) <a href="%sm=IM;s=photo.jpeg"> ... </a>
Ideally you would like to have the image be displayed simultaneously with the Notes in its own window; but depending on the browser and how it is configured, this may not happen. For example, Firefox interprets such a link as a request for downloading the image. Geneweb does have a different parameter, "m=IMH," which ensures that a linked image is displayed (not downloaded). But strangely, the "m=IMH" parameter doesn't work with the <img...> instruction.
Another way to ensure that an image is always displayed in its own window - no matter the browser - is to create a separate HTML page with an <img src="%sm=IM;s=..."> instruction for the image as its only content. In the Notes, you would then LINK to that page and not the image. The next section shows how to do this.
Note: local access works for all image types (jpg, gif, png,..).
Links to HTML Files: "Bio.html and Famous.html" 3) <a href="%sm=SRC;v=Bio"> ... </a> 4) <a href="%sm=H;v=Famous"> ... </a>
Just to make life interesting, the files are specified using special conventions. First the parameter is "v=..." rather than "s=..." is used and depending on the "m" parameter, different sets of local directories are searched. Note further that the name as written above has no (.html) extension AND the 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: I have had no success with other file types like: pdf, mov or even plain text (!!!).
Note: For simplicity (and coherence) I suggest only using the m=SRC option.
For example, to have versions of an index of Famous people 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]. Assuming the index is for our "jv1" database, we would create the translaed versions of the "Famous.txt" file and place them in the following places:
.../bases/src/jv1/Famous.txt (English default) .../bases/src/jv1/fr/Famous.txt (in French) .../bases/src/jv1/de/Famous.txt (in German/Deutsch)
At first glance, Geneweb's facilities to make resources "local" seem reasonable - though hard to understand - but experience quickly shows that most auxiliary documents should probably be stored independently on a web server and accessed via standard URLs.
There are 2 main problems with Geneweb's mechanisms:
Usually, this is done on the Welcome page of your database, just like ROGLO with its "personnes célèbres"
As usual, with Geneweb, finding the Welcome page to modify is not obvious. The description on customization gives some ideas but the details are incomplete and somewhat out-of-date.
In previous versions of Geneweb, the default Welcome page was called "start.txt" and multi language versions were placed in directories called "lang" located in various places.
In Geneweb 5.00, this philosophy has been kept but the names have been changed: the Welcome page (actually, a template) is now called "welcome.txt" and the template directories are called "etc". For compatibility reasons, the current distribution still contains a ".../gw/lang/start.txt" file, but the current default Home page is "...gw/etc/welcome.txt". Further evidence that "etc" is the new directory for templates is that it contains 29 templates whereas "lang" only contains 7. [ Remember: the location of the ".../gw" and ".../bases" directories was covered above in this page. ]
We can obviously change the default page; but the best way to proceed is to use the Geneweb's customization features and insert our modified Welcome page in a directory with higher priority in the search chain. Others have described how customization works and I give a list of references in my Templates section. Here I simply describe how my own installation works.
To use different templates - including one for the Welcome page - you need to modify the configuration file for your database. If your database is called BASE, then the configuration file is:
.../bases/BASE.gwfIt is usually created with "gwsetup". You must add a line which gives the name of the folder that will hold your customized templates. I always use the database name, so you add the line:
template=BASEThe result is that Geneweb will search these directories - in order - for its templates:
.../bases/etc/BASE - Home of customized templates .../gw/etc - Home of default templates
My directory contains templates designed by Dominique Deram and I have modified the Welcome file:
.../bases/etc/BASE/welcome.txtto link to our index thus (m=SRC)
<div align="center"> <a href="%prefix;m=SRC;v=Famous">Index of Important People</a> </div>In another quirk to baffle users, "%s" doesn't appear to work in templates, the macro to use is "%prefix;"
The index file is:
.../bases/src/BASE/Famous.txtFinally, within the Index, you should use the simplified wiki syntax for links, as in:
[[pierre/mouchon/Pierre Mouchon]] : Author of the Index to the EncyclopediaAnd I've found it specially useful to point to family trees. Requests have the following format (m=D,t=T,...):
<a href="%sm=D;i=255;t=T;image=on;v=4">Descendants of the first Vaucher</a> or better: <a href="%sm=D;p=jehan+vaulchie;n=du+pasquier;t=T;v=4"> Descendants of the first Vaucher</a>
Thanks to Dimiter Skordev who gave me useful feedback on LINKS to local files.
Updated: dec 2011