The Include command allows additional template files or sections to be included into the current template. Each included file or section is parsed as a separate entity, and its resulting output inserted into the current template output. This means that included template files will be cached separately, and only re-compiled when necessary.

There is just one command in the Include family - the Include command itself. It consists of the command followed by either an expression which should evaluate out to a valid filename, or the word section followed by a valid section name. Multiple files or sections can be included by separating the filenames or section names with commas, and the scope of each included file or section can also be changed.

For example:

{ include "file.tpl" }
{ include "file1.tpl", "file2.tpl", "file3.tpl" }
{ include file1, file2, file3 }
{ include lowercase(file1) }
{ include section NavigationBar }
{ include section NavigationBar, file1, "file2.tpl" }

Include commands can appear within other command structures, and within included files.

The scope of each included file or section can be set as desired. The "scope" is the behaviour of Variables present in the included file or section, relative to the file doing the including. There are three kinds of scope, with various keywords for each, to provide flexibility to cater for different tastes.

The scope of each included file or section can be set by using the syntax filename as scope or sectionname as scope.

For example:

{ include "file.tpl" as clean }
{ include "file.tpl" as clone }
{ include file1, file2 as clean, file3 as clone }
{ include section NavigationBar as clean }
{ include section NavigationBaras clean, file1 as clone, "file2.tpl" }

When including files, errors can arise for three reasons - either the file does not exist; or it is not readable; or it is outside of the path allowed for includes (which is set by the backend PHP programmer). If it is not readable, this is because of filesystem permissions. If it is outside of the allowed path, then there will be no way to tell if the file exists or not. Setting an allowable path is important for security reasons.

Therefore, it is a good idea to check whether the file is available before trying to include it. In such a situation, type checking should be used to gain information about the file.

For example:

{ if "file.tpl" is a ValidInclude }…
{   include "file.tpl" }…
{ endif }

{ if "file1.tpl" is not a ValidInclude or "file2.tpl" is not a ValidInclude }…
Cannot include files!
{ else }…
{   include "file1.tpl" as clean, "file2.tpl" }…
{ endif }