How to make an element for ZOO/JBZoo - an example

5.0/10 rating (1 votes)

Let’s name our element jbint. It will accept and output whole numbers.

It will have 3 templates:

  • edit.php - editing form.
  • default.php - simple output of a whole number.
  • thousand.php - an output of a number delimiting thousandths with a space.

This element is repeatable-submittable. It will have an option to choose a template and an option that will be used during ajax request test.

During item submission this element will accept whole numbers.

jbint.xml file

<?xml version="1.0" encoding="utf-8" ?>
<!--
 type  - Element type. It should be unique. 
 group - Element group. A group determines a position during creation of new elements.
-->
<element type="jbint" group="JBZoo">
    <name>JBInt</name>
    <author>A. Oganov</author>
    <creationDate>2014 April</creationDate>
    <copyright>Copyright (C)</copyright>
    <authorEmail>author email</authorEmail>
    <authorUrl>author url</authorUrl>
    <version>1.0</version>
    <params>
 <!--  Parameters are displayed during element creation. Element config -->
              <param name="ajax" type="text" default="ajax" label="Default text" />
    </params>
    <params group="render">
    <!-- Parameters are displayed in the configuration of item templates: full, teaser etc. -->
        <param name="template" type="zoolist" default="default" label="Chose template">
            <option name="JBZOO_ELEMENT_STANDART">default.php</option>
            <option name="JBZOO_ELEMENT_THOUSAND">thousand.php</option>
        </param>
        <param name="separated_by" type="zoolist" default="Space" label="Separated by"
               description="CHOOSE_SEPARATOR_REPEATED_ELEMENTS">
            <option name="Space"><![CDATA[separator=[ ]]]></option>
            <option name="Break"><![CDATA[separator=[<br />]]]></option>
            <option name="Span"><![CDATA[tag=[<span>%s</span>]]]></option>
            <option name="Paragraph"><![CDATA[tag=[<p>%s</p>]]]></option>
            <option name="Div"><![CDATA[tag=[<div>%s</div>]]]></option>
            <option name="List Item"><![CDATA[tag=[<li>%s</li>]]]></option>
            <option name="Unordered List"><![CDATA[tag=[<li>%s</li>] enclosing_tag=[<ul>%s</ul>]]]></option>
            <option name="Ordered List"><![CDATA[tag=[<li>%s</li>] enclosing_tag=[<ol>%s</ol>]]]></option>
            <option name="Warp Item"><![CDATA[tag=[<article class="item">%s</article>]]]></option>
        </param>
    </params>
</element>    

All parameter types that we can use in an element are located here:

/administrator/com_zoo/helpers/fields/ or jbuniversal/joomla/elements/

You can also create new types here but that’s another story.

jbint.php file

// Restricting direct access to the file
defined('_JEXEC') or die('Restricted access');
// Registering ElementRepeatable class
App::getInstance('zoo')->loader->register('ElementRepeatable', 'elements:repeatable/repeatable.php');
class ElementJBInt extends ElementRepeatable implements iRepeatSubmittable
{
    /**
     * Checks if the repeatables element's value is set.
     */
    public function _hasValue($params = array())
    {
        $value = $this->get('number');
        return !empty($value);
    }
    /**
     * Get elements search data.
     * @return null | int
     */
    public function _getSearchData()
    {
        return (int) $this->get('number');
    }
    /**
     * Renders the edit form field.
     * @return string HTML
     */
    public function _edit()
    {
        if ($layout = $this->getLayout('edit.php')) {
            return $this->renderLayout($layout);
        }
        return false;
    }
    /**
     * Render
     * @param array $params
     * @return null | string HTML
     */
    public function _render($params = array())
    {
        if ($layout = $this->getLayout($params->get('template', 'default.php'))){
            return $this->renderLayout($layout);
        }
        return false;
    }
    /**
     * Renders the element in submission.
     * @param array $params submission parameters
     * @return null | string HTML
     */
    public function _renderSubmission($params = array())
    {
        return $this->_edit($params);
    }
    /**
     * Validates the submitted element
     * @param AppData $value  value
     * @param AppData $params submission parameters
     * @return array
     * @throws AppValidatorException
     */
    public function _validateSubmission($value, $params)
    {
        $value = $this->app->validator->create('integer',
            array(
                'required' => $params->get('required')
            )
        )->clean($value->get('number'));
        return array('number' => $value);
    }

Creating templates

In order to keep the code of logic and presentation separate, we need to create files that we will used to output information - templates.

Templates should be located in the tmpl folder. Unspoken agreement regarding naming says that if an element is repeatable, an underscore should be added to the template name. This will help you in developing large and complex elements.

The main point of separation of logic and presentation is that these components can be modified independently from one another.

Let’s examine a small example.

 // Checking if a file exists
if ($layout = $this->getLayout('_default.php')) {
    // Buffering and connection of _default.php file
    return $this->renderLayout($layout, array(
                  ‘one’ => ‘var1’,
                  ‘two’ => ‘var2’
    ));
}

Now we can use our variables $one and $two in the _default.php file.

We can also call methods of an element in the template - $this remains an object of the element’s class.

For those who are interested, in the Element class you can see an implementation of all methods:

/media/zoo/elements/element/element.php

API

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.