Context Navigation

ExiteCMS v8 : Smarty Additions

ExiteCMS is a template driven framework.

When a page is requested, the framework does a lookup of the page in the website content tree, checks which theme and template is defined to display the page, loads the template and displays it.
From this point, the template takes over. It does that by callbacks into ExiteCMS, to fetch the output defined for all sections defined in the template. For this purpose, several new functions have been created for the Smarty template engine.

The documentation for the standard Smarty functions can be found here.

Block functions

{ if_section }

The purpose of this block function is to test if there are elements defined within a specific named template section, and if so, process the template contents of the block. This allows template designers to test for the availability of element output in the template, and make design decisions based on the presence or absence of output.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	yes	n/a	Name of the element section in the template
min	integer	no	1	Minimum number of elements that need to be defined
exact	boolean	no	false	If true, the min value must be met exactly
delay	boolean	no	false	If true, delays processing this section untill all other sections are processed

Example

{if_section name="center" min=1}

   <h2>Print this if there is at least one center element defined that has output</h2>

{/if_section}

The name of the element section can also be an expression. This comes in handy if you want to check or evaluate multiple template sections at once. Both arithmetic and logical operators are supported. Brackets to alter the evaluation are currently NOT supported!

Example

{if_section name="left + right" min=1}

   <h2>Print this if there is at least one element defined in both the left and the right section that has output</h2>

{/if_section}

{ has_task_assigned }

The purpose of this block function is to allow template designers to make output conditional on if a task is assigned to the current user or not.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
task	string	yes	n/a	Name of the task to check
module	string	no	n/a	Optionally, the name of the module that defined the task
value	mixed	no	n/a	Optionally, the constraint value to check
var	string	no	n/a	If specified, a template variable with this name will be created, and set to 1 if the task was assigned, 0 if not

Example

{has_task_assigned task="MY_TASK" module="MY_MODULE"}
   <h1>This task is assigned to me!</h1>
{/has_task_assigned}

{ has_role_assigned }

The purpose of this block function is to allow template designers to make output conditional on if a role is assigned to the current user or not.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
role	string	yes	n/a	Name of the role to check
description	string	no	n/a	Optionally, a descriptive reason for checking. This will be used when access violations are logged
var	string	no	n/a	If specified, a template variable with this name will be created, and set to 1 if the task was assigned, 0 if not

Example

{has_role_assigned role="MY_ROLE"}
   <h1>This role is assigned to me!</h1>
{/has_role_assigned}

{ buttons }

The purpose of this block function is to create an inline or block elements in which you can define buttons using the {button} function or anchors using the {anchor} function. If you use the {anchor} function the link will be styled as a button, but it will still behave as a link.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
style	string	no	n/a	Any additional styling you want to apply to the HTML element
inline	boolean	no	false	If false, a <div> will be generated. If true, a <span> is used

Example

{buttons style="margin:10px 0px;" inline=no}
	{button name="Save" type="submit" image="button_save.png" class="" title="Save the data" text="Normal" disabled=no accesskey="S" tabindex=1}
	{anchor link="http://www.google.com" image="google.png" title="Go to google" new=yes}
{/buttons}

Functions

{ anchor }

The purpose of this function is to create an ExiteCMS compliant link. Several styling options are available.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
text	string	no*	false	Text used on the link. supports the syntax 'lang:[line]:[section]' to get localised text
image	string	no*	n/a	Filename of an image. If no path is specified, it is loaded from the theme images directory
link	string	yes	n/a	URL. If it is a relative link, the link will be converted to an absolute link
title	string	no	n/a	Optional anchor tag title supports the syntax 'lang:[line]:[section]' to get localised titles
segments	string	no	n/a	Any URI segments you want add to the link
onclick	string	no	n/a	Optional javascript to be executed when you use clicks the button
style	string	no	n/a	Any additional style you want to apply to the HTML element
new	boolean	no	false	if true, clicking the link will open a new window
script	boolean	no	false	if true, the URL passed contains javascript code
confirm	string	no	n/a	if specified, this adds a javascript confirm() to the onclick of the link. This string is the confirm question being displayed supports the syntax 'lang:[line]:[section]' to get localised titles

*) Note that either 'text' or 'image' is required.

Example

{anchor text="this is a link" link="javascript: history.go(-1);" script=yes}

{ asset }

This function allows you to load assets from your template.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
id	string	no	n/a	If specified, the tag ID of the HTML tag (not for 'js' and 'css' assets)
name	string	yes	n/a	Filename of the asset. This name must be a filename only, no path information may be included
type	string	yes	n/a	Type of asset being loaded. Currently, it supports 'css', 'js', 'icons' and 'images'
class	string	no	n/a	Any additional class you want to apply to the HTML element (not for 'js' and 'css' assets)
style	string	no	n/a	Any additional style you want to apply to the HTML element (not for 'js' and 'css' assets)
onclick	string	no	n/a	Optional javascript to be executed when you use clicks on the asset (not for 'js' and 'css' assets)
title	string	no	n/a	Text for the asset title tooltip (not for 'js' and 'css' assets) supports the syntax 'lang:[line]:[section]' to get localised titles
module	string	no	n/a	Name of the module that provides the asset. If not given, ExiteCMS will check the assets of the currently loaded module and the currently loaded theme

Example

{asset name="image.png" type="images"}
{asset name="red.css" type="css"}

This produces (if the current theme is 'ExiteCMS8'):

<image src="/assets/themes/ExiteCMS8/images/image.png" />
<link href="/assets/themes/ExiteCMS8/css/red.css" rel="stylesheet" type="text/css" />

{ button }

The purpose of this function is to create an ExiteCMS compliant button. Several styling options are available.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	yes	n/a	Name of the button. This is the name returned by the form_button() function of the Form_validation library
id	string	no	n/a	If specified, the tag ID of the button
text	string	yes	false	Text used on the button. supports the syntax 'lang:[line]:[section]' to get localised text
type	string	no	button	If specified, has to be button, sumbit or reset
image	string	no	n/a	Filename of an image. If no path is specified, it is loaded from the theme images directory
class	string	no	n/a	Any additional class you want to apply to the HTML element
style	string	no	n/a	Any additional style you want to apply to the HTML element
title	string	no	n/a	Text for the button title tooltip supports the syntax 'lang:[line]:[section]' to get localised titles
disabled	boolean	no	false	if true, the button will be disabled
accesskey	string	no	n/a	Any access key you want to assign to the HTML element
tabindex	integer	no	n/a	Any tabindex you want to assign to the HTML element
onclick	string	no	n/a	Optional javascript to be executed when you use clicks the button

Example

{button name="Save" type="submit" image="button_save.png" class="" title="Save the data" text="Normal" disabled=no accesskey="S" tabindex=1}
{button name="normal" type="button" class="positive" title="normal type button" text="Normal" disabled=no accesskey="N" tabindex=2 onclick="alert('hello there!');"}

{ captcha }

The purpose of this function is to display a captcha. The ExiteCMS administration has the ability to select one of the captcha modules available for ExiteCMS, or to disable captcha's all together (p.e. when building an intranet website, where all users are known and/or can be trusted).

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	no	none	Name of the captcha to load. If it doesn't exist, this function defaults to 'none'. Note that you should use '$_env.config.captcha' to use the administrator defined captcha.
id	string	no	n/a	If specified, the tag ID of the captcha image
style	string	no	n/a	Any additional style you want to apply to the captcha image
title	string	no	n/a	Text for the refresh button title tooltip (if present)

Example

{captcha name=$_env.config.captcha id="validate" title="Click to refresh the capcha image" style="margin-left:10px;"}

{ editor }

The purpose of this function is to load a WYSIWYG editor. The ExiteCMS administration has the ability to select one of the editor modules available for ExiteCMS, or to select 'none' to use standard HTML textarea's for editing.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	no	none	Name of the editor to load. If it doesn't exist, this function defaults to 'none'. Note that you should use '$_env.config.editor' to use the administrator defined editor
id	string	no	n/a	If specified, the tag ID of the editor HTML element used
type	string	no	n/a	Type of editor to load. [currently not used]
mode	string	no	basic	Mode in which the editor should be loaded. Currently supported are 'basic' and 'full'. What this means is defined by the editor module creator, 'basic' is usually limited in functionality
style	string	no	n/a	Any additional style you want to apply to the editor HTML element used
value	string	no	n/a	Default content to pass on to the editor (i.e. the contents of the field to be edited

Example

{editor name=$_env.config.editor type="textarea" id="reason" style="width:95%;" value="Please edit me!"}

{ html_header }

The purpose of this function is allow module elements to add javascript or css files to the <head> section of the page. This function uses the same logic as the { asset } function to locate the file to load.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	yes	n/a	Name of the file to load. Use this consistently, as it is used to detect duplicate load requests
type	string	yes	n/a	Type of file being loaded. Currently, it supports 'css', 'js' and 'editor'
value	string	yes	n/a	Filename of the file. This name must be a filename only, no path information may be included

Example

// add the script 'mootools-1.2-core.js' to the <head> section of the page.
{html_header type="js" name="mootools_core" value="mootools-1.2-core.js"}

{ html_select_country }

The purpose of this function is to create a dropdown field from which you user can select a country name. This function is locale aware, and will return a country code from the ISO-3166 table.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	yes	n/a	Name of the form field for this dropdown
id	string	no	n/a	If specified, the tag ID of the <select> tag
class	string	no	n/a	Any additional class you want to apply to the HTML element
style	string	no	n/a	Any additional style you want to apply to the HTML element
default	string	no	n/a	Any valid country code from the ISO-3166 table, or '--' for an unknown country
title	string	no	n/a	Text for the HTML element title tooltip supports the syntax 'lang:[line]:[section]' to get localised titles

Example

{html_select_country name="country_id" id="country_id" default="US" class="styled" style="margin:10px;"}

{ html_select_date }

This function is a modified version of the default Smarty function. You will find the syntax in the Smarty documentation.

The following extra parameters or parameters with added functionality are available to this function:

Attribute Name	Type	Required	Default	Description
field_order	string	no	n/a	If not specified, the function uses the current date and time locale to determine the field order
allow_zero	boolean	no	n/a	If specified and TRUE, a zero timestamp causes all fields to be displayed as '--', if FALSE, a zero timestamp defaults to now()

{ html_select_timezone }

The purpose of this function is to create a dropdown field from which you user can select a timezone. This function is locale aware, and will return CodeIgniter Timezone codes.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	yes	n/a	Name of the form field for this dropdown
id	string	no	n/a	If specified, the tag ID of the <select> tag
class	string	no	n/a	Any additional class you want to apply to the HTML element
style	string	no	n/a	Any additional style you want to apply to the HTML element
default	string	no	UTC	Any valid timezone code from the CodeIgniter Date Helper timezone reference
title	string	no	n/a	Text for the HTML element title tooltip supports the syntax 'lang:[line]:[section]' to get localised titles

Example

{html_select_timezone name="tz_id" id="tz_id" default="UTC" class="styled" style="margin:10px;"}

{ load_lang }

{load_lang} is the Smarty equivalent of the CodeIgniter $this->load->lang() function as provided by the Language Library. It is used to load a language file from within a template.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	yes	""	Name of the language file to load
idioom	string	no	""	Language to load. If not specified, it defaults to the currently selected language
module	string	no	""	Name of the module to load this language file from. If not specified, the file is loaded from the current active module (i.e. to which the template belongs to)

Example

// this loads ./modules/my_exitecms_module/languages/en/my_module_lang.php
{load_lang name="my_module" module="my_exitecms_module" idiom="en"}

{ lang }

{lang} is the Smarty equivalent of the CodeIgniter lang() function as provided by the language_helper. It is used to retrieve a language string from within a template.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
line	string	yes	n/a	Key (language line) of the language string to retrieve
id	string	no	""	Name of the label ID. If set, the function returns the string in a HTML <label> tag
section	string	no	n/a	Name of the language file section the key must be looked up in
assign	string	no	n/a	If defined, assign the result to this variable, do not output it
ignore	boolean	no	false	If TRUE, no error is produced if the language line was not specified

Example

{lang line="username" section="login_panel"}: <input type="text" name="username" value="" size="25" />

Note that if the line was specified but not found, and ignore is FALSE, the line will be returned enclosed in a black on yellow colored <span>. this makes easy to see that you have made a mistake, either in your template, or in your language file.

{ load_section }

{load_section} is a function that will ask ExiteCMS to send the output of all modules within a specific named template section. This allows template designers full flexibility to where in their template they want to place modules, which modules are placed there, and how many.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
name	string	yes	n/a	Name of the module section in the template
type	string	no*	n/a	Type of modules allowed in this position
module	string	no*	n/a	Name of a specific module to load
max	integer	no	unlimited	Maximum number of modules that are allowed to output
title	boolean	no	yes	Indicates whether or not titles are displayed at this position
template	string	no	"none"	Chrome template used to render output at this position

*) Note that either 'type' or 'module' is required.

Example

{load_section type="panel" name="center" max=3 template="xhtml"}

{ sorttable }

This function is deprecated

{ ssprintf }

This function is the Smarty equivalent of the PHP sprintf() function.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
format	string	yes	n/a	sprintf() compliant format string
arguments	mixed	yes	n/a	Arguments for the sprintf() function

Note that, like with the sprintf() function, the order of the variables is important! The names of the variables are not used, you only have to make sure they are unique.

Example

{ssprintf format=$string var1=$var1 [var2=$var2 [...]]}

{ tablenavigation }

This function creates a standard table navigation section, for pagination purposes.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
rows	integer	yes	n/a	total number of rows in the table
first	integer	yes	n/a	number of the first row currently displayed in the table
interval	integer	no	number of rows displayed per page
range	integer	no	3	navigation range, number of pages available left and right of the current page indicator
ajax	string	no	n/a	name of the javascript function to be called to process the json data recieved [not implemented yet]

Note that this function uses the current URI to create the URI used to link to new pages. This way any additional parameters in the URI, like for example sort field and sort order, will be maintained without extra programming. The new top row number will be added to the URI as '/start/<value>'. If this parameter already exists, its value will be replaced by the new value.

The HTML for the navigation block will be generated by a template called 'tablenavigation.tpl', located in the theme template directory. If the current theme doesn't have it, it will be loaded from the ExiteCMS8 default theme. This allows theme designers to create their own template to style this navigation block.

Example

{tablenavigation rows=$rowcount first=$rowstart range=3}

{ variable }

This function is deprecated

Modifiers

| span

The purpose of this modifier is to enclose a string in a <span> tag, optionally assigning it a class name. It is mainly used in combination with the variable replacement functions (sprintf alike) of the { lang } function.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
class	string	no	n/a	Any class you want to assign to the span element

Example

{lang line="l1_cmsversion" section="exitecms_administration_dashboard" ver=$_env.version|span:"highlight" rev=$_env.revision|span:"highlight"}

this produces:

This website is currently running ExiteCMS version <span class="highlight">8.0</span>, revision <span class="highlight">356</span>.

| date_format

The purpose of this modifier is apply a format string to a UNIX timestamp, so that it can be displayed.

The following parameters are available to this function:

Attribute Name	Type	Required	Default	Description
format	string	no	YYYY-MM-DD HH:MM	Any strftime() compatible format string, or any of the predefined strings from the table below
default	timestamp	no	now()	Optionally, you can pass this modifier a default timestamp value.

ExiteCMS defines a list of standard format strings, which can be used in templates. The format for this strings can be defined by the ExiteCMS administrator, via the 'Configuration, Date and Time' menu option. These strings are:

Format string	Description
shortdate	Use it where there is not a lot of space available. A shortdate is in a format like "20090323" or "23-03-09"
longdate	Use it where you have more space. A longdate can be formatted as "Sunday, March 23rd 2009"
shortime	Use it where there is not a lot of space available. A shorttime is usually formatted as "HH:MM"
longtime	A longtime format usually includes seconds, and/or other additions, p.e. "12h, 17m, 10s"
shortdatetime	A combination of shortdate and shorttime
longdatetime	A combination of longdate and longtime

It is encouraged that you use the predefined strings as much as possible, to give the ExiteCMS administration control over the date and time formats.

Example

{$timestamp|date_format:"shortdate"}

Download in other formats:

Plain Text