6. Includes

Includes are one fundamental way of leveraging the Templation hierarchy. Templation includes are similar regular PHP includes except your include path is dynamically extended to all the ancestor directories of the current page. You can include the nearest file of a given name from a template using an include tag of the form <%%inc filename> as described on the templates page.

a. Hierarchy searching

Templation includes are located by first searching the 'includes' directory of every ancestor directory to the current page. Searching progresses up to the website root directory, and then finally to the data/includes directory in the data repository. The file is located from the bottom up so that the most specific file with that name is found.

b. API (for widgets)

Simple includes from templates are useful, but they don't begin to capture the possibilities that Templation offers. In fact, they are really just syntactic sugar for a very simple widget (tpl_include.php). When writing widgets, finding files in the includes hierarchy is one of the most useful functions. The Templation_Widget includes this member function:

Templation_Widget::findIncludes($filename[, $number[, $directory]])

Where $filename is the filename relative to the includes directory. The filename may include a path if you wish, which is useful for organizing includes according to which widget uses them. $number will allow you to find more than one include files going up through the hierarchy (for example see tpl_nav.php widget). $directory is an optional starting directory to search in; otherwise, it just starts in the current directory the web server is loading a page from. Remember that an 'includes' directory will be appended to the starting directory, so you should never pass in an includes directory directly, rather specify an actual content directory. findInclude() will return either an absolute path if one exists or false if no file is found.