Theme Guide

[简体中文](Theme 开发指南) | فارسی Contents

Introduction
File structure
Layout template
Introduction of some useful view helper
Predefine variables

Introduction

Theme is used to decide the layout, interaction and css of your site. XoopsEngine allows you to create different themes for different modules or XoopsEngine application itself. You can create your theme package and put it into a folder named 'theme' under directory 'usr/theme' in where it can be detected. Theme packages mainly contain several front files such as js, css, phtml, etc. These files are packed in different folders. In this guide, we will introduce how to create a theme package and how to use helpers of Xoops and Zend to achieve you tasks.

The structure of this guide is organized as follows:

section I introduce the file structure of theme package;
section II introduce the usage of helpers packed in Xoops;
section III lists the predefine variables of XoopsEngine.

File structure

The 'theme' folder is consisted of a series of folders, such as asset, locale, module, template and config.php. The structure is list as follows:

theme
    asset
       css
       image
       js
   locale
       en
   module
       demo
           asset
           template
   template
       {phtml files}
   config.php

The 'asset' folder contains js, css and image files, these static files will be publish to 'www' folder of XoopsEngine, they will override static files of modules because they have the highest priority.

The 'locale' folder contains language files of different countries.

The module folder contains the themes of modules, these themes also have asset and template folder. As we know, the module packages in 'usr/module' folder also have template and static files, but these file has the lower priority, they will be overridden by the files in the 'theme/module' directory if the theme module is installed.

The 'template' folder contains the phtml files contain HTML tags. This files are responsible for displaying your pages.

The config.php file lists the details of the theme, it uses array to store information.

config.php

As we mentioned previous, this file defines basic information of the theme, codes in the file are:

return array(
    'version'       => '1.0.0',
    'title'         => 'Xoops Engine Theme',
    'author'        => 'Xoops Engine Development Team',
    'screenshot'    => 'image/screenshot.png',
    'license'       => 'Creative Common License http://creativecommons.org/licenses/by/3.0/',
    'active'        => true,
    'type'          => 'both', // Potential value: 'both', 'admin', 'front', default as 'both'
    'description'   => 'Default theme for Xoops Engine',
);

The 'type' field in the array define the type of layouts available in the theme, its potential value can be 'both', 'admin' and 'front', if the field is not set, 'both' will be used as default.

Layout templates

In the template folder, some template files are created to display pages for this application or modules. These files define themes of front-end, admin-end and error pages.

layout-front.phtml

This template is used to display the homepage of front-end, it's a complete html page which include 'doctype', 'head' and 'body'. View helpers that we will introduce later can be used to load HTML elements 'head', 'meta' and 'script'.

The body of the page is divided into several parts, they are used to display blocks and module. Here we use a table to simple show the body layout of page:

+--------------------+---------------+---------------+---------------+--------------------+
|                    |               |               |               |                    |
|                    |    Block2     |    Block3     |    Block4     |                    |
|                    |               |               |               |                    |
|                    +---------------+---------------+---------------+                    |
|                    |                                               |                    |
|       Block1       |                     Module                    |      Block5        |
|                    |                                               |                    |
|                    +---------------+---------------+---------------+                    |
|                    |               |               |               |                    |
|                    |    Block6     |    Block7     |    Block8     |                    |
|                    |               |               |               |                    |
+--------------------+---------------+---------------+---------------+--------------------+

The contents of blocks are acquired by calling helper 'blocks', then a block.phtml template is included to display blocks. The template block.phtml will be introduce later.

For example:

<?php $blocks = $this->blocks()?>
    <table cellspacing="0">
        <tr>
            <?php if (isset($blocks['left'])) {?>
                <td id="xoops-column-left">
                <?php foreach ($blocks['left'] as $key => $block) {?>
                    <?php include $this->template('block.phtml');?>
                <?php }?>
                </td>
             ...
         </tr>
    </table>

layout-admin.phtml

The layout-admin.phtml is used to display homepage of admin-end. This template is also a complete HTML page which is as same as layout-front.phtml. But it do not be divided into blocks and module.

In the default theme package, XoopsEngine provides us several templates for displaying simple pages, they are:

block.phtml

The block.phtml template is used to display the content of blocks. It is included in the layout-front.phtml file by the php method 'include'. The codes of this file may be:

<div id="xoops-block-<?php echo $block['name'] ?: $block['id']; ?>" class="block-container<?php if (!empty($block['class'])) { echo ' ' . $block['class']; }?>">
    <fieldset>
        <?php
        if (!empty($block['title'])) {
            if(!empty($block['link'])) {
                $title = sprintf('<a href="%s" title="%s">%s</a>', $block['link'], $block['title'], $block['title']);
            } else {
                $title = $block['title'];
            }
            printf('<legend class="block-title">%s</legend>', $title);
        }
        ?>
        <div class="block-content"><?php echo $block['content']?></div>
    </fieldset>
</div>

The variable $block here is defined in the layout-front.phtml file.

page-zone.phtml

paginator.phtml

layout-content.phtml

This template simply displays content.

<?php echo $content ?>

layout-simple.phtml

This template display main content as well as HTML

element and page header.

layout-style.phtml

This template display main content as well as HTML

element.

The following templates are used when there has errors.

error-404.phtml

This template is used to list the errors when a 404 error occur.

error-index.phtml

This template is used to list errors and exceptions when they occur.

denied.phtml

This template displays a deny message when user have no permission to request the page.

Introduction of some useful view helper

You might found that you have troublesomely wrote scripts in your view page over and over when you code without framework, fortunately, XoopsEngine provides you with plenty of view helpers to complete your work quickly and conveniently.

A helper is simply a class that implements the interface Zend\View\Helper. Helpers of XoopsEngine inherit from that of Zend Framework 2. Helper simply defines two methods, setView(), which accepts a Zend\View\Renderer instance/implementation, and getView(), used to retrieve that instance. Zend\View\PhpRenderer composes a plugin broker, allowing you to retrieve helpers, and also provides some method overloading capabilities that allow proxying method calls to helpers. [Refer to Zend Framework 2 manual]

For example, if we create a class called 'js' in the Xoops\View\Helper or Zend\View\Helper, then we can use the method in the phtml file.

$this->js();

asset

The asset folder of theme is used to stored static file, such as js, css and images. This folder will be published to the 'www' folder of XoopsEngine, so the static files can be fetched by user's request. The asset helper helpers for building a asset URI, then we can use this URI to fetch the file. for example, you can write the following codes in your phtml file:

$this->asset('theme/default', 'css/style.css');

This code will return a string such as 'http://localhost/XoopsEngine/www/asset/theme-default/css/style.css' if you set your XoopsEngine folder's name to 'XoopsEngine'. The first parameter of asset function is a string describes the name of component. This string consist of two parts that connect by characters exclude letters (a-z, A-Z), numeral (0-9) and dash (-), a slash () is recommended. The previous part the string should be 'theme' or 'module' which contain a asset folder and the later part is the name of theme or module.

The second parameter is the file name you want to build.

echo $this->asset('module/demo', 'js/demo.js');

Output:

http://localhost/XoopsEngine/www/asset/module-demo/js/demo.js

Other example:

<img src="<?php echo $this->asset('module/demo', 'image/logo.png'); ?>" />

assetModule

This helper is more conveniently to build a URI for module, because you can only assign the file name if you want to get a URI for current module. This helper takes two parameters, the first parameter should be assigned a string of file name, and the second parameter is a string of module name, this parameter can be ignored if you build a URI for current module. If you want to build a URI of other module, you must assign the module name to the second parameters.

This helper will also return a string contain an asset URI of a module.

For example, supposing you add a phtml file in a module call 'demo' with following codes:

  echo $this->assetModule('js/demo.js');

It will output the following URI:

  http://localhost/XoopsEngine/www/asset/module-demo/js/demo.js

Now if you want to build a URI with other module, such as 'article', you should assign the second parameter such as:

  echo $this->assetModule('css/style.css', 'article');

The output is:

  http://localhost/XoopsEngine/www/asset/module-article/css/style.css

assetTheme

This helper has as same function as asset and assetTheme, the difference is that, it will only build URI for asset folder of theme. The usage of this function is as same as assetModule, the two parameters are file name and module name, respectively. The second parameter can be ignore if you build a URI of current theme.

For example, the current theme named 'default':

echo $this->assetTheme('image/logo.png');
echo $this->assetTheme('js/jquery.js', 'dev');

These codes will output:

http://localhost/XoopsEngine/www/asset/theme-default/image/logo.png
http://localhost/XoopsEngine/www/asset/theme-dev/js/jquery.js

blocks

XoopsEngine divides a page into a module part and several blocks parts. A block is an independent application relates to current module. XoopsEngine encapsulates a helper named 'blocks' for users to load blocks of specified zones. The blocks helper will return an array contains blocks information according to passed parameter.

The blocks helper takes only one parameter that indicates the zone. The value of parameter can be:

left

right

top-left

top-center

top-right

bottom-left

bottom-center

bottom-right

null

Blocks of different zones will be loaded according to its parameter, if the passed parameter is set to null, blocks of all zones will be loaded.

$blocks = $this->blocks();

$blocks = $this->blocks('bottom-center');
foreach($blocks['bottom-center'] as $key => $block) {
    ...
}

css

The HTML element is used for linking varieties of resources for your page, such as stylesheets, feeds, favicons, trackbacks and more. The css is a helper of Xoops library, which inherit from Zend helper, and call headLink helper of Zend to create and aggregate those elements mentioned above for later retrieval and output in your layout script. [Refer to Zend Framework 2 manual]

There is only one parameter of css helper, and it can be string or array which contains file path of resources. This helper will store path information in a AbstractHelper object, and you should add extra codes to output them.

In XoopsEngine, js, css resources are stored in static folder, therefore, you may fetch the URI firstly:

$pathToCss = Xoops::url('static') . '/css';
$this->css($pathToCss . '/style.css');
$this->css(array(
    $pathToCss . '/css1.css',
    $pathToCss . '/css2.css',
));
echo $this->headLink();

Then if you click right button to view page source, you will find a HTML element has been added:

<link href="http://localhost/XoopsEngine/www/static/css/style.css" media="screen" rel="stylesheet" type="text/css" > 
<link href="http://localhost/XoopsEngine/www/static/css/css1.css" media="screen" rel="stylesheet" type="text/css" > 
<link href="http://localhost/XoopsEngine/www/static/css/css2.css" media="screen" rel="stylesheet" type="text/css" >

NOTE: you must add 'echo $this->headLink();' at the end of your code if you want to output a HTML element.

js

js helper is a Xoops helper which inherit from AbstractHelper, this helper allows you to manage a HTML script element for later output, the HTML script element is used to either provide inline client-side scripting elements or link to a remote resource containing client-side scripting code. [Refer to Zend Framework 2 manual]

js helper has only one parameter, it can be string or array that describes the name of js file. This helper do not output HTML script element directly, you should add 'echo $this->headScript();' output it.

js script files are also stored in the 'static' folder in XoopsEngine. You should fetch a static URI first.

$pathToJs = Xoops::url('static') . '/js';
$this->js($pathToJs . '/js1.js');
$this->js(array(     
    $pathToJs . '/js2.js',
    $pathToJs . '/js3.js',
));
echo $this->headScript();

These codes will output:

<script type="text/javascript" src="http://localhost/XoopsEngine/www/static/js/js1.js"></script>
<script type="text/javascript" src="http://localhost/XoopsEngine/www/static/js/js2.js"></script>
<script type="text/javascript" src="http://localhost/XoopsEngine/www/static/js/js3.js"></script>

jQuery

jQuery is a JavaScript framework, it will help user to deal with HTML documents, events and animation conveniently, it also provides with AJAX. jQuery helper inherit from AbstractHelper of Zend, it helps to load js or css files for later output.

jQuery helper contains only one parameter which can be a string or an array consists of string elements. Strings are name of css or js file, if you do not assign the parameter with actual value, a js file named 'jquery.min.js' will be used.

Take notice that, you should add 'echo $this->headScript();' or 'echo $this->headLink();' to output your HTML tags.

$this->jQuery();
$this->jQuery('extension.js');
$this->jQuery(array(
    'js1.js',
    'css1.css',
));
echo $this->headScript();
echo $this->headLink();

The output is:

<script type="text/javascript" src="http://localhost/XoopsEngine/www/static/js/jquery/jquery.min.js"></script>
<script type="text/javascript" src="http://localhost/XoopsEngine/www/static/js/jquery/extension.js"></script>
<script type="text/javascript" src="http://localhost/XoopsEngine/www/static/js/jquery/js1.js">
<link href="http://localhost/XoopsEngine/www/static/js/jquery/css1.css" rel="stylesheet" type="text/css" >

meta

The HTML element is used to provide meta information about your HTML document, such as keywords, document character set, caching pragmas, etc. Meta tags may be either of the 'http-equiv' or 'name' types, must contain a 'content' attribute, and also have either of the 'lang' or 'scheme' modifier attributes. [Refer to Zend Framework 2 manual]

The meta helper will return an AbstractHelper object containing system meta information according to given parameter. This helper has only one parameter typed string, it is the name of meta element. The value of the parameter can be 'copyright', 'description', 'keywords' or 'author' here. If you set the parameter to null, a AbstractHelper contains nothing will be returned.

$this->meta();
$this->meta('keywords');

Output:

Xoops Engine, Web application

template

In XoopsEngine, HTML tags are coded in a special file which has extension named '.phtml'. The template helper is used to decide which template file to use in current theme. This helper takes only one parameter which is a string containing module and template name. The full string has a format such as "{module name}:{template name}.phtml". If you do not set module name, current module will be used. The templates in theme package have the highest priority.

For example, if you install your XoopsEngine in D disc, and current module is system:

echo $this->template('block.phtml');
echo $this->template('module/system:block/login.phtml');

Output:

D:/wamp/www/XoopsEngine/usr/theme/default/template/block.phtml
D:/wamp/www/XoopsEngine/usr/module/system/template/block/login.phtml

Using following codes to add a template:

include $this->template('block.phtml');

url

XoopsEngine adopts a Module-Controller-Action model, you should set module name, controller name and action name in url to route to right page. The url helper provides the function to generate a URL by given parameters.

The url helper takes four parameters, the first is route name, it allow you to choose your route style, it will set to 'default' if you give a null value; the second parameter is an array which contain module name, controller name and action name, if you do not give the module name, current module will be used; the third parameter is an option parameter for route and the fourth parameter is a Boolean which decided whether to reuse matched parameters.

$this->url('', array(    
    'module'     => 'system',
    'controller' => 'index',
    'action'     => 'index',
));

$this->url('home');

$this->url('default', array(
    'controller'  => 'index',
    'action'      => 'index',
));

You can also add your parameters to the second parameter of url helper. These parameters will post by GET method, for example:

$this->url('' array(
    'controller'  => 'login',
    'action'      => 'login',
    'param'       => 'hello',
));

The url will be:

path/to/www/login/login/param-hello

Then you can use params() method to fetch the value:

$this->params('param');

widget

In XoopsEngine, blocks are used to implement a special function in page, you can add a block or remove a block from you page by coding your pthml file of theme package. widget helper will allow user to fetch and render a block.

widget helper inherit from block helper, it takes two parameters, the first can be a string of block name, or a number describes a block. The second parameter is an array.

$this->widget('block-name', array('title_hidden' => 1, 'opt1' => 'val1', 'opt2' => 'val2'));
$this->widget('block-name', array('link' => '/link/to/a/URL', 'opt1' => 'val1', 'opt2' => 'val2'));
$this->widget('block-name', array('style' => 'specified-css-class', 'opt1' => 'val1', 'opt2' => 'val2'));
$this->widget(24, array('opt1' => 'val1', 'opt2' => 'val2'));
$this->widget()->load(24);
$this->widget()->render($blockModel);

navigation

The navigation helper is used to load a navigation for your page.

This helper takes two parameters, the first one is name of navigation. In XoopsEngine, it can be set to 'front' or 'admin' to load a front navigation or admin navigation. The second parameter is an optional array for setting cache.

$this->navigation('front');
$this->navigation('admin', array('cache_ttl' => 3600));
$this->navigation()->breadcrumbs();	
$this->navigation()->links();	
$this->navigation()->menu();    // rendering menus from navigation containers

Predefine variables

Predefine variables are variables define by system, user can output they value in phtml file directly without define them. These variables are declared in 'usr/module/system/config/config.php' with they default value.

sitename

The variable 'sitename' is the name of site, and its default value is 'Web Applications'.

slogan

This variable describes the slogan of site, and its set to 'Powered by Xoops Engine.' by default.

adminmail

This variable describes administration email address for conveniently contact, it has no default value.

locale

This variable decides which language package to use, its default value set to the locale you choose when you install the XoopsEngine.

charset

This variable the is charset for page to display.

timezone_server

This variable describes timezone set by server, it has no default value.

timezone_system

This variable is the timezone for application system, it also has no default value.

theme, theme_admin

These two variables describe the theme for front end and admin area, respectively, they have the same default value which is 'default'.

[Theme helpers](Theme helpers)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Theme Guide

[简体中文](Theme 开发指南) | فارسی Contents

Introduction

File structure

Layout templates

Introduction of some useful view helper

Predefine variables

Clone this wiki locally