Project

General

Profile

h1. Subrion Template Standards

Subrion CMS utilizes Smarty template engine. Smarty is the de-facto standard for php to separate application logic and presentation.

h2. Naming conventions

h3. Template folder

Subrion template *.tpl files should be kept in a separate folder. Folder name contains lowercase Latin letters and underscores only. Examples:

simpla_autos
publish_it
segin
locality

h3. Template files

Template file names should only contain Latin letters, digits, and dash. You should not use underscores, slashes, etc. in template filenames. Only .tpl file extension is allowed for template files. Examples:
Incorrect:
view_account.tpl

Correct:
view-account.tpl

h2. Template structure

There are two ways to use templates. You can use header/footer files structure or use single layout.tpl file. Below you can find a detailed instructions for each of these ways.

h3. Header/footer template files

This is a common way to organize template structure for the pages. You can create header.tpl file in your template folder and it will be used on all pages of the script. Footer.tpl file contains common bottom part of your pages. Please ask questions if you have any.

h3. Layout.tpl structure

There could be one common file that contains both header and footer template files content in it. In order to display file content you should use {$content} variable. This structure is optional. If you delete layout.tpl file from your template directory the software will use header/footer layout as default.

h3. Screenshots

For each new template, starting from Subrion core version 3.4, we need a prepared image file (JPG, 800x400) that is located in [template_name]/docs/img with name preview.jpg.
This file will be an overall representation of template which will be shown on template page on subrion.org website.
Please check attachment for more details.

If no image provided, template icon will be used instead.

h3. Package Templates

There is a cool feature to customize templates for packages. If you want to have a custom design/layout for any package you can create a new folder in your templates/template_name/ directory - packages/package_name/ and copy your package_name tpl files to this folder. The script will use template files from this directory. Example:
If you want to have a specific view auto template your 'automarket' template your view-auto.tpl file should be placed under: templates/automarket/packages/autos/view.tpl and in this case Subrion CMS will use this template file for View Auto page.

h2. XML Meta File

Every template folder must have install.xml file. This file contains sensitive information about template. It has the following structure:

<?xml version="1.0" encoding="utf-8" ?>
<!-- The name of template -->
<!-- @name the name must be unique and match folder name, see template naming conventions -->

<!-- The title of template -->
Skeleton

<!-- The description of template -->
<summary>Nice looking template description</summary>

<!-- The author of template -->
<author>John Doe</author>

<!-- The contributor of template -->
<contributor>Intelliants LLC</contributor>

<!-- The version of template -->
<version>1.0.0</version>

<!-- Last updated, use YYYY-MM-DD date format here -->
<date>2010-01-12</date> 

<!-- The min compatible core version -->
<compatibility>3.2.0</compatibility>

<!-- You may disallow template installation if no necessary extras installed -->
<!-- @type extra type, can be package or plugin -->
<!-- @exist 1 - extra must be installed, 0 - extra must not be installed to perform a template installation -->
<!-- Example: the code below allows to install template in case the publishing package is installed -->
<dependency type="package" exist="1">publishing</dependency>

<!-- Changes done on template installation -->
<!-- values to be changed are described in attributes -->
<!-- an identity of the entry is specified as a value of tag -->
<!-- currently supported entities are blocks, menus and fields -->
<!-- when specifying a name for field entity, please take a note that the format is FIELDNAME-ITEMNAME (see ex. below) -->
<!-- note: TYPE and NAME attributes change is restricted -->
<!-- note: all of the previous values are remembered and will be reset once a template is uninstalled -->
<!-- Example 1: the statement activates real_estate_footer block and set its position to footer1 -->
<!-- Example 2: the statement specifies the ZIP field of ESTATES item as non-editable and sets a length to 6 chars -->
<changeset>
    <block status="active" position="footer1">real_estate_footer</block>
    <field length="6" editable="0">zip-estates</field>
    <menu position="inventory">main</menu>
</changeset>

<!-- Layout settings of the template -->
<layout>
    <!-- Position available in current template. It's mandatory to list all the hardcoded positions in your template. -->
    <!-- @menu 1 - prevents block usage in this position -->
    <!-- @access 1 - allows access for certain pages, 0 - prevents access -->
    <!-- @default_access 1 - allows access for all pages (default), 0 - prevents access to this position for all pages -->
    <!-- @pages list of pages to allow/deny access -->

    <!-- Example: prevents blocks in inventory position -->
    <position menu="1">inventory</position>

    <!-- Example: prevents header position display for all pages, only allows its display on index page -->
    <position access="1" pages="index" default_access="0">header</position>

    <!-- Example: displays verytop position on all pages except order page -->
    <position access="0" pages="order">verytop</position>

    <section name="header">
        <position width="4">header1</position>
        <position width="4">header2</position>
        <position width="4">header3</position>
    </section>
    <section name="content">
        <position fixed="1">left</position>
        <position width="6">center</position>
        <position fixed="1">right</position>
    </section>
    <section name="user-blocks">
        <position fixed="1">user1</position>
        <position fixed="1">user2</position>
    </section>
    <section name="footer">
        <position width="3">footer1</position>
        <position width="3">footer2</position>
        <position width="3">footer3</position>
        <position width="3">footer4</position>
    </section>
</layout>

<!-- This option allows to configure CKEditor content cms to match your template font styles. -->
<config group="miscellaneous" name="ckeditor_css" type="hidden" description="CKEditor CSS file">ckeditor.css</config>

<!-- This option allows to make CKEditor skin color look similar to the template. -->
<config group="miscellaneous" name="ckeditor_color" type="text" description="CKEditor color">#AAB</config>

When writing description (summary) for template, do not place dot (period) in the end of sentence:

Cool responsive HTML5/CSS3 template

h2. Inclusion of custom template file that is specific to package

Subrion templates can have the built-in custom template files to be used by packages. In order to include them the following syntax should be used:

{include file='publishing:brief-article.tpl'}

It will force the script to try to include first the
@templates/{current template}/packages/publishing/brief-article.tpl@

and then, if it does not exist, to use the default template included with package
@packages/{active package}/templates/common/brief-article.tpl@

The script is adding the appropriate smarty resources on template engine initialization.

h2. Inclusion of custom template file to the block that is specific to package

Subrion blocks can have the built-in custom template files to be used by packages. In order to include them the following syntax should be used in install.xml file:

It will force the script to try to include first the
@templates/{current template}/packages/publishing/brief-article.tpl@

and then, if it does not exist, to use the default template included with package
@packages/{active package}/templates/common/brief-article.tpl@