The $templates API variable provides access to all of your site’s templates. 

It provides the API functions available in the admin control panel under Setup > Templates. Use the $templates API variable to retrieve, modify, create or delete templates and control what fields are attached to them. On this page, we'll cover both the $templates API variable, as well as properties and methods common to individual templates.

The $templates API variable is one you aren't likely to use often in typical site development. Instead, this variable is more likely to be used in the development of custom modules or plugins to ProcessWire. In general site development, you will usually interact with templates just from the Admin > Setup > Templates section. However, should you need it, the $templates API variable is always available for you to use just like the other API variables.

$templates properties and functions

$templates->get("name")Return the template with the given name
$templates->name  Return the template with the given name
$templates->save($template)Save the given template instance.
$templates->delete($template)Delete the given template instance. Note that this will throw a fatal error if the template is in use by any pages.

Iterating $templates

If you iterate the $templates API variable, it will return each template object in alphabetical order.

foreach($templates as $template) {
    echo "<li>{$template->name}</li>";

Template objects

You can retrieve an individual template object from the $templates API variable by name (as shown above), or you can retrieve a template assigned to a page like this:

$template = $page->template; 

Regardless of how you retrieve an individual template, all templates share the same API properties and functions. These are documented in the table below.

Template properties and functions

$template->idGet or set the template's numbered database ID.
$template->nameGet or set the template's name.
$template->filenameGet or set a template's filename, including path (this is auto-generated from the name, though you may modify it at runtime if it suits your need).
$template->fieldgroupGet or set a template's Fieldgroup. Can also be used to iterate a template's fields.
$template->fieldsSyntactical alias for $template->fieldgroup. Use whatever makes more sense for your code readability.
$template->get($property)Get the value of a template's property (same as $template->$property)
$template->set($property, $value)Set the value of a template's property (same as $template->$property = $value).
$template->getNumPages()Return the number of pages using this template.
$template->save()Save this template to the database.

In addition, there are several optional/advanced properties may be used to modify the behavior of pages using an individual template. These are documented separately below.

Optional/advanced template properties

$template->cache_timeGet or set the number of seconds this template's output should be cached (default is 0). In newer API versions you can also use cacheTime (camelCase for better consistency).
$template->childrenTemplatesIDGet or set the template database ID that children of pages using this template default to. 0 is the default and indicates no selection. Set to -1 to disallow pages using this template from having children.
$template->allowPageNumGet or set whether pages using this template can have URL-based page numbers. Set to 1 for yes or 0 for no. Default is 0.
$template->urlSegmentsGet or set whether pages using this template can make use of URL segments. Set to 1 for yes or 0 for no. Default is 0.
$template->slashUrlsGet or set whether pages using this template should have URLs that end with a slash. Set to 1 for yes or 0 for no. Default is 1.
$template->redirectLoginGet or set what should happen when a user attempts access to a page using this template, and they don't have access to. Set to 0 to show the 404 page, or 1 to redirect to the login page. Default is 0.
$template->protocolGet or set what protocol is required to access pages using this template. If the user attempts access from the wrong protocol, it will be redirected to the right protocol. Set to 0 to allow either HTTP or HTTPS. Set to 1 to allow HTTPS only. Set to -1 to allow HTTP only. Default is 0.

Accessing a template as a string

Accessing a template as a string returns the template's name.

Using Templates and Fields from the API

In the ProcessWire admin, fields are added directly to templates. But it's a little bit different on the API side, where groups of fields (called Fieldgroups) are assigned to templates, and fields are assigned to Fieldgroups rather than directly to templates. This is to allow for future expansion potential by increasing the utility of templates and fieldgroups. The result is that, if you are working with templates and fields in the API, then you will also need to work with Fieldgroups. The interface to Fieldgroups is very simple, and nearly identical in most aspects to most other API variables. Following are examples that demonstrate how you would interact with templates and fields by way of fieldgroups.

We are looking at simplifying this interface to templates and fields so that you don't have to consider the Fieldgroup unless you want to.

Adding fields to an existing template

When we add fields to an existing template, we're technically adding them to the fieldgroup.

$template = $templates->get("some_template");
$template->fields->add("body"); // add some fields

Note that $template->fields and $template->fieldgroup are the same thing. Use whichever makes more sense with your syntax.

Creating a new template

To create a new template called "something", we first have to create a new Fieldgroup and add fields to it. Then we can assign that fieldgroup to the new template.

$fieldgroup = new Fieldgroup();
$fieldgroup->name = "something";
$fieldgroup->add("title"); // add some fields

$template = new Template();
$template->name = "something"; // must be same name as the fieldgroup
$template->fieldgroup = $fieldgroup;

Note that every template may also have a file associated with it in /site/templates/. When you create a new template, it will not create the file for you. If you want a file in your /site/templates/, then you should place it there manually and give it the same name as the template, but with the ".php" extension, i.e. /site/templates/something.php.

If there is an an example you'd like to see that isn't posted here, please post your request in the forum.

See Also

Template Files


No comments yet. Be the first to post!

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.