Templates overriding : a small Tutorial
Date 2006/9/23 21:50:00 | Topic: Themes
| This article, translated from french to english by Tripmon(many many thanks to him)/Marco, will explain the Template override concept, a feature introduced from XOOPS 2.0.14.
This news is here in order to help users understand this new concept. This article will demonstrate that by 2 examples.
First, What is a template ?
Templates can display data (as well as sort, position, and conditional display...)
Templates are used to separate the process of displaying data from retrival and manipulation.
This allows non programmers to easily format data for presentation, without modifying underlying code, by simply modifying the template file.
XOOPS comes with its own templates (module system, 26 files), for example:
- system_redirect.html (Redirection page)
- system_siteclosed.html (Closed site page)
- system_block_login.html (Login block)
- system_block_online.html (User on line block)
- system_block_comments.html (Comments block)...
Every recent module also uses templates (pages and blocks).
Example :
News module (15 templates) for example:
- news_archive.html (archives page)
- news_block_new.html (New news block)
- news_block_top.html (better read news block)...
To browse these templates, go to admin system / templates and click on list on the module that you want to see, on the default template set.
The top section shows template pages, with template blocks below.
If these pages and blocks do not display to your liking, it's not a problem, you can modify them with the new functionality included in the core since XOOPS 2.0.14:
Templates overriding.
An excerpt from XOOPS 2.0.14 news:
Quote:Designers can add custom templates to their themes, and those will be used instead of the default ones.
To exploit this feature, templates have to be created in subfolders of the themes duplicating the default folders structure and removing the "templates" part:
To overload :
system_userinfo.html (template located in modules/system/templates/system_userinfo.html), you have to create your custom version in:
/modules/system/system_userinfo.html
To overload :
system_block_login.html (template located in modules/system/templates/blocks/system_block_login.html), you have to create your custom version in:
/modules/system/blocks/system_block_login.html
Explanation:
Now, You don't need to clone your default template set, you can use the default template set (in fact, to override, you MUST), and install the structure file of your modules in the directory.
Bonus :
- In case of "Update" module, your modified files will not be suppressed
- Just modified templates will be installed in directory
- The understanding of custom templates is very easy now (structured files)
- Easy to use
- You can change themes very easily by overriding the default template pack (for example, login block, search block, close site block...)
Page 2: Example 1
Page 3: Example 2
Page 4: Notes and image & css overriding...
Didactic Exemple # 1:
Customization of the template "comments block" (system_block_comments.html from system module)
0a) Test on your test server prior to making production changes.
0b) You must use XOOPS 2.0.14 version or greater, (or version 2.3.x).
0c) If you currently use a cloned template set, you must active the default template set in order to use Overriding.
In this case, you can download the custom templates from your cloned set in order to move them to the proper directories for overriding.
0d) Your block must be visible to see the modification of templates !  (for beginners)
1) First let's download the template block file:
admin system / templates / System list / line system_block_comments.html, [Download]/i]
<table width="100%" cellspacing="1" class="outer">
<{foreach item=comment from=$block.comments}>
<tr class="<{cycle values="even,odd"}>">
<td align="center"><img src="<{$xoops_url}>/images/subject/<{$comment.icon}>" alt="" />td>
<td><{$comment.title}>td>
<td align="center"><{$comment.module}>td>
<td align="center"><{$comment.poster}>td>
<td align="right"><{$comment.time}>td>
tr>
<{/foreach}>
table>
2) Let's modify the file you just downloaded and now have locally.
<table width="100%" cellspacing="1" class="outer">
<{foreach item=comment from=$block.comments}>
<tr class="<{cycle values="even,odd"}>">
[color=FF0000]<td style="text-align: left; vertical-align: middle;">
<img src="<{$xoops_url}>/images/commentaires_ico_16.gif" alt="Commentaire" /> <{$comment.title}>
<div style="text-align:right"><br /><{$comment.module}> - <{$comment.time}> - <{$comment.poster}>div>
td>[/color]
tr>
<{/foreach}>
table>
3) If my theme is 7dana-soft, via ftp, go to the directory
/themes/dana-soft Let's create the directory modules then down and create directory system then down and create directory blocks
4) Let's upload the local file system_block_comments.html to /themes/dana-soft/modules/system/blocks/ on the server.
5) Let's delete the files in the /template_c directory (except index.html) (or update modules cache) in order to see the results of our changes...
 <== default comments bloc - Custum ==>
Thats's all
Didactic Example # 2:
Another example but with the "waiting contents" from the Extensible Waiting Block Module module.
0a 0b 0c 0d Same as example 1
1) First let's download the template block file:
admin system / templates / Waiting Contents Extensible [i]list / line waiting_block_waiting.html, [Download]
<{foreach item=module from=$block.modules}>
<{$module.name}>
<ul>
<{foreach item=pending from=$module.pending}>
<li>
<{if $pending.pendingnum}>
<span style='font-weight:bold;'>
<{else}>
<span style='font-weight:normal;'>
<{/if}>
<a href="<{$pending.adminlink}>"><{$pending.lang_linkname}>a>:<{$pending.pendingnum}>
span>
li>
<{/foreach}>
ul>
<{/foreach}>
2) Let's modify the file you just downloaded and now have locally.
<{foreach item=module from=$block.modules}>
[color=FF0000]<b>[/color]<{$module.name}>[color=FF0000]b>[/color]
<ul>
<{foreach item=pending from=$module.pending}>
<li>
<a href="<{$pending.adminlink}>"><{$pending.lang_linkname}>a> :
<{if $pending.pendingnum}>
[color=FF0000]<font color=red><b>[/color]<{$pending.pendingnum}>[color=FF0000]b>font>[/color]
<{else}>
<{$pending.pendingnum}>
<{/if}>
li>
<{/foreach}>
ul>
[color=FF0000]<hr />[/color]
<{/foreach}>
3) If my theme is 7dana-soft, via ftp, go to the directory
/themes/dana-soft Let's create the directory modules then down and create directory waiting then down and create directory blocks
4) Let's upload the local file waiting_block_waiting.html to /themes/dana-soft/modules/waiting/blocks/ on the server.
5) Let's delete files in the /template_c directory (except index.html) (or update modules cache) to see the result...
 <== Default waiting contents bloc - Custum ==>
Note 1:
In both examples, we have just modifed block templates, but for page templates, upload your files to:
//modules/mymodule
and not in
//modules/mymodule/blocks.
Note 2:
Have a look at this theme, 7dana-clean.
In this theme you will find:
- The new position blocks (bottom center blocks, bottom left blocks, bottom right blocks, )
- 7 templates for overriding
Note 3:
Copy index.html (from templates_c or any other core folder with index.html) to your new directory.
Images overriding
Finally, image overriding is also possible. 2 possible cases:
- If the module used overriding, you can just copy images the same way as templates overridng,
- Either, Let's modify a template and as:
<img src="<{[color=FF0000]xoImgUrl[/color] modules/mymodule/images/image1.gif}>" alt=""/>
Example:
Change image from the news module (the print.gif image)(article.html template from the news module)
Let's replace the following code in the article.html template
<img src="<{$xoops_url}>/modules/news/images/print.gif" border="0" alt="<{$lang_printerpage}>" />
with
<img src="<{[color=FF0000]xoImgUrl [/color]modules/news/images/icon/print.gif}>" border="0" alt="<{$lang_printerpage}>" />
When the page is displayed, the template will display the image located in //modules/news/icon/, and if the image doen't exist, the initial image will be displayed (/modules/news/icon).
CSS overriding
For CSS, overriding is used the same way, but the command is different:
<{$xoTheme->addStylesheet('modules/news/style.css')}>
javascript overriding
More information soon.
For developpers
Friends, when you next update your module(s), consider modifying your original templates with these new functionalities (images overriding, css overriding).
Big thanks to Dugris for his précisions on css, images and javascript.
So, now, you can play with that new feature !
|
|