Geneweb Secrets
Links to Local Files
Jean Vaucher (sept 2010)

Index

Here we consider how best to add photographs and links to other resources in the Notes for individuals. Accessing files already available on the WEB, by using standard HTML, 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. 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.

Using Absolute URLs

Since Geneweb generates ouput in HTML format, the same URLs (web addresses) used for images and LINKs in other HTML documents should also work in Notes. This is true but only when absolute 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]

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.cgi
Images 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>

-- Back to the TOP --

Using Relative URLs

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):

	<img src="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.

-- Back to the TOP --

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"... 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.html
Remember 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.

-- Back to the TOP --

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 is:
   file:///Users/jean/Documents/Genealogy/Crest.jpg
On a PC (remember, I'm no expert), it might read:
   file:///c:/Genealogy/Crest.jpg

The Geneweb solution

Access to local resources in Geneweb relies on the use of a special macro "%s" along with conventions which permit "relative addressing" of files placed 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"
-- Back to the TOP --

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 absolute URL for the enclosing file. This includes the path to the host, the database name as well as any context information (such as language).

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=255
The 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=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.

"%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;".

-- Back to the TOP --

Links to local individuals

The "%s" macro simplifies the writing of links to persons in the same database. Remember, "%s" only specifies context. It must be followed by other parameters. For example:
	<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]]

Other uses of "%s"

We can get ideas on the variety and format of request that Geneweb accepts by examining the contents of the browser's URL field as we navigate a base and invoke different services.
List of birthdays: m=AN
<a href="%sm=AN">
Listing all Surnames: m=N&tri=A
<a href="%sm=N&tri=A">
Search by surname (for Vauchers) : m=NG
<a href="%sm=NG&n=vaucher&t=N">
Display of the descendant (m=D) tree (t=T) for individual i=255
<a href="%sm=D;i=255;t=T;image=on;v=4">
Display of the ancestors (m=A) for individual #402
<a href="%sm=A;i=402;t=T;image=on;v=5">
-- Back to the TOP --

Access to local IMAGES

Finally, we get to what we set out to do: adding our pictures to Notes. This can be done by using the "m=IM" addressing option:

   Including an IMAGE: "photo.jpg"
       1)  <img src="%sm=IM;s=photo.jpg">

and placing the file in a common directory

	..../bases/src/images
or 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,..).

Access to local HTML files

Local HTML files can be specified with the "m=SRC" or "m=H" options. In this case, the file name is specified differently from images: "v=..." rather than "s=..." and depending on the "m" parameter, different sets of local directories are searched for the file.

   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 (!!!).

Search directories for local HTML files.

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.

-- Back to the TOP --

Provision for multiple languages

Geneweb has facilites for multi-lingual operation based on translations of each page - all with the same name - placed in specific directories named according to the language of the files they contain (fr for French, en for English, ru for Russian, etc...). By convention, a default copy (often in English) is usually placed in the enclosing directory.

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)

Adapting a web document to Geneweb

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:

  1. Geneweb only handles image files and HTML files; I have had no success with other types, like: PDF, DOC, MOV or even TXT.
  2. Even a simple set of HTML pages and illustrations - like this tutorial - would need extensive transformation to fit in the Geneweb mold: all HTML files would need to have their names changed, all HTML links would need to be modified to include "%s" and images would have to be put in different directories.
Conclusion: The Geneweb facilities are mainly suited to images and indexes pointing to important people.

-- Back to the TOP --

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 should know how to do this. The only element missing is providing a visible link to your index.

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.gwf
It 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=BASE
The 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.txt
to 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.txt
Finally, within the Index, you should use the simplified wiki syntax for links, as in:
      [[pierre/mouchon/Pierre Mouchon]] : Author of the Index to the Encyclopedia
And 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>

-- Back to the TOP --

Thanks to Dimiter Skordev who gave me useful feedback on LINKS to local files.

Updated: dec 2011


Creative Commons License
GeneWeb Secrets by Jean Vaucher is licensed under a Creative Commons Attribution 4.0 International License.
Based on a work at http://www.iro.umontreal.ca/~vaucher/Genealogy/Secrets/GW_secrets.html