Programming templates

From GeneWeb
Jump to: navigation, search


This page is for adventurous programmers. It exists only in english.

In order to produce the appropriate result, the gwd server of GeneWeb does either of two things:

  • it produces directly HTML code which is returned to the web client
  • it examines a text file which provides instructions for producing the desired output. These instructions can be viewed as a GeneWeb specific programming language. The produced output is in general HTML code, but can be anything else (Henri has built a few template files that produce a mixture of HTML style tags and LaTeX for further processing into pure LaTeX).

Some pages are produced with the first method, and cannot be changed short of changing the Ocaml code of gwd itself (list of such pages here). Other pages are entirely produced with the second method and allow for total user control through the template mechanism.

The template language has the following properties:

  • anything that is not an instruction (or its parameters) is text that is produced as output. (check CR LF behaviour)
  • output producing instructions begin with a & and terminate with a ;
    • execution flow: %if; %then; %else; %foreach; (each of these instructions open a block terminating with a %end;)
    • file handling: %include.file; %origin_file;
    • procedure definition: %define; (terminates with a %end)
    • variable definition: %let;variable;value of the variable, possibly GeneWeb code%in; (the definition holds within the currently opened block)
    • procedure call: %apply;
    • arithmetic: %reset_count; %init_count; %incr_count;
  • context setting or testing instructions do not begin with a % and terminate with a ;. See the expert page for a (possibly) complete list.
    • setting: family; father; mother; child; witness; relation; ... (list to be completed)
    • testing: has_parents; has_children; are_married; is_cremated; ... (list to be completed)
    • misc:

The best approach to discovering this programming language is to read the existing template files. All the instructions have a fairly self explanatory name. What may be needed is a full list of available instructions. (Note: does anybody know of a context aware text editor?).

==Short examples== BTW: Line-by-line comments would make these even more clear

%define;loc_long_married(xx)
  %apply;loc_married_to%with;%xx.sex%and;
    %if;(marriage_place = "")
      %if;(on_marriage_date = "")
      %else; <em>%on_marriage_date;
        %if;wedding_birthday; ([happy birthday to them!])%end;
        </em>
      %end;
    %else;
      %if;(on_marriage_date = "")<em>, %marriage_place;, </em>
      %else; <em>%on_marriage_date;
        %if;wedding_birthday; ([happy birthday to them!])%end;
        , %marriage_place, </em>
      %end;
    %end;
  %end;
%end;

Usage : <em>&nbsp;%apply;loc_long_married("child")</em>

  <ul>
    %if;has_birth_date;
      <li>%apply;capitalize(nth([born],sex)) %on_birth_date;
      %if;birthday; ([happy birthday to you!])%end;
      %if;has_birth_place; - %birth_place;%end;</li>%nl;
      %if;computable_age;<li>[*age] : %age;</li>%end;
    %else;
      %if;has_birth_place;
        <li>%apply;capitalize(nth([born],sex)) - %birth_place;</li>%nl;
      %end;
    %end;

The following example is an extract of the welcome page and shows that one must master HTML as much as this new GeneWeb programming language.

    <h3 class="with_picto" style=" background-image:url(%image_prefix;/picto_loupe.png)"> 
           [*search/case sensitive]0
    </h3>
      <form id="form-person" method="get" action="%action;">
        <div>
          %hidden;
          <input type="hidden" name="m" value="NG"%/>
          <span class="highlight">[person/persons]0</span>
          <br%/>
          <input type="text" name="fn" placeholder="[*first name/first names]0" size="25" 
            maxlength="200"%/>
          <input type="text" name="sn" placeholder="[*surname/surnames]0" size="25" 
            maxlength="200"%/>
          <br%/>
          <input type="text" name="n" placeholder="[*public name], [*alias] 
            %if;browsing_with_sosa_ref;, [n° Sosa relative to]%end; ..." size="53" 
            maxlength="200"%/>
          <input type="submit" value="Ok"%/>
          <br%/>
          %if;browsing_with_sosa_ref;%apply;display_sosa_ref%with;%sosa_ref;%end;%end;
        </div>
      </form>

GeneWeb Manual

Rembrandt Old Man Reading a Book.jpg

Use and manage genealogical databases

Technical annex