HTML Template Guide - jcobban/Genealogy GitHub Wiki

Up: Home

Each script uses one or more context specific templates which define the contents of the <main> tag within the body of the page. A template is a file using HTML5 syntax. Aside from the "page" and "dialog" templates, which define the common portions of a page and therefore are a complete HTML document, including the DOCTYPE comment, the <html> tag, the <head> tag, and the <body> tag, most templates only contain the portion of the document that is inserted into the <main> tag.

An application specific template contains some or all of the following pieces:

information about the pages which form the hierarchy of applications above the current page. This is contained in a <div class="hidden" id="breadcrumbs">. This is the information which is displayed when the user clicks on the "hamburger" icon. For example:

  <div class="hidden" id="breadcrumbs">
    <a href="/genealogy.php">
		Genealogy
    </a>:
    <a href="/Canada/CountriesEdit.php?lang=$LANG">
	    List of Supported Countries
    </a>:
    <a href="/genCountry.php?cc=$CC&lang=$LANG">
	    $COUNTRYNAME
    </a>:
  </div>

the portion of the template that defines the locale-specific presentation of information by the application. This is contained inside a <div class="body">. Note that the <h1> tag contains a link to a documentation page which described how this page is to be used. When the page is displayed this link is moved to the page menu. For example:

 <div class="body">
    <h1>
      <span class="right">
	<a href="/Canada/CountiesEditHelpen.html" target="help">? Help</a>
      </span>
      $DOMAINNAME: County Table Update
    </h1>
    $MSG
    $TRACE
...
  </div>

the locale-specific text of error messages displayed to the user. These may be used either by the Template engine or by the Javascript code running in the browser. For example:

    <div class="hidden">
      <span id="badPassword">
        Password must match the current password on the account. 
      </span>
      <span id="badEmail">
        Invalid email address.  
      </span>
 ...
    </div>

a section which contains the locale-specific layout of popup modal dialogs which are presented to the user by Javascript in the browser. Each dialog is contained in a <form>. This supports internationalization. For example the following defines the layout of a dialog which is displayed by displayDialog('RegDel$template', parms, this, confirmDelete);. The name and id of the <form> must contain a substitution to avoid creating a duplicate within the resulting Document Object Model (DOM):

    <div id="templates" class="hidden">
      <!-- template for confirming the deletion of a citation-->
      <form name="RegDel$template" id="RegDel$template">
        <p class="message">
            Are you sure you want to delete this registration?
        </p>
        <p>
          <button type="button" id="confirmDelete$regnum">
      	    OK
          </button>
          <input type="hidden" id="regdomain$template" name="regdomain$template"
      	        value="$regdomain">
          <input type="hidden" id="regyear$template" name="regyear$template"
      	        value="$regyear">
          <input type="hidden" id="formname$template" name="formname$template"
      	        value="$formname">
          &nbsp;
          <button type="button" id="cancelDelete$regnum">
      	    Cancel
          </button>
        </p>
      </form>
    </div>

the portion that provides the locale-specific text and layout of popup dialogs which describe the content and behavior of form elements such as input fields and buttons. Every named input field and button must have a corresponding popup help dialog. This supports internationalization. For example:

    <!-- The remainder of the page consists of context specific help text.
    -->
    <div class="balloon" id="HelpCode">
      This field contains a 3-character abbreviation for the county which
      is used to refer to this record.
      Except when adding a new county this is a read-only field.
    </div>

the specification of the scripts which implement the dynamic functionality of the page. These are loaded after the bulk of the page layout has been read so that they do not delay the display of the page, although the execution of Javascript code once the page is loaded may change aspects of the presentation. For example:

    <script src="/jscripts/CommonForm.js" type="text/javascript">
    </script>
    <script src="/jscripts/util.js" type="text/javascript">
    </script>
    <script src="/Canada/CountiesEdit.js" type="text/javascript">
    </script>

When the application specific template is inserted into the base page tag:

The text content of the <h1> tag, with substitutions filled in, is used to set the contents of the <title> tag in the <head> section. If the application specific template is embedded by a dialog layout master template then this title is also presented in a <h1> tag next to the main menu button and the <h1> tag is removed from the <main> section.
The contents of the site tree hierarchy in the page are copied from the <div id="breadcrumbs" class="hidden"> tag into the division which is displayed when the user clicks on the menu button. This is usually the first HTML text in an application specific template and looks like:

<div id="breadcrumbs" class="hidden">
    <a href="/genealogy.php?lang=$LANG">
	Genealogy
    </a>:
    <a href="/Canada/CountriesEdit.php?lang=$LANG">
	List of Supported Countries
    </a>:
    <a href="/genCountry.php?cc=CA&amp;lang=$LANG">
	Canada
    </a>:
</div>

Any link to a help page that is in the <h1> tag is copied to the division which is displayed when the user clicks on the menu button. The name of the Help page is typically the name of the page followed by the Internet Best Common Practices 47 language code and the file-type .html. This supports context specific help text. A typical <h1> tag contains the page title and the help link as follows:

  <h1>Ontario
    <span class="right">
	<a href="/Ontario/genOntarioHelpen.html" target="help">? Help
	</a>
    </span>
  </h1>

The presentation of the layout is contained within a <div class="body"> which permits customizing the appearance through CSS.
The insertion point $TRACE is replaced by any non-fatal warning diagnostic messages. The PHP script can generate output that appears here by appending HTML, for example a paragraph tag, to the global $warn. The warning text is displayed in class “warning” which defaults to dark yellow text.
The insertion point $MSG is replaced by the contents of the $msg global variable embedded in a paragraph with class “message” which displays the text in red.
For each named form element there should be a <div class="balloon" id="Helpinputname"> which contains the popup which is displayed if the user holds the mouse over the input field or touches the element on a touch-sensitive device. Note that this applies to all form input elements, including buttons, textareas, radio buttons, check boxes, and selects. For example:

    <button type="button" name="Delete" id="Delete">
        Delete
    </button>

requires that the following division be defined:

    <div class='balloon' id='HelpDelete'>
        Click on this button to delete the specific
        sub-district from this district.
    </div>

As discussed in more detail in the description of the class Template there are two kinds of substitutions that are used to customize the presentation of a template:

Simple text substitutions, usually identified using PERL/PHP style insertion markers $NAME.
HTML-tag-based substitutions in which individual tags, identified by their id attribute are customized.

To support the latter style the template engine parses the template to create a Document Object Model (DOM). However while this parser understands many of the formal idiosyncrasies of HTML, for example that tags with VOID content, such as the <input> tag, do not have ending tags, it is not as tolerant of genuine violations of formal syntax which browsers traditionally give silent warnings for. In particular the output is not guaranteed to be correct if there are missing closing tags. Therefore the template parser detects and flags missing closing tags

Templates for tabular displays are designed to present a common user interface to deal with the case where there are more lines to display than will fit in the browser view-port. Pages which wish to take advantage of the common support for paging through such tables identify the HTML <table> which is to be paged through by the identifier id="dataTable". Such scripts typically accept parameters LIMIT= and OFFSET= to identify the portion of the table to display. The <table> is preceded by a block of HTML like:

       <div class="center" id="topBrowse">
        <span class="left" id="topPrev">
      	  <a href="$NPURI$NPAND$NPPREV">&lt;---</a>
        </span>
        <span class="right" id="topNext">
      	  <a href="$NPURI$NPAND$NPNEXT">---&gt;</a>
        </span>
      	  displaying rows $FIRSTOFFSET to $LASTOFFSET of $TOTALROWS
        <div style="clear: both;"></div>
      </div> <!-- end of top page scroll -->

A similar block of HTML can be placed after the table display distinguished by ids starting with "bot".

The common dynamic functionality manipulates this header and trailer code in several ways:

The displayed width of the divisions "topBrowse" and "botBrowse" is adjusted to match the minimum of the width of the table "dataTable" and the width of the view-port.
If the table is wider than the view-port when the user scrolls the view-port left and right these divisions are also shifted so that the entire width is visible.
If the span "topPrev" is displayed, that is the display is not at the beginning of the table, then the key PgUp follows the link in the contained <a> link.
If the span "topNext" is displayed, that is the display is not at the beginning of the table, then the key PgDn follows the link in the contained <a> link.

An example of this is:

Scrolling Tables

The templates for the sample site are kept in the folder /templates. This is where the class FtTemplate looks for them, although the base class Template requires complete file names. If you look at that directory with your browser the display of the contents is adjusted so that a script is used to open the template. This script displays how the template looks when using the main CSS file for the site on the left side but with the substitution points left in their raw form. The special $MSG and $TRACE substitutions are displayed with the type highlighting specified by the CSS. The right side of the display contains the raw HTML,XML, or JSON of the template with color coding of syntactic elements.

Viewing a Template

It is useful to use this tool to look at any template that you add or modify so you can see issues immediately such as improperly nested tags.

In general the filename of an HTML template as supported by class FtTemplate has the following structure:

Each PHP script uses multiple templates depending upon the locale. Each template controls the appearance of the page for each locale including headings, labels, message texts, and the appearance of dates. The first part of the name corresponds to the name of the script. For example the first part of the templates used by the script Location.php is 'Location'.
Some PHP scripts use parameters to identify the specific data that they act on. For example the script CensusForm.php is used to display a complete page from the population schedule of any of the censuses of Canada. So the enumeration year qualifies the template name. For example templates starting with 'CensusForm1881' display information from the 1881 Census of Canada.
Many census forms present differently depending upon whether or not the current user has permission to update the database, or is restricted to merely viewing the contents. For example the script Location.php uses templates starting with 'LocationUpdate' if the current user has permission to update the instance of class Location but uses templates starting with 'LocationDisplay' for casual visitors.
Any user, including casual visitors, can specify the locale including the preferred language of communication. This is represented by an ISO 639-1 two-character language code, optionally qualified by an ISO 3166 country code. Examples of such codes include 'en', 'fr', 'es-MX', 'fr-CA', and 'de-AT'. For example the page displayed by script 'Person.php' is customized by templates 'Personen.html', 'Personfr.html', 'Persones.html', and 'Personde.html'. The main menu displayed for each page lists all of the alternate languages supported for that page.
In addition there are a set of general translation tables for each supported language and dialect whose names are 'tranTabll.html' where ll is the language code specified in the previous point.

For example:

Template Name	Description
`LanguagesDisplayen.html`	template for displaying the defined Languages to a casual visitor using English
`LanguagesUpdatefr.html`	template for displaying the defined Languages to a registered user using French
`CensusForm1911Updateen.html`	template for displaying a page of the 1911 census of Canada to a registered user who has authority to update that page, using English
`CensusForm1911Displayen.html`	template for displaying a page of the 1911 census of Canada to a casual visitor, using English
`CensusForm1911Proofreaden.html`	template for displaying a page of the 1911 census of Canada to a registered user can review and suggest corrections to that page, using English
`Personde.html`	template for displaying the information about an individual in the family tree and his/her parents, spouses, and children in German
`Personen-US.html`	(hypothetical) template for displaying the information about an individual in the family tree and his/her parents, spouses, and children in American English

Next: Template Translation Tables

HTML Template Guide - jcobban/Genealogy GitHub Wiki

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️