eZ Publish templating

In the first part of this article, we will introduce the basics of the eZ Publish templating system, which will help us to better understand the rest of the article

Templating

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.

The official eZ Publish website has a constant, up-to-date reference with the entire templating markup. We suggest you to use the following link every time that you need to know more details about the available arguments:
http://ez.no/doc/ez_publish/technical_manual/4_0/templates/

The templating markup

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.

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}

Control structure operators

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

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.

Loop control

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).

Fetch functions

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.

Generic template functions and operators

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.

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

Layout variables

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.

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

Overriding a template

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.

Embedding HTML inside the WYSIWYG XML editor, pt.2

We have to override a standard behavior of eZ Publish to create a generic HTML block inside the WYSIWYG XML editor.

We use a content style named html for the online editor and we will work on it for the frontend to render it correctly.

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.

Creating a new design

Before starting work on the eZ Webin template code, we need to create a wireframe in order to decide on the layout structure. We will use this structure to override the standard layout files.

A wireframe is a basic visual guide that is used in web design to suggest the structure of a website and the relationships between its pages.

Wireframe editors
There are a lot of commercial and free wireframe editors. To create our site’s wireframes, we will use the Firefox plugin called Pencil(http://www.evolus.vn/Pencil/).
We have chosen Pencil because it is open source and works on every platform that runs the Firefox browser.
If you need something more complete, you should take a look at Balsamiq (http://www.balsamiq.com/) or at OmniGraffle (http://www.omnigroup.com/applications/OmniGraffle/) if you have an Apple computer.

Our site will have at least six different page layouts:

• The homepage
• The issue page, where we will display the cover and the articles list
• The issue archive page, by month and by years
• The staff profile page, where we will display the latest articles that the editor has written, along with his profile
• The article and the forum pages, with the default layout based on the eZ Webin design

Now we will illustrate the first four layouts because we will work on them, overriding their standard eZ Webin layout.

The homepage

Starting from the homepage, we can see that the site will have, in the top-left corner, a logo for the magazine and a place-holder for a banner. Under these, we will have the main navigation menu and the main content area.

We have chosen a three-column layout in order to easily manage the content that we want to show.

In the homepage, the first column will show the latest news and the middle column will show the information and cover of the latest issue.

The last column will have two boxes—one with the most important article from the latest issue and the other with the forum thread.

Issue page

The issue page will show some information of a specific magazine issue.

In this page, the middle box of the homepage will shift towards the left, and in the right column there will be the highlighted article for the issue. At the bottom of the page, we will find all of the other articles.

The issue archive

We have to remember that our magazine is released monthly, so we need an archive page where we can collect all of the past issues.

The issue archive page, which can be reached by clicking on the main navigation menu, will again show some information from the latest issue. (We need to sell our articles!)

The rightmost column of the template will show all of the covers for the current or selected year.

At the bottom of the page, we will create a box with links to the past issues grouped by years and months.

The staff profile page

The staff profile page will display information from a staff profile, such as his avatar, biography, and the latest articles that he has written.

The staff profile page will have three columns. The first column will show information regarding the editor’s profile, the middle column will show all of the articles the editor has written (paged five by five) and the third will be used for banners or other images.

>> Continue Reading: Creating a Design with eZ Publish 4 Templating System: Part 2