Template::includeSub

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

Up: class Template

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. $template->includeSub($filename,'submarker',true) is functionally equivalent to $template‑>set('submarker', file_get_contents($filename)).

This method has three parameters:

parameter	description
$filename	the filename to be opened. This should be an absolute file name within the templates directory of the site. For example $document_root . '/templates/filename.html'. To facilitate using appropriate tools for editing the template it should have a suitable file extension. 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 includeSub are made before substitutions provided by $templateTag‑>update or $template->updateTag or $template->set.
$submarker	the insertion point name. For example if this file is to be included in the master template pagell.html this should be 'MAIN'. 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, either the sub-template must be included after text substitutions have been performed or all of the $ signs must be escaped, for example \$code, so the $ signs are preserved until run time. 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. If this file were included before text substitutions were made all of the run-time insertions would disappear. 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->set($marker, $value, $doSubs)