CoTemplate Introduction

Documentation / Extending Cotonti / Themes / CoTemplate Introduction

What is XTemplate? Template blocks and logic blocks explained.

#1. What is CoTemplate?

CoTemplate is a template engine allows you to store HTML code separately from your PHP code (as opposed to many other template engines, like Samrty do). CoTemplate based on XTemplate class — a fast and lightweight block template engine, but extends it with many useful features such as nested blocks, various kinds of variable interpolation, callbacks, etc. and still is very short and very optimized.

#2. Cotonti and CoTemplate

CoTemplate is using blocks for outputting HTML code. You can think of them as instructions to Cotonti where to output the specific code.

Block syntax

<!-- BEGIN: XXX --> Your code here <!-- END: XXX -->


<!-- BEGIN: XXX --> 

This defines the beginning of the block, and also tells Cotonti how and when to output your code (an example below will hopefully make this clear for everyone)

"Your code here"

Pretty self explanatory, you can insert your HTML code (divs, tables, etc) and Tags ( visit TPL Tags Repository for more info)

<!-- END: XXX -->

Defines the end of block, after this block, Cotonti stops outputting your code


Cotonti defined code, you can find the codes in any .tpl file.


		<br /><br /><hr />

		<div class="pageBody">
			<div class="pageTop"></div>
			<div class="pageText">
				<!-- END: MEMBERSONLY -->
				<!-- BEGIN: DOWNLOAD -->
				{PAGE_FILE_ICON}<a href="{PAGE_FILE_URL}">{PHP.L.Download}: {PAGE_SHORTTITLE}</a><br/>
				<!-- END: DOWNLOAD -->
				{}: {PAGE_FILE_SIZE}{PHP.L.kb}, {} {PAGE_FILE_COUNT} {}
		<!-- END: PAGE_FILE -->

<!-- BEGIN: PAGE_FILE --> instructs Cotonti to output (display it to user) the code below if page has "File Download : Yes" and "URL" of file is entered.

If "File Download:" is set to "No", Cotonti will skip to the end of <!-- END: PAGE_FILE --> and simply continue reading the code after that ending tag (without displaying the code between <!-- BEGIN: PAGE_FILE --><!-- END: PAGE_FILE --> to user).

Image 1. File download is set to No..

Image 1.1 ... link for download won't be displayed on page

Image 2. File download is set to Yes and URL of file is entered...

Image 2.1 ... and now can see the link and download the file

You can think of Blocks as "case logic", and that's pretty much correct as CoTemplate also supports "IF-ELSE" statements, but blocks are also used for defining the beginning and the end of theme parts (template blocks).


<!-- BEGIN: HEADER --> <!-- END: HEADER -->
<!-- BEGIN: MAIN --> <!-- END: MAIN -->
<!-- BEGIN: FOOTER --> <!-- END: FOOTER -->


NOTE! that blocks are case sensitive! e.g.

<!-- BEGIN: HEADER -->
This is valid block!
<!-- END: HEADER -->
<!-- begin: header -->
This is NOT a valid block!
<!-- end: header -->

#3. Disk cache

CoTemplate has disk cache feature. It's an internal cache of CoTemplate and reserved only for it.

If you don't see changes on your site, even though you uploaded modified .tpl file back to server, you will need to clean your "Disk cache" to see the template changes.

Simply go to Administration → Other → Disk cache and clean the cache by clicking on "Purge all". Now you will be able to see the changes you made in your .tpl files.

#4. CoTemplate and logic blocks (IF ELSE statements)

CoTemplate supports IF-ELSE statements (logic blocks). Let's see it i details. 

First we have to understand what is logic block, and what is supported by new CoTemplate.

Logic block:

<!-- IF <if_statement> -->
this will display if <if_statement> is true
<!-- ENDIF -->

For <if_statement> you can use TPL tags or Global tags.


<!-- IF {PHP.usr.profile.user_name} == "admin" -->
hello admin !
<!-- ENDIF -->
<!-- IF {PAGE_DESC} == "" -->
Description of this page is empty
<!-- ENDIF -->
There is some comments here.
And title and description of this page are equal.
<!-- ENDIF -->


Blocks are NOT space sensitive! e.g.

This is valid block!
<!-- ENDIF -->
This is also valid block! 
<!--ENDIF -->


Logical expressions are limited functionality. Supported logical operators are: AND, OR (AND has higher priority). Parenthesis is not supported. Supported comparison operators are: ==, !=, <, >, <=, >=, !. First operand of comparison must be a template variable e.g. {}. Second operand may be a template variable, a number or a quoted string.


<!-- IF {USER_DETAILS_NAME} == 'Mark' AND {PHP.g} >= 6 OR !{PHP.error_string} -->
    <div>The expression is true!</div>
<!-- ELSE -->
    <div>The expression is false!</div>


Nested logical blocks ARE supported, e.g.

<!-- IF {} == 'test' -->
    <!-- IF {} -->
        <div>This block is invalid!</div>
    <!-- ENDIF -->
<!-- ENDIF -->


Template blocks inside of logical blocks ARE supported, e.g. 

<!-- IF {} == 'test' -->
    <!-- BEGIN: BAR -->
        <div>This block is invalid!</div>
    <!-- END: BAR -->
<!-- ENDIF -->


#4.1. Live example: styling author comments

This is something you can see on almost every Wordpress blog. Comment is styled different if the comment author is also the page owner.

The regular comment styling in sed-light theme looks like this:


<span class="title">
<a href="{COMMENTS_ROW_URL}" id="c{COMMENTS_ROW_ID}"><img src="themes/{PHP.theme}/img/system/icon-comment.gif" alt="" /> {COMMENTS_ROW_ORDER}.</a>
 &nbsp; {PHP.themelang.comments.Postedby} {COMMENTS_ROW_AUTHOR}</span> &nbsp; {COMMENTS_ROW_DATE} &nbsp; {COMMENTS_ROW_ADMIN} &nbsp; {COMMENTS_ROW_EDIT} 


<hr />



And we can make it look like this:

by simply editing comments.tpl and inserting some logic blocks.

Here's the code:

<!-- IF {COMMENTS_ROW_AUTHORID} == {PHP.pag.page_ownerid} --> 
<div style="background-color:#C8D9E2; padding: 10px;">
<span class="title">
<a href="{COMMENTS_ROW_URL}" id="c{COMMENTS_ROW_ID}"><img src="{PHP.usr.profile.user_avatar}" width="20" height="20" alt="" /> {COMMENTS_ROW_ORDER}.</a>
 &nbsp; {PHP.themelang.comments.Postedby} {COMMENTS_ROW_AUTHOR}</span> &nbsp; {COMMENTS_ROW_DATE} &nbsp; {COMMENTS_ROW_ADMIN} &nbsp; {COMMENTS_ROW_EDIT} 

 <p>{COMMENTS_ROW_TEXT}</p></div><hr />
<!-- ELSE -->
<span class="title">
<a href="{COMMENTS_ROW_URL}" id="c{COMMENTS_ROW_ID}"><img src="themes/{PHP.theme}/img/system/icon-comment.gif" alt="" /> {COMMENTS_ROW_ORDER}.</a>
 &nbsp; {PHP.themelang.comments.Postedby} {COMMENTS_ROW_AUTHOR}</span> &nbsp; {COMMENTS_ROW_DATE} &nbsp; {COMMENTS_ROW_ADMIN} &nbsp; {COMMENTS_ROW_EDIT} 
<p>{COMMENTS_ROW_TEXT}</p><hr />
<!-- ENDIF -->


As you can see, I changed the background-color and I added user avatar instead of comments icon. You can do much more 
Note: it's recommended not to use direst styling inside your templates. Use CSS classes instead!

No comments yet
Only registered users can post new comments