Building a custom template for a news portal

This section shows how to replace the template from the default root directory in the eZ Publish installation with a custom template that displays a mix of news and banners (as shown above). To achieve this we will override the template by:

• configuring override settings
• creating a template file

Override settings

The settings shown below are used to specify the use of a custom template for the root folder. The settings are stored in the settings/siteaccess/news/override.ini.append.php configuration file.

[folder_frontpage]

Source=node/view/full.tpl

MatchFile=full/folder_frontpage.tpl

Subdir=templates

Match[node]=2

This override matches on node ID, which is the internal representation of an object placed in the eZ Publish content node tree. To find the node ID of an object, open the Administration Interface and hover your mouse over the icon representing the object (in the left-hand menu):

Identifying the node ID

Template code

The override settings specify a template file, which is where we will implement the following functionality:

• Fetching data for articles and banners
• Displaying one large-sized article at the top of the page
• Displaying one banner
• Displaying four medium-sized articles in a two column table
• Displaying one banner
• Displaying nine small articles in a three column table
• Displaying one banner

In this example, the MatchFile specifies full/folder_frontpage.tpl. The full path to the file (relative to the eZ Publish installation directory) is design/news/override/templates/full/folder_frontpage.tpl. This is the template file that will be used by eZ Publish when the override condition (defined as Match[node]=2) is met.

The full contents of the folder_frontpage.tpl template file is shown below. In subsequent sections, we will go through each of its parts step-by-step.

{* 
 * Fetch the data to be displayed
 *}
{def $articles_array=fetch_alias( children, hash( parent_node_id, 85,
                                          offset, 0,
                                          sort_by, array( published, false() ),
                                          limit, 14 ) )
    $banners_array=fetch_alias( children, hash( parent_node_id, 67,
                                          offset, 0,
                                          sort_by, array( published, false() ),
                                          limit, 3 ) )}

   {* Show the first large news article *}
   {foreach $articles_array as $article max 1}
       {node_view_gui view=large content_node=$article}
   {/foreach}

   {* Show the first banner *}
   {foreach $banners_array as $banner max 1}
       {node_view_gui view=banner content_node=$banner}
   {/foreach}


   {* Show the next four news articles in 2x2 columns *}
   <table>
   <tr>
   {foreach $articles_array as $key => $article max 4 offset 1}
       <td>
       {node_view_gui view=medium content_node=$article}
       </td>
       {delimiter} 
       {if eq($key|mod(2),0)}
       </tr><tr>
       {/if}
       {/delimiter}
   {/foreach}
   </tr>
   </table>


   {* Show the second banner *}
   {foreach $banners_array as $banner max 1 offset 1}
       {node_view_gui view=banner content_node=$banner}
   {/foreach}
 

   {* Show the next nine small news articles *}
   <table width="100%">
   <tr>
     <td>
     <ul>
   {foreach $articles_array as $key => $article max 9 offset 5}
       <li>
       {node_view_gui view=small content_node=$article}
       </li>
       {delimiter}
       {if eq($key|mod(3),0)}
       </ul></td><td><ul>
       {/if}
       {/delimiter}
   {/foreach}
     </ul>
     </td>
   </tr>
   </table>
 

   {* Show the last banner *}
   {foreach $banners_array as $banner max 1 offset 2}
       {node_view_gui view=banner content_node=$banner}
   {/foreach}


{/let}

Override template functionality

The following functionality is implemented in the main override template of our news portal frontpage.

Fetching article and banner data

The first part of the frontpage template code fetches the data we want to display. To retrieve the data, we use the template operator fetch_alias.

{* 
 * Fetch the data to be displayed
 *}
{def $articles_array=fetch_alias( children, hash( parent_node_id, 85,
                                          offset, 0,
                                          sort_by, array( published,
                                                          false() 
),
                                          limit, 14 ) )
    $banners_array=fetch_alias( children, hash( parent_node_id, 67,
                                          offset, 0,
                                          sort_by, array( published,
                                                          false() ),
                                          limit, 3 ) )}

The first parameter to this operator specifies the type of fetch. We are using children to fetch a list of objects placed directly under a node. The second parameter is a hash defining the:

• Parent node from where objects are fetched
• Offset from which results should be returned
• Result sorting array (latest first)
• Maximum number of objects to return

Displaying top news

{* Show the first large news article *}

{foreach $articles_array as $article max 1}

   {node_view_gui view=large content_node=$article}

{/foreach}

The first article is displayed by using the foreach template function. We use this to loop over the $articles_array variable containing the articles we want to display. In our case, we only want to show the first article, so we provide the parameters offset=0 and max=1.

The article is displayed via the function node_view_gui. This function handles the inclusion of a specific view template for the article (called large).

Displaying banners

{* Show the first banner *}

{foreach $banners_array as $banner max 1}

   {node_view_gui view=banner content_node=$banner}

{/foreach}

The banners are all displayed via the same mechanism. Similar to the article described above, we use foreach to loop over the $banners_array variable. The differences between the display characteristics of the three banners is determined by the offset used to show the banners.

Displaying two-column articles

{* Show the next four news articles in 2x2 columns *}
<table>
<tr>
{foreach $articles_array as $key => $article max 4 offset 1}
   <td>
   {node_view_gui view=medium content_node=$article}
   </td>
   {delimiter}
   {if eq($key|mod(2),0)}
    </tr><tr>
   {/if}
   {/delimiter}
{/foreach}
</tr>
</table>

The four half-column articles are displayed within a table. Again we use the foreach function to loop over the $articles_array variable and show four articles starting from offset 1.

The articles are displayed via the node_view_gui function using the view mode called medium. To break up the table, we use the delimiter function with modulo=2. This means that the template will insert the code defined inside the delimiter for every second element, unless it's the last element.

Displaying three-column articles

{* Show the next nine small news articles *}

<table width="100%">
<tr>
   <td>
   <ul>
   {foreach $articles_array as $key => $article max 9 offset 5}
       <li>
       {node_view_gui view=small content_node=$article}
       </li>
       {delimiter}
       {if eq($key|mod(3),0)}
       </ul></td><td><ul>
       {/if}
       {/delimiter}
   {/foreach}
   </ul>
   </td>
</tr>
</table>

The nine three-column news article links are displayed in a similar manner to the two-column articles. The difference is that we use the view mode small and that we use a modulo value of 3 to make a three-column table instead of two.