Position styles in item templates

5.0/10 rating (2 votes)

Position styles exist in ZOO in order to output elements in item templates with needed layout - such as a table, a block or an ordinary list. Sometimes default styles are not enough so you might have a question: “How to output elements using custom layout, classes, id etc?”. Custom position styles can help us here.

Standard ZOO styles

If you opened template files, you probably seen following lines of code:

<?php echo $this->renderPosition('subtitle', array('style' => 'block')); ?>

renderPosition function outputs all elements which are assigned to this position and has at least one mandatory parameter - position name (in the above example it is subtitle). Second optional parameter is an array of settings (in the above example it is array('style' => 'block')). If an array with settings is omitted, all elements will be rendered using standard template - default.

By default there are 8 styles in ZOO. You can see them in this folder:

/components/com_zoo/renderer/element

There you will see following php-files:

  • block.php - renders elements inside div blocks. A class can be assigned for this div.
  • comma.php - renders elements inside span tags using comma “,” as a delimiter. A class can be assigned as well.
  • default.php - renders elements without formatting.
  • hyphen.php - renders elements inside span tags using hyphen “-” as a delimiter.
  • inline.php - renders elements inside span tags.
  • list.php - renders elements inside li tags.
  • paragraph.php - renders elements inside p tags.
  • pipe.php - renders elements inside span tags using “|” as a delimiter.

File name is a name of the style that is used in an array of settings. For example, in order to output elements as a list, we just have to write like this:

<?php echo $this->renderPosition('position name', array('style' => 'list')); ?>

JBZoo styles

JBZoo also has its position styles located in this folder:

/media/zoo/applications/jbuniversal/templates/catalog/renderer/element

If you open this folder, you will see such files as:

  • jbblock.php
  • jbsubtitle.php
  • jbtable.php
  • jbtitle.php

Let’s examine each file separately.

JBblock and JBSubtitle styles

JBblock - similarly to the standard ZOO block style - renders elements inside div tags, but has some additional parameters:

  • tag - possibility to set a tag that will be used to render an element (instead of div).
  • labelTag - defines a wrapper for the element title. It is strong by default.
  • wrapperTag - defines a tag for a value.
  • class - adds a class for an element name (label).
  • altlabel - using this parameter you can replace name/title (will be replaced for all elements in this position).
  • clear - can be true or false (false by default). If you set true, then this block will be inserted after each element:
<div class="clear clr clearfix"></div>

Delimiter block

Parameters for a style are defined using an array in this->renderPosition after specifying position name.

echo $this->renderPosition('anons' , array(
    'style'      => 'jbblock', 
    'class'      => 'simple-block' , 
    'altlabel'   => 'Element Title' , 
    'labelTag'   => 'strong', 
    'tag'        => 'p' , 
    'wrapperTag' => 'i'
));

In the source code you can see following classes that are set for elements:

Elements classes

  • index-<N> - assigns a number starting from zero until last element (ascending).
  • element-<ELEMENT_ID> - adds hash-id.
  • element-<ELEMENT_TYPE> - adds element type to a class.
  • first / last - this classes are added to the first and last elements accordingly.

JBSubtitle is the same as JBblock except the tag parameter which is h2 by default.

JBTable style

JBTable also has all the settings of JBblock style, but the following parameters are forcedly set:

echo $this->renderPosition('anons' , array(
    'style'      => 'jbtable', 
    'labelTag'   => 'td', 
    'tag'        => 'tr' , 
    'wrapperTag' => 'td'
));

They are needed in order to receive a table. Since these parameters (labelTag, tag, wrapperTag) are already set, you just have to only specify ‘style’=>’jbtable’ in the array.

Rendering a table and a list using JBblock style

JBblock is pretty universal. You can use it to output a table (without using jbtable) or a list.

In order to output elements inside a table when using jbblock, you should render position like this:

<?php if ($this->checkPosition('anons')) : ?>
    <table class="item-anons">
        <?php echo $this->renderPosition('anons' , array(
            'style'      => 'jbblock',
            'labelTag'   => 'td',
            'tag'        => 'tr' ,
            'wrapperTag' => 'td'
        )); ?>
    </table>
<?php endif; ?>

And in order to output a list use the following structure:

<?php if ($this->checkPosition('anons')) : ?>
    <ul class="item-anons">
        <?php echo $this->renderPosition('anons' , array(
            'style'      => 'jbblock',
            'tag'        => 'li' ,
            'wrapperTag' => 'p'
        )); ?>
    </ul>
<?php endif; ?>

Creating your own position style

There is nothing hard in creating a style. You just need some basic knowledge of php and html. Our style will output an element in a specified tag, will have a default class which can be changed. Also we will add a possibility to specify a tag and id for an element title.

Let’s create a php file of our style in this folder:

/media/zoo/applications/jbuniversal/templates/catalog/renderer/element

Let’s call it jbexample.php. If will contain following code:

<?php
defined('_JEXEC') or die('Restricted access'); // Restricting direct access
// Output of an element label
$label = ''; // A variable for a label
/**
* Since the display of a label can be configured in the settings, we should make this check:
*/
if (isset($params['showlabel']) && $params['showlabel']) {
    $label .= $element->config->get('name');
}
/**
* Outputting elements values/
* render function outputs element (elements) values in a cycle
*/
echo $label.$element->render($params);

Everything is ready. We can now check how our style works. Let’s open a template of an item type (full, teaser etc.), full, for example. And specify our style for one of the positions.

We have the anons position which currently doesn’t have any styles:

<?php if ($this->checkPosition('anons')) : ?>
    <div class="item-anons"><?php echo $this->renderPosition('anons'); ?></div>
<?php endif; ?>

This position can be rendered using our newly created style. Let’s add a second parameter and specify our style.

<?php if ($this->checkPosition('anons')) : ?>
    <div class="item-anons">
    <?php 
       echo $this->renderPosition('anons' , array(
          'style' => 'jbexample',
       )); 
    ?>
</div>
<?php endif; ?>

Let’s check it.

Checking our style for errors

You can see that two elements are rendered in one line without any tags. Let’s fix this.

We’ll add the following to the renderPosition function:

<?php if ($this->checkPosition('anons')) : ?>
    <div class="item-anons">
        <?php
            echo $this->renderPosition('anons' , array(
                'style' => 'jbexample',
                'label' => array(
                    'tag' => 'strong', // a tag for a title
                    'id'  => 'label',  // an id of a title
                ),
                'element' => array(
                    'tag'   => 'p', // a tag for an element value
                    'class' => 'my-elents' // element class
                ),
            ));
        ?>
    </div>
<?php endif; ?>

If we try to refresh the page, the result will be the same because we didn’t accept these parameters in our style.

In order to understand this better, you can make var_dump($params) in the jbexample.php file and look what is inside this variable. $params returns an array with data. The data that we previously entered in renderPosition function is in the red blocks.

Data from renderPosition function

Accepting parameters in jbexample.php

<?php
defined('_JEXEC') or die('Restricted access'); // restricting direct access to the file
// Output of an element label
$label = ''; // A variable for a label
/**
 * Since the display of a label can be configured in the settings, we should make this check:
 */
if (isset($params['showlabel']) && $params['showlabel']) {
    //  Accepting label tag. If it is omitted, using i by default
    $labelTag = (!empty($params['label']['tag'])) ? $params['label']['tag'] : 'i' ;
    //  Accepting label id. If it is omitted, do not use it
    $labelId  = (!empty($params['label']['id'])) ? 'id="'.$params['label']['id'].'"' : '' ;
    //  Concatenating a tag, an id and a label
    $label .= '<'.$labelTag.' '.$labelId.'>';
    $label .= $element->config->get('name');
    $label .= '</'.$labelTag.'>';
}
/**
 * Outputting elements values/
 * render function outputs element (elements) values in a cycle
 */
//  Accepting element tag. If it is omitted, using span by default
$elementTag = (!empty($params['element']['tag'])) ? $params['element']['tag'] : 'div' ;
//  Accepting element class. If it is omitted, do not use it
$elementClass  = (!empty($params['element']['class'])) ? 'class="'.$params['element']['class'].'"' : '' ;
//  Concatenating a tag, a class and a value. Moving everything to $myElement variable.
$myElement = '<'.$elementTag.' '.$elementClass.'>'.$element->render($params).'</'.$elementTag.'>';
//  Output
echo $label.$myElement;

That’s all! Our style is ready.

This is how our new style looks like

By using custom position styles you can output your elements in any layout by wrapping them in desired tags, adding their own classes, id, attributes and a lot more that html has.

API, Item, Template

Still gotta questions, who can help me?

Visit our special JBZoo tech support forum which is specifically meant for JBZoo so the priority of the response and its promptness are much better there than in any other place. With inactive account with a “Plus” sign in a tariff plan you can ask for support in one of these sections or use any of our contacts.