A guide on developing templates for Elxis

Templates control the layout and style for the whole site. They can be installed from the administration area as any other Elxis extension type. In this guide we will show you how you can create a simple template for Elxis. This template can be downloaded as a ready to be installed Elxis extension for further testing and study.

Table of contents

Requirements
Template files
The XML file
index.php
        Template's header
        Template's body
        Add dynamic content
        The footer
Working with template parameters
Packaging and installation
        Download template Simplicity
        Manual install a template
Typography and standard CSS
Notes

 

Requirements

 

To follow this guide and develop a template you need to know CSS ^[1], HTML and a little PHP (the PHP code you will need to write is almost copy-paste). You will also need some basic knowledge on Elxis document library, on installation XML file syntax which has been fully described in our modules development guide, on Elxis parameters and probably to other guides in this site depending on what you want to do with your template. CSS ^[1] knowledge is absolutely required to style the template. We will start with a plain HTML layout and convert it into a usable Elxis 2-columns template.

 

Template files

 

A template has a number of required and a number of optional files. All templates resides under the templates/ folder in Elxis filesystem. Templates for the backend section are under the templates/admin/ folder. A template named "sample" will have all of its files under templates/sample/ folder (or templates/admin/sample/ if it is for the backend section). In this guide we will build a sample template named Simplicity (simplicity).

Begin by creating the folder templates/simplicity/. Inside the simplicity folder create 2 files: index.php and simplicity.xml ^[2]. These are the absolutely required files for a template, other files are optional although you will surely need a css file to put your styling rules and maybe some images (this is why we also mark template.css as required).

simplicity/
	simplicity.xml (required - contains XML parameters and information about the template such as version, author, etc)
	index.php (required - the php file Elxis executes)
	inner.php (optional - the php file Elxis executes on inner pages, e.g. popup windows)
	mobile.php (optional - since Elxis 4.1 - the php file Elxis executes for handheld/mobile devices)
	install.php (optional - contains actions to be performed during template install, uninstall and update).
	simplicity.png (optional - a small preview for the template, 200-300 pixels width is fine)
	language/
		en.tpl_simplicity.php (optional - English language file)
		el.tpl_simplicity.php (optional - Hellenic language file)
		it.tpl_simplicity.php (optional - Italian language file)
		...etc..
	css/
		template.css (required - contains styling rules)
		template-rtl.css (optional - contains styling rules for Right-To-Left languages)

You can also include into the template's root folder any of the Exit pages Elxis supports (error 404, error 403, site offline, etc). By doing so you can overwrite the general ones with your own custom ones. It is cool to have your own exit pages ;-)

 

The XML file

 

The structure and contents of the installation XML file (simplicity.xml) is the same as for any other Elxis extension type. Consider our modules development guide on how to format in this file. Don't forget that the extension type is template. For documentation purposes we will use an XML parameter in our template of type color for setting the background colour of the pages. We will name this parameter bgcolour. The default value of this parameter is set to EEEEEE (light gray).

<package type="template" section="frontend">
	<name>simplicity</name>
	<title>Simplicity</title>
	...
	<params>
		<param type="color" name="bgcolour" default="EEEEEE" label="Background colour" description="" />
	</params>
</package>

 

index.php

 

index.php file is used to draw the HTML layout for the template, load CSS and javascript files, load modules, the site pathway and the component.

 

Template's header

 

All HTML documents have a <head></head> section. We will use some PHP to built this easily. The elxisDocument library does the most of this job automatically. Here is a typical HTML document.

<html>
	<head>
		...
	</head>
	<body>
		...
	</body>
</html>

We use Elxis Document to create the head section. We will also need the Elxis Framework and Elxis Language libraries.

 

$eLang->getinfo('RTLSFX') will return the string -rtl on Right-To-Left languages (so css file template-rtl.css) and an empty string for Left-To-Right languages so css file template.css.

 

 

Template's body

 

We are now ready to work on the <body></body> section of the template. The template is a normal HTML document. The designed layout follows the HTML tags and the loaded CSS. There are only a few Elxis specific areas for loading the modules, the component and the pathway. To load the modules assigned to a position left use $eDoc->modules('left'). To load the component use $eDoc->component(). To display the pathway write: $eDoc->pathway(). It's easy, don't you think? So, let's write some HTML for the layout.

<body>
	<div class="simple_wrapper">
		<div class="simple_top">
			Site top
		</div>
		<div class="simple_path">Pathway</div>
		<div class="simple_middlewrap">
			<div class="simple_middle">
				<div class="simple_main">
					<div class="simple_pad">
						Main page contents
					</div>
				</div>
				<div class="simple_sidecolumn">
					<div class="simple_pad">
						Left column
					</div>
				</div>
			</div>
		</div>
		<div class="clear"></div>
		<div class="simple_footer">
			Page footer
		</div>
	</div>
</body>

Our template has 5 main sections: Site top, Pathway, Left column, Main page contents and Page footer. We use an offset based technic to create a 2 columns layout with equal heights and also we put "Main page contents" container div before the side column contents in order search engines to focus more on the page copntent rather than the modules on the side column. We will provide a right direction float to these 2 DIV elements to reverse the visual position of these blocks. So, at the end the side column will be displayed into the left and the main page contents into the right. Put the CSS rules shown below into the template.css file. (In the sample template provided below for download there is also an RTL version).

body { margin:0; padding:0; background-color:#EEEEEE; }
div { margin:0; padding:0; }
.simple_wrapper { margin:20px auto; width:970px; border:1px solid #bbb; }
.simple_top { padding:20px; background-color:#CBE1F1; }
.simple_top h2 { margin:0; padding:0;  font:normal 22px/28px Georgia, "Times New Roman", Times, serif; }
.simple_top h2 a { color:#444; text-decoration:none; }
.simple_path { margin:0; padding:5px 10px; background-color:#87afe5; }
.simple_middlewrap { width:970px; float:left; overflow:hidden; background-color:#FFFFFF; }
.simple_middle { position:relative; right:770px; width:970px; float:left; background-color:#CCC; }
.simple_main { position:relative; left:770px; float:right; width:770px; }
.simple_sidecolumn { position:relative; left:770px;  float:right;  width:200px; }
.simple_footer {
	padding:10px; border-top:1px solid #BBB; background-color:#e2e2e2; text-align:center;
	font:normal 12px/16px geneva, arial, sans-serif; color:#666;
}
.simple_footer a { color:#222; text-decoration:none; }
.simple_pad { padding:5px; }
.clear { clear:both; }

 

Add dynamic content

 

It is easy to import into this HTML only layout dynamic content from Elxis. At first we will display the site's title within the "Site top" area. We will make this title linkable so when someone clicks it he will go to the site's frontpage.

 

Now let's inport the pathway Elxis automatically generates into the simple_path DIV

 

The pathway method accepts a boolean attribute that controls the display of the "You are here" string in front of the pathway.
$eDoc->pathway(true) will display You are here: Mplah > mplah
$eDoc->pathway(false) will display just the pathway without the You are here prefix: Mplah > mplah

 

Display the main page's contents generated by the requested component inside the simple_main DIV by using the component method of the elxisDocument library.

 

 

To display the modules of a modules position into an area of this template use the modules ^[3] method of the elxisDocument library.

 

Let's include the modules assigned into the left and right module positions ^[4] into our template.

 

The footer

 

You can display some modules on your footer like we did on the side column, a copyright message, or anything else. Here for simplicity we will display a short " designed by" message.

 

Working with template parameters

 

If your template doesn't use parameters you can ommit this part. We will provide the user the option to change the template's background colour without having to modify the CSS files. For this purpose we will use the bgcolour parameter we declared in the XML file. Parameters are stored in the database as a string. They are separated with a newline break (\n) so they can not be used directly, we need to parse them with the elxisParameters library to make them usable.

param1=value1\nparam2=value2\nparam3=value3...

We recommend the whole process of parameters to be placed in an external file (in a template's addon class) in order to keep the index.php file with just the basic layout. In this tutorial for simplicity we will put this process in top of the index.php file. Let's begin!

 

 

 

A more advanced developer could save the resulted parameters values in APC cache. This way we wont have to execute the above code on each page refresh.

 

 

Now that we have collected the user's preferable background colour ($bgcolour) we will overwrite the default template's background color with the new value. We must do that after the load of the template.css file, else the new value wont be applied.

 

 

Packaging and installation

 

The template is finished! Off course it is ugly. You must work on the CSS to beautify it but I think you got the idea on how to create a template for Elxis CMS. You can pack all the template files in a zip package named tpl_simplicity_1.0.zip and install it as usual from the Elxis administration console. On the modules development guide you will find more i nfo about this process.

 

Download sample template

 

Download template Simplicity we created in this guide to study it further and work on it.

 

Manual install a template

 

A template is not available in Elxis unless you install it

So, despite if the template files exist in the proper path Elxis wont load or use it. You must install it first. If you haven't yet created a package you can manually install the template! How? Go to your database manager (eg. phpmyadmin) and execute a command such the one below.

INSERT INTO elx_templates VALUES (NULL, 'Simplicity', 'simplicity', 'frontend', 0, NULL);

That's it! Make sure that the required template files exist in the proper path and then go to Elxis configuration and switch the template to your new one. You can now continue working on the template and you can refresh the pages to see your changes. You can see below the recommended steps when you want to start developing a new template.

1. Create the template's folder
2. Create the absolutely required files for the template (index.php, simplicity.xml, css/template.css)
3. Write the contents of the XML file
4. Install manually the template by executing an SQL command in the database
5. Set the new template as the site's template in Elxis configuration
6. Continue working on the template files and CSS.

 

Typography and standard CSS

 

Elxis has an article on the sample contents named Typography. This is a showcase of some basic elements used by Elxis. You can use this page as a way to see how your template styles these elements. Such elements are lists, paragraphs, message boxes, featured and short articles, forms and buttons, images, links and more.

The standard CSS (templates/system/css/standard.css) applies a very basic style on Elxis pages and it is used as a failover stylesheet. Never edit it! The standard CSS makes sure your pages wont break or stay without at least a very basic styling if you forget to style an element in your CSS. Your styling rules in your own CSS file will overwrite the values from the standard CSS. The standard CSS can also be used as an index of all Elxis default styling CSS classes. The table below displays a list of the most important CSS definitions Elxis core uses and a short description for each one.

 

Notes

 

1. CSS tutorial on w3schools.
2. For backwards compatibility with Elxis 2009.x, the XML file can also be named templateDetails.xml
3. Inclusion of modules, pathway and component into the template.
4. Normally module position left is for the template's left column and module position right for the template's right column but as our template has only one column we will display both left and right module positions into the left column of the template. We recommend you do this trick in single column templates.