Skip to content

PHP Programming Guide

James Cobban edited this page May 16, 2019 · 25 revisions

Up: Home

This section of the documentation describes how to write a PHP script to display an application specific page.

The classes that implement the behavior of the Genealogy application are in namespace Genealogy. So each script in the application identifies that it is in the Genealogy application by specifying namespace Genealogy;. While PHP handles references to functions that are globally defined, in particular the built-in functions of PHP, references to classes defined in any other namespace must be qualified. For example if the script uses or handles Exceptions then there must be a use \Exception; statement at the beginning of the script. The classes that are not specific to the Genealogy application are in other namespaces. In particular the Template engine is in namespace Templating. Most scripts only access the Template engine through the application specific class \Genealogy\FtTemplate but those scripts that access class \Templating\Template directly must add use \Templating\Template;.

In order that all of the pages on the Genealogy site have a similar appearance the logical structure of the common header portion is implemented by a common template. One of the objectives of using a template is to support communicating with users in their language of choice. The preferred language of communication is identified to the application by the parameter lang, whether passed in the URL for requests which do not alter the state of the database, or as the value of a field passed by method=POST for requests which do alter the database. The value of this attribute is the ISO 639-1 2-character language code. Therefore the script must have obtained the value of this parameter before invoking the template engine. Since most scripts have other parameters all of the parameter values are typically collected by code which looks like:

    $lang                       = 'en';

    foreach($_GET as $key => $value)
    {			    // loop through all parameters
        switch(strtolower($key))
        {		    // act on specific parameters
            case 'lang':
    	    {
    	       if (strlen($value) >= 2)
    		    $lang	= strtolower(substr($value,0, 2));
    	        break;
    	    }               // language
            // check other parameters ... 
        }		    // act on specific parameters
    }			    // loop through all parameters

Note that it is not desirable to validate and issue error messages in this loop because the language of communication has not yet been identified and the language-specific text of any such messages should be defined in the language specific template. Furthermore it is common for the valid values for one parameter to depend upon the values of other parameters. So, for example, the ISO language code is merely collected here and not validated except to ignore values that are less than 2 characters long and make the value lower case. Note that country-specific language codes are not currently supported. A country code specification may be included, for example “lang=en-US” or “lang=fr-CA” or “lang=es-MX”, but the country code is currently ignored.

All scripts invoke this common template by creating an instance of class \Genealogy\FtTemplate:

 $template	        = new FtTemplate("PageName$lang.html");

or

 $template	        = new FtTemplate("PageName$option$lang.html");

Where "PageName" is the name of the application specific template. A common reason for inserting a $option into the requested file name is to choose a different layout for users who are authorized to update the information on the page. So a template file "PageNameDisplayen.html" is used to present the information in such a way that the user cannot change anything, for example including readonly="readonly" in input fields and omitting buttons to request updates and possibly using different CSS classes, while "PageNameUpdateen.html" presents the information as a form with active input fields, checkboxes, selection lists, buttons, and so on. The class \Genealogy\FtTemplate is an extension of class \Templating\Template to implement specific functionality related to the Family Tree application. The client's requested language is passed in the template file name. The language specific template does not need to already exist. If it has not been created then the English version of the template is used. On November 29, 2018 there were base templates, defining the appearance of the common page header, for English, French, German, and Spanish.

The header section displayed for the site can be customized in the base template. The distributed version has three columns:

  1. The left column displays a menu button, commonly called a "hamburger" button, which looks like a stack of three thick lines.
  2. The next column is reserved for advertising.
  3. If there is sufficient room then social media links are displayed.
  4. The right hand column displays the logo of the site.

Common Page Header Appearance

The main section is displayed using style div.body. The page script fills this with page-specific content by identifying the application layout for the requested language through the filename passed to new FtTemplate.

class \Genealogy\FtTemplate attempts to locate the language specific version of the application layout template. If there is no language specific version this code selects the default English language version and apologizes for the lack of specific support using a message from the Language record for the requested language. On November 22, 2018 there were 12 languages with language specific apology text. The code works even if the requested language code is not defined by the ISO standard. The content of the Languages table is managed by page LanguagesEdit.php where the text of the language specific apology can be altered by authorized subscribers.

Apology for not supporting Polish

If the page requires specific CSS additions then the page PHP script should include:

$template->updateTag('otherStylesheets',
                     array('filename'   => $filename));

which causes the standard page template to expand the following element inside the <head> tag:

<link rel='stylesheet' type='text/css' href='$filename.css'
            id="otherStylesheets">

Note that the value of $filename does not include the filetype extension .css. Also if $filename is an array of strings then multiple style sheet links are generated. If the application specific script does not define an action to take for element "otherStylesheets" then the element is removed from the generated document.

Table of Contents:

Next: Javascript Programming Guide

Clone this wiki locally
You can’t perform that action at this time.