FtTemplate::includeSub - jcobban/Genealogy GitHub Wiki

$template->includeSub($filename, $submarker, $after)

Up: class FtTemplate

This method is used to identify a file whose contents are to be inserted at the specified marker. If the specified file is found on the system this method returns true, otherwise it returns false. I would have preferred to call this function "include" but that is a reserved word in PHP 5.6, although it may be used for methods in PHP 7. When the template is converted into a string for delivery to the end-user, the file insertions identified by includeSub are performed first, followed by substitutions defined by method $template‑>updateTag or $tag->update, and finally substitutions identified by method $template‑>set or $template->includeSub(,,true). Each file identified by includeSub may itself contain insertion markers, but any insertion markers contained in the value passed to $template‑>set or in the file passed with $template->includeSub(,,true) are not replaced.

This class extends the implementation of Template::includeSub to support the application-specific template folder and the template naming convention for internationalization support.

This method has three parameters:

parameter description
$filename If the supplied value contains an insertion point $XXX or {{XXX}}), or an HTML tag () then this parameter contains the actual template contents to be inserted. This is not a duplication of the method $template‑>set because substitutions defined by $template->includeSub are made before substitutions provided by $templateTag‑>update or $template->updateTag or $template->set. Otherwise it is the filename,within the application template folder, to be embedded into the template. If the filename ends with "ll-CC.html" or "ll.html", where "ll" is an ISO language code and "CC" is an ISO country code then the two or five characters immediately before the period are assumed to be a language code. If the requested template does not exist, in other words the requested language is not supported, this language code is replaced by "en".
$submarker The insertion point name. This value is case-sensitive and it is recommended that it be all in upper case.
$after This is an optional parameter. Normally sub-templates are included before doing text substitution as defined by $template->set, $template‑>updateTag, or $tag->update, however if the sub-template file contains presentation information that is to have substitutions performed at run time, and therefore contains "$name" markers and those markers match $template->set('name') substitutions, either the sub-template must be included after text substitutions have been performed or all of the dollar signs must be escaped, for example "$code", so the dollar signs are preserved until run time. This is one of the reasons why it is recommended that marker names used by $template->set('NAME') be in all upper case, while those used for run-time substitution be in lower case. If you want the file to be included after substitutions are made add this parameter set to true, or use $template->set('MARKER',file_get_contents($filename)).

For example:

 $template‑>includeSub($popupsFileName, 
		       'POPUPS', 
		       true);

where the template file identified by $popupsFileName contains:

    <!-- select matching names dialog -->
    <form name='idirChooserForm$sub' id='idirChooserForm$sub'>
      <p class='label'>$surname, $givenname born $birthyear
      <p>
      <select name='chooseIdir' id='chooseIdir$sub' size='5'>
        <option value='0'>Choose from the following partial matches:</option>
      </select>
      <p>
        <button type='button' id='choose$sub'>Cancel</button>
      </p>
    </form>

This defines a dialog which is displayed at run-time by JavaScript. The alternative is to escape the dollar signs which must be preserved until run-time:

    <!-- select matching names dialog -->
    <form name='idirChooserForm\$sub' id='idirChooserForm\$sub'>
      <p class='label'>\$surname, \$givenname born \$birthyear
      <p>
      <select name='chooseIdir' id='chooseIdir\$sub' size='5'>
        <option value='0'>Choose from the following partial matches:</option>
      </select>
      <p>
        <button type='button' id='choose\$sub'>Cancel</button>
      </p>
    </form>

Next: $template->customization()

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