======Include Command======

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 [[PTPScript:Commands:Include#Scope|scope]] of each included file or section can also be changed.

For example:

<code ptpscript>
{ 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" }
</code>

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

====Scope====

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.

^ Scope Type Keywords ^^^^ Description ^
| ''shared'' | ''inherited'' | ''mutable'' | ''same'' | All Variables will be available to the included file or section, and changes will be reflected in the original file (default) |
| ''clean'' | ''fresh'' | ''separate'' | ''new'' | The included file or section will not inherit any Variables from the original file, and vice versa |
| ''clone'' | ''preserved'' | ''immutable'' | ''copy'' | The included file or section will inherit all Variables from the original file, but changes will not affect the original file |

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

For example:

<code ptpscript>
{ 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" }
</code>

<note tip>
Scope type keywords are case-insensitive, as is the ''section'' keyword.
</note>

====Errors====

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, [[PTPScript:Operators:Type Checking|type checking]] should be used to gain information about the file.

For example:

<code ptpscript>
{ if "file.tpl" is a ValidInclude }…
{   include "file.tpl" }…
{ endif }
</code>

<code ptpscript>
{ 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 }
</code>