Instructions for adding new content sources to Zentools2

The following is a guide for adding a new content source to Zentools2.

The Zentools infrastructure will receive an overhaul for Zentools2 v2.0 and move to a plugin based system. However for now you can manually create new content sources by adding the following files and code additions:

Helper file

Description: The key helper file that interfaces with the database or external source and maps content to the desired Zentools2 layout elements.

Location: includes/

Naming: The name of the file needs to match the name of your content source. eg k2_authors.php, images.php etc. Any spaces in the name need to use the underscore character as a replacement.

Content: 

  • The helper file must contain a class for your content source that also uses the same name. eg abstract class images {}
  • The class must contain a function called getList eg public static function getList(&$params) {}

 

Settings/sources xml

The various layout elements that can be used by this content source are specified in an xml file located in the settings/sources folder. This xml file should use the same name specified above. eg k2_authors.xml

You can see an example file is below:

<?xml version="1.0" encoding="utf-8"?>
<items>
<item>image</item>
<item>title</item>
<item>introtext</item>
<item>category</item>
<item>author</item>
<item>date</item>
<item>exif</item>
<item>readmore</item>
<item>fulltext</item>
<item>tagblock</item>
<item>tweet</item>
<item>pinit</item>
<item>like</item>
</items>

Each of the items listed in this file is added to the layout area in the zentools2 layout tool.

layout items

Adding new layout elements

If your new content source uses layout elements that have not yet been added to Zentools2 you will need to follow these additional steps. For this example we are going to use a new layout element called "related_items".

1. You should already have the new related item listed in the xml file that you created for your new content source.

2. Parameters for the new layout element (related_items) need to be added to a settings/elements/related_items.xml. This xml file needs to include a minimum number of parameters for basic functionality from Zentools2 to be available:

These include:

  • responsive_classes
  • display
  • alignment
<?xml version="1.0" encoding="utf-8"?>
<params>
<field name="responsive_classes" type="responsiveclasses" default="content" label="Activate items below to show element at specified screen resolution." description="">
<option value="phone">Phone</option>
<option value="tablet">Tablet</option>
<option value="desktop">Desktop</option>
<option value="wide">Widescreen</option>
</field>
<field name="display" class="hide-field" display="third" type="text" default="block" label="Display" description="Inline or block" />
<field name="alignment" type="flatlist" default="left" label="Align" description="Determines whether the element is aligned to the left, right or center.">
<option value="left">Left</option>
<option value="center">Centre</option>
<option value="right">Right</option>
</field>
</params>

Once this file has been added to that folder the settings for that layout element will appear in the item layout area after the layout element has been added to the layout.

related

3. The next step is to add the layout file for this new element. Layout files for elements are located in the mod_zentools2/tmpl/elements/ folder.

The layout element file needs to use the same name as specified in the previous steps eg related_items. This layout file can hold any data or content you need to add.

Retrieving data from the helper file.

Data from the helper file can be retrieved by access the $item object. in the case of this example you would expect to add data from the $item->related_items field, however any other fields found in the $items object is also available.

Retrieving data from the element settings.

Any of the parameters that you created in the settings/elements/related_items.xml file can be accessed in the layout element by accessing the $element object. eg the alignment can be accessed via the $element->alignment variable.

Retrieving data from the module settings

Any other parameters stored in the module can be accessed by the $settings object. eg $settings->count.

 

An additional function for the zentools2 helper file

One of the parts of the infrastructure in Zentools2 that will be overhauled for v2 is that to add a new content source you need to manually add a check for it in the includes/zentools2helper.php. This is a simple function to check whether the content source is available.

For content sources that are not tied to a specific component you can just add a function like this:

/**
* Returns true for using Image as a source
* We do this because Images are automatically available
* as a source
*/

public static function images() {
return true;
}

Or for content sources that are tied to a specific component you need to add a check that the component is installed. There are a number of ways to do this but the easiest is perhaps to check to see if a file exists that the component uses. The following is the check to see if K2 is installed:

/**
* Checks if K2 is installed
*
*
*/

public static function k2()
{
jimport( 'joomla.filesystem.file' );

if (defined('K2_JVERSION')) {
return true;
}

return JFile::exists(JPATH_ADMINISTRATOR . '/components/com_k2/k2.php');
}