In the previous chapter, we learned how to place our code in a custom extension. In this chapter, we will learn how to manage our design in the same way. We will see what an eZ Publish template is and how to apply a template to a single content node or subtree. We will also take a look at template overrides and create a proper design extension starting from the eZ Webin package.
In the first part of this chapter, we will introduce the basics of the eZ Publish templating system, which will help us to better understand the rest of this chapter and the next.
eZ Publish has its own templating system based on the decoupling of layout and content. This will help us to assign a custom layout to any content object in different sections.
Moreover, just as other templating platforms, such as Smarty (http://www.smarty.net), eZ Publish has its own markup to help developers with control structure operations, subtemplating, and on-the-fly content editing. It also exposes a particular function to fetch and filter content from a database.
All of the eZ Publish templating code should be placed between curly brackets ({ }). When the CMS will parse our template file and find the curly brackets, it will start executing the related code.
Note
Escaping the curly brackets
If we need to use curly brackets, for example to write a javascript function inside our template, we need to use the {literal} operator.
{literal}
<script type="text/javascript">
function alertMe() {
window.alert('Harkonen approaching!'),
}
</script>
{/literal}
We can divide these function into two main families:
- Conditional (
IF-THEN-ELSE) - Looping (
FOR-FOREACH-WHILE)
Whereas the first one should be used to change the template behavior according to some predefined condition, the other one will help us to seek and manage array and content structures.
Conditional control is sometimes useful for changing the output when some data is received by the system. For example, we would need a different CSS class for a particular value, or to change the <div> class, if the current month is the same as the one displayed, as shown below:
{def $current_month=currentdate()|datetime(custom, '%F')}
{if $node.name|eq($current_month) }
<span class="this-month">
{else}
<span class="default-month">
{/if}
{undef $current_month}
In the first line, we define a $current_month variable that has a value of the name of the month (for example, October), retrieved by the datetime() operator. Then we use the IF conditional control to choose the correct class.
In the last line, we delete the variable previously created, by releasing it from system memory.
As stated above, the loop control structure can be used to iterate through an array. We can, for example, create an unordered list (<ul>) from an array of items.
<ul>
{foreach $items as $item}
<li>{node_view_gui content_node=$item view=line}</li>
{/foreach}
</ul>
This will be rendered as:
<ul> <li>1st item</li> <li>2nd item</li> <li>3rd item</li> … </ul>
As you can see, the FOREACH structure is similar to the PHP structure. In this example, the most interesting line is the definition of the list object. This we can literally read as: render the content node (node_view_gui) from a specific node (content_node=$issue) using the line view template (view=line).
With the fetch functions, we can retrieve all of the information about a content object for a module. The fetch functions can also be used to create custom queries to retrieve only the information we need, and not everything.
eZ Publish exposes many fetch functions, which can be read about on the documentation site at http://ez.no/doc/ez_publish/technical_manual/4_0/reference/template_fetch_functions
The most important, and most used, fetch functions are those regarding the content, sections, and user modules. For example, we can fetch the root content object by using the following code in our template:
{$object = fetch('content', 'object', hash('id', '1'))}
We can then use the $object variable to display the object inside the HTML code.
The CMS gives us a lot of functions and operators, all of them described in the reference manual of the eZ System documentation site.
As a thumb rule, we should remember that to execute a particular function, we have to use the following syntax:
{function_name parameter1=value1 … parameterN=valueN }
All parameters are separated by spaces and can be specified in no particular order.
If we want to manage the operators, we have to remember that they accept the parameters passed in a specific order, separated by a comma. Moreover, an operator should handle a parameter passed to it with a pipe (|).
{$piped_parameter|my_operator( parameter1, …, parameterN ) }
Every time we see a pipe after a variable, we have to remember that we are passing a value to an operator.
We used the datetime() operator in the previous example for the conditional control functionality.
Tip
As a reference to API functions and operators, you can use the official variable documentation that is constantly updated on the eZ System site: http://ez.no/doc/ez_publish/technical_manual/ 4_0/reference/template_operators
http://ez.no/doc/ez_publish/technical_manual/ 4_0/reference/template_functions
By default, the page layout template can access some of the variables passed by the CMS. These variables, named Layout variables, can be used to render system and user information, or to change the output. These variables are automatically configured by eZ Publish when it analyzes and executes the code related to a view.
One of the most important variables is $module_result, which contains the results generated by the module and the view that is being executed.
A module is an HTTP interface that interacts with eZ Publish. A module consists of a set of views that contain the code to be executed. For example, if we call the following URL, the system executes the login view code of the user module:http://www.example.com/index.php/user/login.
Tip
As an API reference, you can use the official variable documentation that is constantly updated on the eZ System site: http://ez.no/doc/ez_publish/technical_manual/4_0/templates/the_pagelayout/variables_in_pagelayout
eZ Publish offers a set of standard templates that are useful, but they cannot cover all the possible design needs.
To solve this issue, the CMF provides a fallback system that allows us to load different templates based on specific rules. This system is usually referred to as overriding, and allows us to change the template for each module's view by overriding the default template when the user is in a particular context.
As we saw in Chapter 4, we had to override a standard behavior of eZ Publish to create a generic HTML block inside the WYSIWYG XML editor.
We previously created a content style named html for the online editor, but we didn't do anything for the frontend to render it correctly. Now, we will finish that work.
First, we have to create a file named literal.tpl and place it in the design folder of our extension. The following code will do exactly what we need:
# mkdir -p /var/www/packtmediaproject/extension/packtmedia/design/magazine/templates/datatype/view/ezxmltags/
# cd /var/www/packtmediaproject/extension/packtmedia/design/magazine/templates/datatype/view/ezxmltags/
# touch literal.tpl
Next, we will open the literal.tpl file in our preferred IDE. Now we will add the code that will, by default, render everything surrounded by a <pre> tag and the raw HTML code, if the class is html:
{if ne( $classification, 'html' )}
<pre {if ne( $classification|trim, '' )} class="{$classification|wash}"{/if}>{$content|wash( xhtml )}</pre>
{else}
{$content}
{/if}
This code will check to see if the $classification variable is different from the "html" string in order to add the <pre> tag and then, again, it will add a class attribute to the <pre> tag if the $classification variable is not null.
To use it, we only need to reset the cache from the shell prompt by using the following command:
cd /var/www/packmediaproject/
php bin/php/ezcache.php --clear-all --purge
The ezcache.php file is a PHP shell script that can be used to clear and manage the eZ Publish cache. This file has many parameters, which can be viewed by using the --help parameter.