Theme Guide

[简体中文](Theme 开发指南) Contents

Get start with XoopsEngine theme

Introduction of some useful view helper

Predefine variables

Get start with XoopsEngine theme

Introduction

XoopsEngine allows you to define different themes for different module. You can create your theme package and put it into a folder named 'theme', then it can be install for actual modules. Theme packages mainly contain several front files such as js, css, phtml, etc. These files are packed in different folders. In these section, we will introduce some useful knowledge as follows: creating a theme package, view helper of Xoops and Zend library and 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
          template
              {phtml files}
      config.php

The 'asset' folder contains js, css and image files, these static files have the highest priority, it will override static files of modules. The 'locale' folder contains language files of different countries. The 'template' folder contains lots of phtml files to display HTML tags. The config.php file defines the basic information of the theme, it uses array to store information.

Structure of this article

This article will mainly introduce helper functions for user to use in phtml file, the structure of this article is organized as follows:

section I introduce some details of XoopsEngine helper, and its file structure;

section II introduce how to use some useful helper of XoopsEngine;

section III lists the predefine variables and helper of Xoops and Zend.

Introduction of some useful view helper

You maight found that you have troublesomely wrote scripts in your view page over and over when you code without framework, fortunately, XoopsEngine provides you with plenties 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 fecth 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), numberal (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, repectively. 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

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. [Refering 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 actural 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. [Refering 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 formate 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 output a navigation for your page.

This helper takes two parameters, the first one is name of navigation, and the second is an optional array.

::

 echo $this->navigation('front');

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 adminstration email address for convienient 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 defalut 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, repectively, they have the same default value which is 'default'.