Content template files
From phpCMS
Contents |
[edit] Using content template files
[edit] Introduction
Templates (i.e. template files (.tpl) as opposed to layout templates for a website design) represent a general frame, into which the actual content of the site is inserted. A phpCMS template is in principle an ordinary HTML file, however it needs to be extended with special instructions for the phpCMS parser.
In such a template one defines placeholders. During parsing by phpCMS these placeholders are replaced by the content which one defined for this placeholder in an according content file. By the use of templates, the layout is separated from the content. This makes later changing of the layout very easy, quick, and comfortable, as one only has to change the template (see more detailed discussion below).
[edit] A very simple example
To make the working principle of phpCMS clear, here is a simple template as an example:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
<h1>{TITLE}</h1>
<p>
{CONTENT}
</p>
</body>
</html>
If a browser requests a file, it is always a so-called content file. First it is checked which project file is needed. Then from this project file the template name is determined. Now this template is used to process the content file requested by the browser. The result of this process is a HTML document, which could have the following content:
<html>
<head>
<title>A simple example</title>
</head>
<body>
<h1>A simple example</h1>
<p>
This text was read from the content file and filled in
to the according place in the template.
</p>
</body>
</html>
[edit] The predefined tag $home
The predefined tag $home is usable in templates too, if it is defined in the project file. The use of this predefined tag is always recommended if images, style sheets, or external JavaScripts are referenced in a template. Thus one can avoid the use of absolute pathnames.
Absolute pathnames have the crucial disadvantage that a directory cannot be moved without changing all the links in all the files.
Example:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
<h1>{TITLE}</h1>
<p>
{CONTENT}
<img src="$home/images/image.png" alt="Image" />
Home directory of the project: $home
</p>
</body>
</html>
[edit] The predefined tag $self
This predefined tag is declared automatically by the phpCMS parser with the name (including the path) of the concerned content file. The use of this predefined tag is helpful if you want to send a parameter to the current file, as it has not to be changed if the content file is moved or renamed.
Example:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
<h1>{TITLE}</h1>
<p>
{CONTENT}
Name of the currently active file: $self
</p>
</body>
</html>
[edit] Sub-Templates
Within a template one can include further templates. These are called "sub-templates". Sub-templates behave like templates. This also implies that one can include a sub-template into another sub-template. One should always make sure that there is no recursion, as the parser would not recognize this.
The use of sub-templates is recommended if HTML code blocks would be re-used several times in the same or in different templates. To include a sub-template, the following instruction is used:
{TEMPLATE FILE="/demo/sub_template.tpl"}
To be noted that there has to be exactly one space between TEMPLATE and FILE. Furthermore, double quotation marks have to be used to make sure that the template is found.
Either absolute or relative paths may be used here, and the use of the predefined tag $home is also allowed.
Examples:
{TEMPLATE FILE="/demo/sub_template.tpl"}
{TEMPLATE FILE="$home/sub_template.tpl"}
{TEMPLATE FILE="sub_template.tpl"}
[edit] Advantages of sub-templates
In phpCMS different templates can be involved in the "making" of a page, e.g. header.tpl, main.tpl, footer.tpl, meta.tpl as shown in the demo delivered with the phpCMS package.
One could condense those three templates into only one template (which then must be the one referenced in the project file), or one could subdivide them into even more different (sub-) templates.
The following section will show the advantages of maintaining a multiple-template structure well adapted to the website project.
Here is an example for a (minimal) complete template:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
{CONTENT}
</body>
</html>
Furthermore there are some content files with the content for the placeholders {TITLE} and {CONTENT}. A content file could look like this:
{PROJECT}
./template/home.ini
{TITLE}
My Web Page
{CONTENT}
This is a test page.
This here is the content, i.e. the part shown in the browser,
defined in a static way in the content file.
Beside the content files (.htm) with static content defined in a placeholder {CONTENT}, there are often also pages with dynamic content produced by scripts, e.g. an embedded forum.
Here is an example for such a content file calling a forum script:
{PROJECT}
./template/forum.ini
{TITLE}
My Forum
{SCRIPT_FORUM}
$home/forum/forum.php
There is no placeholder {CONTENT} in the content file with fixed text, but a placeholder {SCRIPT_FORUM} instead.
The fact that the (otherwise freely selectable) name of this placeholder starts with {SCRIPT... tells phpCMS that this is not a "normal" placeholder with fixed (static) text, but that the content of this placeholder, "$home/forum/forum.php" in this case, represents the path to a PHP script that it should execute and take its output as content of the placeholder {SCRIPT_FORUM}. If one now places the placeholder {SCRIPT_FORUM} somewhere in the page template, phpCMS will insert the output of the forum script at this location of the page.
There now is a new placeholder called {SCRIPT_FORUM}, but it should only be shown on one page of the website, the forum page. It has no relevance for any other page of the website.
That means that one needs a relating page template comprising a placeholder {SCRIPT_FORUM} in addition to or instead of the {CONTENT} placeholder. To create it, one copies the home.tpl to a new template forum.tpl and changes the respective line to obtain:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
{SCRIPT_FORUM}
</body>
</html>
Everything is running fine and the website author is happy. :-))
But with time one gets more and more page templates, because one needs another one for showing the sitemap instead of the {CONTENT} placeholder, one more for the search facility and so on, and one ends up with a multitude of page templates which only differ by the placeholder {CONTENT} being replaced by a different one.
And when one now wants to change the layout of the website, e.g. include a background image in all the pages, one has to take all these page templates, i.e. the "normal" one, the one for the forum, the one for the sitemap, the one for the search, the one for ..., and change the line
<body>
to become
<body background="backgroundimage.jpg">
meaning one must always remember to change all those template file to achieve a change on all the pages.
Pls. note that a background image these days is normally included via CSS (Cascading Style Sheets) which makes a change easier, but this example shall only show the principle.
And that exactly is why work becomes much easier if one separates the one template into several parts.
Supposing the simple template from the beginning of this example would have been separated into three parts:
header part:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
middle (main) part:
{CONTENT}
footer part:
</body> </html>
and they are saved as three different files, e.g. header.tpl for the header part, footer.tpl for the footer part, and main.tpl or home.tpl (names again are freely selectable!) for the remaining middle (main) part, the latter one should become the main template, and header.tpl and footer.tpl sub-templates.
phpCMS parses the main template (main.tpl) and one only has to instruct it to include the sub-templares header.tpl at the top and footer.tpl at the bottom.
So the three template files look like this:
header.tpl:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
main.tpl:
{TEMPLATE FILE="header.tpl"}
{CONTENT}
{TEMPLATE FILE="footer.tpl"}
footer.tpl:
</body> </html>/
When phpCMS now parses main.tpl, it notices that at the top and at the bottom there are other parts to be included, parses these parts, puts all the parts together and ends up with the complete template which is identical to the first simple (complete) template used in this example.
In addition to the main.tpl one can now make the derived templates for the middle part, e.g. for the forum, looking like this:
forum.tpl:
{TEMPLATE FILE="header.tpl"}
{SCRIPT_FORUM}
{TEMPLATE FILE="footer.tpl"}
The same goes for the search facility, the sitemap, and all the other special pages one may want to have and which show another placeholder instead of or additionally to {CONTENT}.
And as one can see, the same header.tpl and footer.tpl are included by forum.tpl (and would be for all the other ones) as they where by main.tpl.
If one now is in the same situation as above, i.e. one wants to have a background image for all the pages, one only has to change one file, header.tpl, and include there 'background="background.jpg' into the <body> tag to make it available to all templates as all of them include the same header.tpl.
To conclude:
One should always try to
- divide the template into at least three parts, the "variable" middle part as main template, and the areas above and below it as "static", "re-usable" sub-templates header.tpl and footer.tpl,
- keep the middle part as simple as possible.
[edit] Special Sub-Templates
- You can use Sub-Templates that are only shown in Edit Mode. Have a look here
[edit] Possible Issues
- You should use a different extension for your included template files so that they can't be called directly with the "Dynamic templates"-Feature (see below) since the parser only allows the template extension in the main configuration. If you configured .tpl to be your template extension links with site.htm?template=subtemplate.stpl won't be parsed. You should do this in order to prevent users from bypassing scripts you included in your main template file by simply calling a site with a sub-template.
[edit] Dynamic templates
It is possible that the content of a content file should under certain circumstances be shown in different ways, e.g. one wants to use a special template for a print preview. To allow this, phpCMS provides the possibility of using a temporary template to lay out a content file. To use this feature, one has to add ?template=... (in Stealth-Mode) or &template=... (in Non-Stealth-Mode) behind the URL. Following the equal sign, the absolute or relative path (from the document root) to a template file is noted. It's also allowed to use the predefined tag $home.
For security reasons the URL must not contain a ../.
In addition one can only supply files with the file suffix set in the configuration. By default, this suffix is set to .tpl.
Examples for URLs, here for the Stealth-Mode:
http://phpcms.de/demo/index.htm?template=/demo/templates/print.tpl http://phpcms.de/demo/index.htm?template=$home/templates/print.tpl http://phpcms.de/demo/index.htm?template=template/print.tpl
To link to a print template one can use $self. This could look like that:
<html>
<head>
<title>{TITLE}</title>
</head>
<body>
<h1>{TITLE}</h1>
<p>
{CONTENT}
<a href="$self?template=print.tpl">Print preview</a>
</p>
</body>
</html>
Main Page: User Documentation MainPage
« Previous Page: How to work with project files | Top Page: How to work with phpCMS | Next Page: How to work with content files »
