Zo2 template developing guide

The structure


A basic template Zo2 template structure is as followed:

basic-structure

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 core directory.

bootstrap-addons

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.

components 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();
$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', 'mainmenu'), $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 tochmod these 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/development directory.
  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.