Smarty - the compiling PHP template engine
Prev	Chapter 3. Template Language	Next

Custom Functions

Smarty comes with several custom functions that you can use in the templates.

Custom Functions

assign

Attribute Name	Type	Required	Default	Description
var	string	Yes	n/a	The name of the variable being assigned
value	string	Yes	n/a	The value being assigned

assign is used for assigning template variables during the execution of the template.

NOTE: This was added to Smarty 1.4.3.

Example 3-63. assign

{assign var="name" value="Bob"}

The value of $name is {$name}.

OUTPUT:

The value of $name is Bob.

counter

Attribute Name	Type	Required	Default	Description
id	string	No	default	The id of the counter
start	number	No	1	The initial number to start counting from
skip	number	No	1	The interval to count by
direction	string	No	up	the direction to count (up/down)
print	boolean	No	true	Whether or not to print the value
assign	string	No	n/a	the template variable the output will be assigned to

counter is used to print out a count. counter will remember the count on each iteration. You can adjust the number, the interval and the direction of the count, as well as determine whether or not to print the value. You can run multiple counters concurrently by supplying a unique id for each one. If you do not supply an id, the default id will be used. counter was added to Smarty 1.4.0.

If you supply the special "assign" attribute, the output of the counter function will be assigned to this template variable instead of being output to the template. (new in Smarty 1.5.0)

Example 3-64. counter

{* initialize the count *}
{counter start=0 skip=2 print=false}

{counter}<br>
{counter}<br>
{counter}<br>
{counter}<br>

OUTPUT:

2<br>
4<br>
6<br>
8<br>

eval

Attribute Name	Type	Required	Default	Description
var	mixed	Yes	n/a	variable (or string) to evaluate
assign	string	No	n/a	the template variable the output will be assigned to

eval is used to evaluate a variable as a template. This can be used for things like embedding template tags/variables into variables or tags/variables into config file variables.

If you supply the special "assign" attribute, the output of the eval function will be assigned to this template variable instead of being output to the template.

Technical Note: Evaluated variables are treated the same as templates. They follow the same escapement and security features just as if they were templates.

Technical Note: Evaluated variables are compiled on every invocation, the compiled versions are not saved! However if you have caching enabled, the output will be cached with the rest of the template.

Example 3-65. eval

setup.conf
----------

emphstart = <b>
emphend = </b>
title = Welcome to {$company}'s home page!
ErrorCity = You must supply a {#emphstart#}city{#emphend#}.
ErrorState = You must supply a {#emphstart#}state{#emphend#}.


index.tpl
---------

{config_load file="setup.conf"}

{eval var=$foo}
{eval var=#title#}
{eval var=#ErrorCity#}
{eval var=#ErrorState# assign="state_error"}
{$state_error}

OUTPUT:

This is the contents of foo.
Welcome to Foobar Pub & Grill's home page!
You must supply a <b>city</b>.
You must supply a <b>state</b>.

fetch

Attribute Name	Type	Required	Default	Description
file	string	Yes	n/a	the file, http or ftp site to fetch
assign	string	No	n/a	the template variable the output will be assigned to

fetch is used to fetch files from the local file system, http, or ftp and display the contents. If the file name begins with "http://", the web site page will be fetched and displayed. If the file name begins with "ftp://", the file will be fetched from the ftp server and displayed. For local files, the full system file path must be given, or a path relative to the executed php script.

If you supply the special "assign" attribute, the output of the fetch function will be assigned to this template variable instead of being output to the template. (new in Smarty 1.5.0)

Technical Note: This will not support http redirects, be sure to include a trailing slash on your web page fetches where necessary.

Technical Note: If template security is turned on and you are fetching a file from the local file system, this will only allow files from within one of the defined secure directories. ($secure_dir)

Example 3-66. fetch

{* include some javascript in your template *}
{fetch file="/export/httpd/www.domain.com/docs/navbar.js"}

{* embed some weather text in your template from another web site *}
{fetch file="http://www.myweather.com/68502/"}

{* fetch a news headline file via ftp *}
{fetch file="ftp://user:[email protected]/path/to/currentheadlines.txt"}

{* assign the fetched contents to a template variable *}
{fetch file="http://www.myweather.com/68502/" assign="weather"}
{if $weather ne ""}
	<b>{$weather}</b>
{/if}

html_options

Attribute Name	Type	Required	Default	Description
values	array	Yes, unless using options attribute	n/a	an array of values for dropdown
output	array	Yes, unless using options attribute	n/a	an array of output for dropdown
selected	string	No	empty	the selected array element
options	associative array	Yes, unless using values and output	n/a	an associative array of values and output

html_options is a custom function that creates html option lists with provided data. It takes care of which item is selected by default as well. Required attributes are values and output, unless you use options instead.

NOTE: As of Smarty 1.4.5, html_options now outputs xhtml compatible code.

Example 3-67. html_options

{* assume that $cust_ids, and $cust_names are arrays of values,
	and $customer_id may or may not be set to a value *}

<select name=customer_id>
	{html_options values=$cust_ids selected=$customer_id output=$cust_names}
</select>


{* an alternative method is to pass the values & output as an associative array into
   options. $customer_options is an associative array in this example. This
   functionality was added to Smarty 1.3.0 *}

<select name=customer_id>
	{html_options options=$customer_options selected=$customer_id}
</select>


OUTPUT:

<select name=customer_id>
	<option value="1000">Joe Schmoe</option>
	<option value="1001" selected="selected">Jack Smith</option>
	<option value="1002">Jane Johnson</option>
	<option value="1003">Charlie Brown</option>
</select>

html_select_date

Attribute Name	Type	Required	Default	Description
prefix	string	No	Date_	what to prefix the var name with
time	timestamp	No	current time	what date/time to use
start_year	string	No	current year	the first year in the dropdown, either year number, or relative to current year (+/- N)
end_year	string	No	same as start_year	the last year in the dropdown, either year number, or relative to current year (+/- N)
display_days	boolean	No	true	whether to display days or not
display_months	boolean	No	true	whether to display months or not
display_years	boolean	No	true	whether to display years or not
month_format	string	No	%B	what format the month should be in (strftime)
day_format	string	No	%02d	what format the day should be in (sprintf)
year_as_text	boolean	No	false	whether or not to display the year as text
reverse_years	boolean	No	false	display years in reverse order
field_array	string	No	null	if a name is given, the select boxes will be drawn such that the results will be returned to PHP in the form of name[Day], name[Year], name[Month].
day_size	string	No	null	adds size attribute to select tag if given
month_size	string	No	null	adds size attribute to select tag if given
year_size	string	No	null	adds size attribute to select tag if given
all_extra	string	No	null	adds extra attributes to all select/input tags if given
day_extra	string	No	null	adds extra attributes to select/input tags if given
month_extra	string	No	null	adds extra attributes to select/input tags if given
year_extra	string	No	null	adds extra attributes to select/input tags if given
field_order	string	No	MDY	the order in which to display the fields
field_separator	string	No	\n	string printed between different fields

html_select_date is a custom function that creates date dropdowns for you. It can display any or all of year, month, and day.

NOTE: reverse_years, field_array, day_size, month_size, year_size, all_extra, day_extra, month_extra, year_extra, field_order, field_separator added in Smarty 1.4.5.

Example 3-68. html_select_date

{html_select_date}


OUTPUT:

<select name="Date_Month">
<option value="1">January</option>
<option value="2">February</option>
<option value="3">March</option>
<option value="4">April</option>
<option value="5">May</option>
<option value="6">June</option>
<option value="7">July</option>
<option value="8">August</option>
<option value="9">September</option>
<option value="10">October</option>
<option value="11">November</option>
<option value="12" selected>December</option>
</select>
<select name="Date_Day">
<option value="1">01</option>
<option value="2">02</option>
<option value="3">03</option>
<option value="4">04</option>
<option value="5">05</option>
<option value="6">06</option>
<option value="7">07</option>
<option value="8">08</option>
<option value="9">09</option>
<option value="10">10</option>
<option value="11">11</option>
<option value="12">12</option>
<option value="13" selected>13</option>
<option value="14">14</option>
<option value="15">15</option>
<option value="16">16</option>
<option value="17">17</option>
<option value="18">18</option>
<option value="19">19</option>
<option value="20">20</option>
<option value="21">21</option>
<option value="22">22</option>
<option value="23">23</option>
<option value="24">24</option>
<option value="25">25</option>
<option value="26">26</option>
<option value="27">27</option>
<option value="28">28</option>
<option value="29">29</option>
<option value="30">30</option>
<option value="31">31</option>
</select>
<select name="Date_Year">
<option value="2001" selected>2001</option>
</select>

Example 3-69. html_select_date

{* start and end year can be relative to current year *}
{html_select_date prefix="StartDate" time=$time start_year="-5" end_year="+1" display_days=false}

OUTPUT: (current year is 2000)

<select name="StartDateMonth">
<option value="1">January</option>
<option value="2">February</option>
<option value="3">March</option>
<option value="4">April</option>
<option value="5">May</option>
<option value="6">June</option>
<option value="7">July</option>
<option value="8">August</option>
<option value="9">September</option>
<option value="10">October</option>
<option value="11">November</option>
<option value="12" selected>December</option>
</select>
<select name="StartDateYear">
<option value="1999">1995</option>
<option value="1999">1996</option>
<option value="1999">1997</option>
<option value="1999">1998</option>
<option value="1999">1999</option>
<option value="2000" selected>2000</option>
<option value="2001">2001</option>
</select>

html_select_time

Attribute Name	Type	Required	Default	Description
prefix	string	No	Time_	what to prefix the var name with
time	timestamp	No	current time	what date/time to use
display_hours	boolean	No	true	whether or not to display hours
display_minutes	boolean	No	true	whether or not to display minutes
display_seconds	boolean	No	true	whether or not to display seconds
display_meridian	boolean	No	true	whether or not to display meridian (am/pm)
use_24_hours	boolean	No	true	whether or not to use 24 hour clock
minute_interval	integer	No	1	number interval in minute dropdown
second_interval	integer	No	1	number interval in second dropdown
field_array	string	No	n/a	outputs values to array of this name

html_select_time is a custom function that creates time dropdowns for you. It can display any or all of hour, minute, second and meridian.

Example 3-70. html_select_time

{html_select_time use_24_hours=true}


OUTPUT:

<select name="Time_Hour">
<option value="00">00</option>
<option value="01">01</option>
<option value="02">02</option>
<option value="03">03</option>
<option value="04">04</option>
<option value="05">05</option>
<option value="06">06</option>
<option value="07">07</option>
<option value="08">08</option>
<option value="09" selected>09</option>
<option value="10">10</option>
<option value="11">11</option>
<option value="12">12</option>
<option value="13">13</option>
<option value="14">14</option>
<option value="15">15</option>
<option value="16">16</option>
<option value="17">17</option>
<option value="18">18</option>
<option value="19">19</option>
<option value="20">20</option>
<option value="21">21</option>
<option value="22">22</option>
<option value="23">23</option>
</select>
<select name="Time_Minute">
<option value="00">00</option>
<option value="01">01</option>
<option value="02">02</option>
<option value="03">03</option>
<option value="04">04</option>
<option value="05">05</option>
<option value="06">06</option>
<option value="07">07</option>
<option value="08">08</option>
<option value="09">09</option>
<option value="10">10</option>
<option value="11">11</option>
<option value="12">12</option>
<option value="13">13</option>
<option value="14">14</option>
<option value="15">15</option>
<option value="16">16</option>
<option value="17">17</option>
<option value="18">18</option>
<option value="19">19</option>
<option value="20" selected>20</option>
<option value="21">21</option>
<option value="22">22</option>
<option value="23">23</option>
<option value="24">24</option>
<option value="25">25</option>
<option value="26">26</option>
<option value="27">27</option>
<option value="28">28</option>
<option value="29">29</option>
<option value="30">30</option>
<option value="31">31</option>
<option value="32">32</option>
<option value="33">33</option>
<option value="34">34</option>
<option value="35">35</option>
<option value="36">36</option>
<option value="37">37</option>
<option value="38">38</option>
<option value="39">39</option>
<option value="40">40</option>
<option value="41">41</option>
<option value="42">42</option>
<option value="43">43</option>
<option value="44">44</option>
<option value="45">45</option>
<option value="46">46</option>
<option value="47">47</option>
<option value="48">48</option>
<option value="49">49</option>
<option value="50">50</option>
<option value="51">51</option>
<option value="52">52</option>
<option value="53">53</option>
<option value="54">54</option>
<option value="55">55</option>
<option value="56">56</option>
<option value="57">57</option>
<option value="58">58</option>
<option value="59">59</option>
</select>
<select name="Time_Second">
<option value="00">00</option>
<option value="01">01</option>
<option value="02">02</option>
<option value="03">03</option>
<option value="04">04</option>
<option value="05">05</option>
<option value="06">06</option>
<option value="07">07</option>
<option value="08">08</option>
<option value="09">09</option>
<option value="10">10</option>
<option value="11">11</option>
<option value="12">12</option>
<option value="13">13</option>
<option value="14">14</option>
<option value="15">15</option>
<option value="16">16</option>
<option value="17">17</option>
<option value="18">18</option>
<option value="19">19</option>
<option value="20">20</option>
<option value="21">21</option>
<option value="22">22</option>
<option value="23" selected>23</option>
<option value="24">24</option>
<option value="25">25</option>
<option value="26">26</option>
<option value="27">27</option>
<option value="28">28</option>
<option value="29">29</option>
<option value="30">30</option>
<option value="31">31</option>
<option value="32">32</option>
<option value="33">33</option>
<option value="34">34</option>
<option value="35">35</option>
<option value="36">36</option>
<option value="37">37</option>
<option value="38">38</option>
<option value="39">39</option>
<option value="40">40</option>
<option value="41">41</option>
<option value="42">42</option>
<option value="43">43</option>
<option value="44">44</option>
<option value="45">45</option>
<option value="46">46</option>
<option value="47">47</option>
<option value="48">48</option>
<option value="49">49</option>
<option value="50">50</option>
<option value="51">51</option>
<option value="52">52</option>
<option value="53">53</option>
<option value="54">54</option>
<option value="55">55</option>
<option value="56">56</option>
<option value="57">57</option>
<option value="58">58</option>
<option value="59">59</option>
</select>
<select name="Time_Meridian">
<option value="am" selected>AM</option>
<option value="pm">PM</option>
</select>

math

Attribute Name	Type	Required	Default	Description
equation	string	Yes	n/a	the equation to execute
format	string	No	n/a	the format of the result (sprintf)
var	numeric	Yes	n/a	equation variable value
assign	string	No	n/a	template variable the output will be assigned to
[var ...]	numeric	Yes	n/a	equation variable value

math allows the template designer to do math equations in the template. Any numeric template variables may be used in the equations, and the result is printed in place of the tag. The variables used in the equation are passed as parameters, which can be template variables or static values. +, -, /, *, abs, ceil, cos, exp, floor, log, log10, max, min, pi, pow, rand, round, sin, sqrt, srans and tan are all valid operators. Check the PHP documenation for further information on these math functions.

If you supply the special "assign" attribute, the output of the math function will be assigned to this template variable instead of being output to the template.

Example 3-71. math

{* $height=4, $width=5 *}

{math equation="x + y" x=$height y=$width}

OUTPUT:

9


{* $row_height = 10, $row_width = 20, #col_div# = 2, assigned in template *}

{math equation="height * width / division"
      height=$row_height
      width=$row_width
      division=#col_div#}

OUTPUT:

100


{* you can use parenthesis *}

{math equation="(( x + y ) / z )" x=2 y=10 z=2}

OUTPUT:

6


{* you can supply a format parameter in sprintf format *}

{math equation="x + y" x=4.4444 y=5.0000 format="%.2f"}

OUTPUT:

9.44

popup_init

popup is an integration of overLib, a library used for popup windows. These are used for context sensitive information, such as help windows or tooltips. popup_init must be called once at the top of any page you plan on using the popup function. overLib was written by Erik Bosrup, and the homepage is located at http://www.bosrup.com/web/overlib/.

This was added to Smarty 1.4.4.

popup

Attribute Name	Type	Required	Default	Description
text	string	Yes	n/a	the text/html to display in the popup window
trigger	string	No	onMouseOver	What is used to trigger the popup window. Can be one of onMouseOver or onClick
sticky	boolean	No	false	Makes the popup stick around until closed
caption	string	No	n/a	sets the caption to title
fgcolor	string	No	n/a	color of the inside of the popup box
bgcolor	string	No	n/a	color of the border of the popup box
textcolor	string	No	n/a	sets the color of the text inside the box
capcolor	string	No	n/a	sets color of the box's caption
closecolor	string	No	n/a	sets the color of the close text
textfont	string	No	n/a	sets the font to be used by the main text
captionfont	string	No	n/a	sets the font of the caption
closefont	string	No	n/a	sets the font for the "Close" text
textsize	string	No	n/a	sets the size of the main text's font
captionsize	string	No	n/a	sets the size of the caption's font
closesize	string	No	n/a	sets the size of the "Close" text's font
width	integer	No	n/a	sets the width of the box
height	integer	No	n/a	sets the height of the box
left	boolean	No	false	makes the popups go to the left of the mouse
right	boolean	No	false	makes the popups go to the right of the mouse
center	boolean	No	false	makes the popups go to the center of the mouse
above	boolean	No	false	makes the popups go above the mouse. NOTE: only possible when height has been set
below	boolean	No	false	makes the popups go below the mouse
border	integer	No	n/a	makes the border of the popups thicker or thinner
offsetx	integer	No	n/a	how far away from the pointer the popup will show up, horizontally
offsety	integer	No	n/a	how far away from the pointer the popup will show up, vertically
fgbackground	url to image	No	n/a	defines a picture to use instead of color for the inside of the popup.
bgbackground	url to image	No	n/a	defines a picture to use instead of color for the border of the popup. NOTE: You will want to set bgcolor to "" or the color will show as well. NOTE: When having a Close link, Netscape will re-render the table cells, making things look incorrect
closetext	string	No	n/a	sets the "Close" text to something else
noclose	boolean	No	n/a	does not display the "Close" text on stickies with a caption
status	string	No	n/a	sets the text in the browsers status bar
autostatus	boolean	No	n/a	sets the status bar's text to the popup's text. NOTE: overrides status setting
autostatuscap	string	No	n/a	sets the status bar's text to the caption's text. NOTE: overrides status and autostatus settings
inarray	integer	No	n/a	tells overLib to read text from this index in the ol_text array, located in overlib.js. This parameter can be used instead of text
caparray	integer	No	n/a	tells overLib to read the caption from this index in the ol_caps array
capicon	url	No	n/a	displays the image given before the popup caption
snapx	integer	No	n/a	snaps the popup to an even position in a horizontal grid
snapy	integer	No	n/a	snaps the popup to an even position in a vertical grid
fixx	integer	No	n/a	locks the popups horizontal position Note: overrides all other horizontal placement
fixy	integer	No	n/a	locks the popups vertical position Note: overrides all other vertical placement
background	url	No	n/a	sets image to be used instead of table box background
padx	integer,integer	No	n/a	pads the background image with horizontal whitespace for text placement. Note: this is a two parameter command
pady	integer,integer	No	n/a	pads the background image with vertical whitespace for text placement. Note: this is a two parameter command
fullhtml	boolean	No	n/a	allows you to control the html over a background picture completely. The html code is expected in the "text" attribute
frame	string	No	n/a	controls popups in a different frame. See the overlib page for more info on this function
timeout	string	No	n/a	calls the specified javascript function and takes the return value as the text that should be displayed in the popup window
delay	integer	No	n/a	makes that popup behave like a tooltip. It will popup only after this delay in milliseconds
hauto	boolean	No	n/a	automatically determine if the popup should be to the left or right of the mouse.
vauto	boolean	No	n/a	automatically determine if the popup should be above or below the mouse.

popup is used to create javascript popup windows.

Example 3-72. popup

{* popup_init must be called once at the top of the page *}
{popup_init}

{* create a link with a popup window when you move your mouse over *}
<A href="mypage.html" {popup text="This link takes you to my page!"}>mypage</A>

{* you can use html, links, etc in your popup text *}
<A href="mypage.html" {popup sticky=true caption="mypage contents"
text="<UL><LI>links<LI>pages<LI>images</UL>" snapx=10 snapy=10}>mypage</A>

OUTPUT:

(See the Smarty official web site for working examples.)

Prev	Home	Next
Built-in Functions	Up	Config Files