Zo2 template developing guide

Zo2 Framework / Nov 3, 2015

The structure

A basic template Zo2 template structure is as followed:

Directory:

assets: contains the stylesheet, images, and javascripts.
components: contains the Zo2 components, which will attach to a module position, and render HTML.
language: contains the language files of the current template.
layouts: contains the data of layout structure, presets, megamenu, and static assets.

Files:

index.php: the main template file which will invoke Zo2 Framework.
error.php: the error page.
templateDetails.xml: the template’s meta file, contains the informations of the current template, definitions
of module positions, and template’s options.
To achieve the basic template structure, the easiest way is clone or download the latest default template of
Zo2 Framework Hallo fromgithub.com/aploss/zo2.

1. The assets directory

Every static assets are managed by Zo2 in a unit of package, a package is stored in a directory, and has a
name in which may contains or not contains version. A package consists of 2 optional

directory: core and addons. The core directory will contain the main files of the package, and

the addonsdirectory will contain the files those are depended on the files in coredirectory.

Example of a static package

2. The components directory

Zo2 Components are basically HTML attached to a module position. The logo and footer on the default Zo2

Framework template, Hallo, is rendered by components. Components’ intention is to make an easy way to

render simple HTML structure at the desired module position, with an ability of quick to edit and easy to edit.

 The basic components

Every components must obey the following conventions:

1. File naming: the file name must be exactly as the module position name, the extension of file is .php. Take
a look at the templateDetails.xmlfor the complete module positions list, which can be varied on different
templates.
2. The class: the class name must follow the pattern: Zo2Component_<module_position_name> and extends
the base component classZo2Component.
3. The render position: currently, Zo2 Framework allows to render a component at the beginning or at the
ending of a module position. You can define where will the component rendered by defining the public
property: public $position. The value of the position can
beZo2Component::RENDER_BEFORE or Zo2Component::RENDER_AFTER. If the public property $position is
missing, Zo2 Framework will render at the beginning of the module position as default.
4. The render method: every components must have a public function render() which takes no
parameters. This method must return a HTML string to render.

3. The layouts directory

The layouts directory is the most important directory. This directory will stored all the data of current template:

layout structure layout.json, presets presets.json, static assets assets.json, megamenu megamenu.json.

The cache directory is used to store layout structure after rendered to HTML.

3. 1. The presets.json file

The presets.json is used to store presets data. A basic structure of preset data is as followed:

{ 
  "name": "black", 
  "default": true, 
  "css": "presets/black", 
  "less": "presets/black", 
  "thumbnail": "/assets/zo2/images/presets/black.jpg", 
  "variables": { 
  "background": "#dedede", 
  "header": "#cfcfcf", 
  "header_top": "", 
  "link": "#212121", 
  "link_hover": "#5eaf28", 
  "text": "#ffffff", 
  "bottom1": "", 
  "bottom2": "", 
  "footer": "" 
  } 
} 

The presets.json can contain multiple of presets data in the form of json array.

Attribute name: the name of preset, will be displayed on the backend platform.
Attribute default: whether this preset should be chosen as default preset.
Attribute css and less: the CSS and LESS files of current preset. The path to CSS and LESS will have no
file extension.
Attribute thumbnail: a preview image of current preset.
Attribute variables: an customizable list of variables to change color of preset. Those variable will be
rendered as CSS style with the following selector.
Attribute background: will render body selector with background‐color.
Attribute header: will render #zo2‐header selector with background‐color.
Attribute header_top: will render #zo2‐header‐top selector with background‐color.
Attribute text: will render body selector with color.
Attribute link: will render a selector with color.
Attribute link_hover: will render a:hover selector with color.
Attribute bottom1: will render #zo2‐bottom1 selector with background‐color.
Attribute bottom2: will render #zo2‐bottom2 selector with background‐color.
Attribute footer: will render #zo2‐footer selector with background‐color.
3. 2. The layout.json file

The layout.json file contains the structure module position. This file should not be modified directly.

Instead, use the layout builder in the backend.

3. 3. The assets.json file

The assets.json file contains the static packages. As described before, every packages must registed inside

this file in order to be included. The file contains an array of json object, structured as below:

{ 
  "path": "vendors\ekko‐lightbox\ekko‐lightbox", 
  "type": "js" 
} 

Attribute path: is the path to the static file, root of path is from the assets directory, and use the
backslash \ to divide betweens directories.
Attribute type: the attribute defined the type of current static file. The value can be js, cs, or less.

3. 4. The megamenu.json file

The megamenu.json file contains the data structure of mega menu. This file should not be modified directly.

Instead, use the mega menu builder in the backend.

4. The file index.php

This is the basic structure of the index.php file:

<?php 
/** 
 * Zo2 (http://www.zo2framework.org) 
 * A powerful Joomla template framework 
 * 
 * @link        http://www.zo2framework.org 
 * @link        http://github.com/aploss/zo2 
 * @copyright   Copyright (c) 2013 APL Solutions (http://apl.vn) 
 * @license     GPL v2 
 */ 
 
defined('_JEXEC') or die('Restricted Access'); 
if (!class_exists('Zo2Framework')) die('Zo2Framework not found'); 
 
/** @var Zo2Framework $zo2 */ 
$zo2 = Zo2Framework::getInstance(); 
 $zo2 = Zo2Framework::getInstance(); 
$doc = JFactory::getDocument(); 
$debug = $zo2‐>getParams('debug_visibility'); 
$responsive = $zo2‐>getParams('responsive_layout'); 
$favicon = $zo2‐>getParams('favicon'); 
$this‐>language = $doc‐>language; 
$this‐>direction = $doc‐>direction; 
 
$layout = Zo2Framework::getInstance()‐>getLayout(); 
// init body 
$body = $layout‐>generateHtml(); 
 
$socialShares = new Zo2Socialshares(); 
?> 
<!DOCTYPE html> 
<html lang="<?php echo $this‐>language; ?>" dir="<?php echo $this‐>direction; ?>"> 
<head> 
    <meta http‐equiv="X‐UA‐Compatible" content="IE=edge"> 
    <?php if ($responsive) { ?> 
        <meta name="viewport" content="width=device‐width, initial‐scale=1.0"> 
    <?php } ?> 
    <?php if ($favicon) { ?> 
        <link rel="icon" type="image/x‐icon" href="<?php echo $favicon ?>" /> 
    <?php } ?> 
    <jdoc:include type="head" /> 
</head> 
<body class="<?php echo $layout‐>getBodyClass() ?> <?php echo $this‐>direction;?> "> 
<!‐‐[if lt IE 9]> 
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script> 
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script> 
<![endif]‐‐> 
    <?php echo Zo2Framework::displayOffCanvasMenu($zo2‐>getParams('menutype', 'mainmen
u'), $zo2‐>getTemplate()) ?>     
    <section class="wrapper"> 
        <!‐‐ SocialShare ‐‐> 
        <?php if (Zo2Framework::get('socialshare_floatbar', 1) == 1) { ?> 
            <?php echo $socialShares‐>getFloatbar(); ?> 
        <?php } ?> 
        <?php echo $body; 
        ?> 
    </section>     
    <?php if ($debug == 1) : ?> 
    <jdoc:include type="modules" name="debug" /> 
<?php endif; ?> 
</body> 
</html> 

The PHP code part should stay intacted, while the HTML structure can be modified as you need.

5. Permissions

The two directories assets/zo2 and layouts with theirs children should be writable by Joomla. For advanced

users, the ideal permissions for those two directories are 0755, which means the directories are writable by

theirs owner. If you’re expriencing missing CSS or JS files, you may need tochmodthese directories to 0777.
6. How to build a template based on Zo2
Framework

There are few conventions you have to follow:

1. Template name starts with zo2_ or zt_.
2. Components class name starts with Zo2Component_ and follows by name of module position that
component will attached to.
3. All custom statics assets must placed inside assets/zo2/developmentdirectory.
4. Third party plugin must be placed inside assets/vendors directory, with a directory with the corresponding
name. Though it’s not required, but we suggest you place the main static assets inside a core directory,
and other third party plugins that required the current plugin inside addonsdirectory.
5. The output override files must be placed inside html directory. Please refer to this document for more
details: How to override the output from the Joomla! core.
6. Languages must be placed inside language directory.
7. Layouts data file layouts.json, static assets data file assets.json, megamenu data file megamenu.json,
presets data file presets.json must be placed inside layouts directory. Please refer to the sections above
for how to modify those files.