Οδηγός κατασκευής template

Τελευταία ενημέρωση από Elxis Team

Οδηγός κατασκευής template για το Elxis CMS

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.

<?php
// get the Elxis libraries we are going to use
$elxis = eFactory::getElxis();
$eLang = eFactory::getLang();
$eDoc = eFactory::getDocument();
// display the document type before the html tag.
echo $eDoc->getDocType()."\n";
?>
<!-- Start html this way (elxis will append some attributes on the html tag) -->
<html<?php echo $eDoc->htmlAttributes(); ?>>
<!-- Start head section and display its contents (elxis generates it automatically) -->
<head>
<?php $eDoc->showHead(); ?>
<!-- Put your template css file and close the head tag -->
<link rel="stylesheet" href="<?php echo $elxis->secureBase(); ?>/templates/simplicity/css/template<?php echo $eLang->getinfo('RTLSFX'); ?>.css" type="text/css" />
</head>
<body>
<!-- page contents here -->
</body>
</html>

 

$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.

<div class="simple_top">
<h2><a href="<?php echo $elxis->makeURL(); ?>" title="<?php echo $elxis->getConfig('SITENAME'); ?>"> <?php echo $elxis->getConfig('SITENAME'); ?></a></h2>
</div>

 

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

 

<div class="simple_path"><?php $eDoc->pathway(false); ?></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.

 

<div class="simple_main">
<div class="simple_pad">
<?php $eDoc->component(); ?>
</div>
</div>

 

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

 

<?php $eDoc->modules('position name', 'optional style'); ?>

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

<div class="simple_sidecolumn">
<div class="simple_pad">
<?php $eDoc->modules('left'); ?>
<?php $eDoc->modules('right'); ?>
</div>
</div>

 

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.

<div class="simple_footer">
Designed by <a href="http://www.example.com">Example Company</a> - Copyright (c) 2013 Example Inc.
</div>

 

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!

// Fetch the parameters from the database
$db = eFactory::getDB();
$sql = "SELECT ".$db->quoteId('params')." FROM ".$db->quoteId('#__templates')
."\n WHERE ".$db->quoteId('template').' = '.$db->quote('simplicity').' AND '.$db->quoteId('section').' = '.$db->quote('frontend');
$stmt = $db->prepareLimit($sql, 0, 1);
$stmt->execute();
$tplparams = (string)$stmt->fetchResult();

 

// Include the elxisParameters library

 

elxisLoader::loadFile('includes/libraries/elxis/parameters.class.php');
// Construct the absolute path to the template's XML file
$xmlpath = ELXIS_PATH.'/templates/simplicity/simplicity.xml';
// Initialize elxisParameters
$params = new elxisParameters($tplparams, $xmlpath, 'template');
// Get the value of the bgcolour parameter
$bgcolour = trim($params->get('bgcolour', 'EEEEEE'));
// If bgcolour parameter value is empty set the background to the default colour (in this case EEEEEE - light gray)
if ($bgcolour == '') { $bgcolour = 'EEEEEE'; }

 

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.

 

<link rel="stylesheet" href="<?php echo $elxis->secureBase(); ?>/templates/simplicity/css/template<?php echo $eLang->getinfo('RTLSFX'); ?>.css" type="text/css" />
<style type="text/css">body { background-color:#<?php echo $bgcolour; ?>; }</style>
</head>

 

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.

Simplicity 1.0
Πακέτο ZIP, 13.98 KB, 265 λήψεις, 14 Φεβ 2013 21:55

 

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.

CSS rule Description CSS rule Description
Generic lists
ul.elx_stdul Generic unordered list ol.elx_stdol Generic ordered list
Tables
div.elx_tbl_wrapper A wrapper arround tables table.elx_tbl_list Class applied to tables used as lists
table.elx_tbl_list tr.elx_tr0 List table's 1st, 3rd, 5th, ..., rows table.elx_tbl_list tr.elx_tr1 List table's 2nd, 4th, 6th, ..., rows
table.elx_tbl_list tr th.elx_th_sub Sub-title <th> cells table.elx_tbl_list tr th.elx_th_subcenter Sub-title <th> cells centered aligned
Message boxes
.elx_info Informational message box .elx_error Error message box
.elx_warning Warning message box .elx_success Success message box
.elx_textblock Text message block .elx_sminfo Small informational message box
.elx_smerror Small error message box .elx_smwarning Small warning message box
.elx_smsuccess Small success message box    
Forms
.elx_form Applies on <form> tags fieldset.elx_form_fieldset Form fieldset
legend.elx_form_legend Form legend div.elx_form_row Applies on a div element that surrounds a form row.
div.elx_form_cell Applies on a div element that surrounds a form row cell. label.elx_form_label Form lebel
.inputbox Input type=text boxes .filebox Input type=file bozes
.selectbox Drop down select box textarea.textbox Textarea elements
button.elxbutton Generic button button.elxbutton-save Save button
button.elxbutton-search Search button    
Navigation links
.elx_navigation Navigation surrounding box span.elx_nav_page Applies on "Page" before the navigation links
a.elx_nav_link Navigation link a.elx_nav_link_active Navigation active link (current page)
Pathway
div.elx_pathway Pathway surrounding box span.elx_pathway_here Applies on "You are here" before the pathway
span.pathway_text Non-linkable pathway text a.pathway Pathay links
Category page
div.elx_category_page Category page container box div.elx_category_summary Category summary
img.elx_category_image Category's image ul.elx_subcategories List listing category's sub-categories
div.elx_featured_box Featured article container box div.elx_short_box Short article container box
div.elx_dateauthor Article's date and author line div.elx_content_imagebox Main article's image outer box
div.elx_category_featured_inner Box arround the featured article's text p.elx_content_subtitle Article's sub-title
p.elx_content_short Text of short articles ul.elx_links_box List listing articles displayed as lists
Article page
div.elx_article_page Article page container box div.elx_tags_box A box containing the article's tags
div.elx_hits_box Article's hits counter box    
.elx_chain_previous Previous chained article box .elx_chain_next Next chained article box
.elx_chain_previous .elx_chain_title Title of the previous chained article .elx_chain_next .elx_chain_title Title of the next chained article
.elx_chain_previous img Image of previous chained article .elx_chain_next img Image of next chained article
.elx_chain_previous a Link to previous chained article .elx_chain_next a Link to next chained article
ul.elx_comments_box Comments list img.elx_comment_avatar Avatar image on comments list
div.elx_comment_actions Comment actions container div.elx_comment_author Comment author
div.elx_comment_date Comment date div.elx_comment_message Comment message
Tags page
div.elx_tags_page Tags page container box    
RSS/ATOM feeds page
div.elx_feeds_page Feeds page container box table.elx_feeds_tbl Feeds list table
Component search
.elx_engines_box Search engines surrounding box span.elx_engine_current Current search engine
.elx_search_summary A summary of the search results    
Component user
ul.elx_ulist Members list div.elx_avatar_box Image avatar box
div.elx_profile_summary Profile summary box div.elx_profile_details Profile details box
.elx_user_bottom_links Bottom links container box .elx_user_links Links container box
div.elx_profile_twitter Twitter profile box div.elx_profile_twitter_user Twitter profile username
div.elx_profile_twitter_summary Twitter profile summary    
Gallery module
mod_gallery_box A box surrounding the gallery module .mod_gallery_more More link surrounding box
Login module
.modlogin_wrapper A box surrounding the login module .modlogin_pretext Text shown before the login form
.modlogin_posttext Text shown after the login form .modlogin_wrapper form Applies on login form tag
.modlogin_uname_row Username field row .modlogin_pword_row Password field row
.modlogin_remember_row Rememener me field row .modlogin_linksbox Links container box
a.modlogin_profile Link to user profile a.modlogin_logout Logout link
.modlogin_authbox Authentication methods container box .modlogin_group User group
.modlogin_online Online users .modlogin_method Authentication method
Who is online module
.whoisonline Surrounding box .whoisonline_thumbs Surrounding box for image links
Various
#innerpage Popup and lightbox pages surrounding box .elx_back Back link

 

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.

 

Έχει διαβαστεί 17537 φορές
Πολλαπλά onload events
Προηγούμενο άρθρο
Πολλαπλά onload events
Οδηγός κατασκευής plugin
Επόμενο άρθρο
Οδηγός κατασκευής plugin

Μπορείτε να αντιγράψετε, διανείμετε και παρουσιάσετε τα άρθρα αυτού του ιστότοπου για μη εμπορικούς σκοπούς.
Creative Commons 3.0