JBZoo item templates - operation principles and customization

This article is a short but extensive description about where and how you can edit JBZoo item templates without having any problems with application updates. I.e. everything that is described below is not a hack but a common task when customizing an appearance of your website. We strongly recommend you to read an article about general concepts of JBZoo customization. Attention! in this article this path

media/zoo/applications/jbuniversal/templates/catalog/

will be replaced with .../ .

Where are item templates located?

There are two types of layout files for items: common ones and those that are specific to the particular item type. Template engine first checks if there is a folder for an item type

.../renderer/item/<ITEM TYPE ALIAS>/

If it can’t find such folder, then default templates are used, which are located in the .../renderer/item/ directory.

Usually, default templates can be used as examples that can be easily copied and customized. We recommend you to always use custom templates - it will make your code independent and flexible.

Which file does what?

Templates:

• full.php - a detailed page of an item.
• teaser.php - if an item is displayed as a category element.
• related.php - related items (default).
• subcategory_item.php - if an item is displayed as a subcategory item.
• compare.php - item comparison (should be empty), it just need to exist.
• submission.php - item submission form template.
• favorite.php - for the favorites list.
• feed.php - text of a description for RSS.

System files:

• metadata.xml - names of the templates and their description. This information is displayed in the control panel.
• positions.config - this file stores the settings of all positions for all item templates in ZOO. Change it at your own risk. Normally, ZOO and JBZoo do it themselves.
• positions.xml - a description of all positions for all templates (see below for more details).
• index.html - standard Joomla stub in case htaccess doesn’t work.

Each ZOO item template should contain only main layout, design parts and maybe some general text. Layout is used to include positions which in turn are used to include necessary elements. This is exactly what you are configuring in the control panel.

Position output looks like this (empty check and the output if there is something to display):

<?php if ($this->checkPosition('position-name')) : ?>
<ul><?php echo $this->renderPosition('position-name', array('style' => 'list')); ?></ul>
<?php endif; ?>

array(’style’ => ’list’) is an optional argument which is used to specify the style of output for every element.

Such position styles are available:

• default - default style - element will be rendered as it is (you don’t have to specify this style).
• block - elements are wrapped in <div> tags.
• comma - elements are wrapped in <span> tags and are separated with “,”.
• hyphen - elements are separated with a short dash (minus).
• inline - elements are wrapped in <span> tags.
• list - elements are wrapped in <li> tags in order to create a list.
• paragraph - elements are wrapped in <p> tags.
• pipe - elements are separated with “|” symbol.
• submission.block - it’s mandatory to specify this style for positions of item submission form.

How to add your own style for element positions?

Examples can be found here - components/com_zoo/renderer/element/

You can put your files in the following folder:

.../renderer/element/

Here they will not be changed or deleted during an update.

If you want to add your own position it’s better to do this in a custom item template. Open this file:

.../renderer/item/<ITEM TYPE ALIAS>/positions.xml

You will see this:

<?xml version="1.0" encoding="utf-8"?>
<renderer>
   <positions layout="full">  <!-- start of the full template block, a description of its positions -->
      <position name="title">Title</position> <!-- System name of a position is set in the "name" attribute, system position name for the control panelis set in the tag field -->
      <position name="image">Image</position>
        <position name="company">Company</position>
      <position name="list">List</position>
      <position name="text">Text</position>
   </positions>
   <positions layout="related"> <!-- Same, but here it is specified that this template can be used for related items -->
      <position name="title">Title</position>
      <position name="photo">Photo</position>
        <position name="rating">Rating</position>
      <position name="contacts">Contacts</position>
   </positions>
</renderer>

Change positions as you need. Paste the code of a position in a template. Like this, for example:

<?php if ($this->checkPosition('position-name')) : ?>
    <?php echo $this->renderPosition('position-name'); ?>
<?php endif; ?>

Go to the control panel and drag your elements to a desired position. Each element may have its own rendering settings.

How to modify metadata.xml file?

.../renderer/item/<ITEM TYPE ALIAS>/metadata.xml

<?xml version="1.0" encoding="utf-8"?>
<metadata>
   <layout name="full"> <!-- template name in the attribute -->
      <name>Full</name> <!-- template name for the control panel -->
      <description>Full layout</description> <!-- template description for the control panel -->
   </layout>
   <layout name="teaser" type="related"> <!-- same, but in this attribute you can specify how this template will be used (related, feed, submission, compare) -->
      <name>Teaser</name>
      <description>Teaser layout</description>
   </layout>
</metadata>