Smarty For Template Designers Basic Syntax All Smarty template tags are enclosed within delimiters. By default, these delimiters are { and }, but they can be changed. For these examples, we will assume that you are using the default delimiters. In Smarty, all content outside of delimiters is displayed as static content, or unchanged. When Smarty encounters template tags, it attempts to interpret them, and displays the appropriate output in their place. Comments Template comments are surrounded by asterisks, and that is surrounded by the delimiter tags like so: {* this is a comment *} Smarty comments are not displayed in the final output of the template. They are used for making internal notes in the templates. Comments {* Smarty *} {* include the header file here *} {include file="header.tpl"} {include file=$includeFile} {include file=#includeFile#} {* display dropdown lists *} <SELECT name=company> {html_options values=$vals selected=$selected output=$output} </SELECT> Functions Each Smarty tag either prints a variable or invokes some sort of function. Functions are processed and displayed by enclosing the function and its attributes into delimiters like so: {funcname attr1="val" attr2="val"}. function syntax {config_load file="colors.conf"} {include file="header.tpl"} {if $highlight_name} Welcome, <font color="{#fontColor#}">{$name}!</font> {else} Welcome, {$name}! {/if} {include file="footer.tpl"} Both built-in functions and custom functions have the same syntax in the templates. Built-in functions are the inner workings of Smarty, such as if, section and strip. They cannot be modified. Custom functions are additional functions implemented via plugins. They can be modified to your liking, or you can add new ones. html_options and html_select_date are examples of custom functions. Attributes Most of the functions take attributes that specify or modify their behavior. Attributes to Smarty functions are much like HTML attributes. Static values don't have to be enclosed in quotes, but it is recommended for literal strings. Variables may also be used, and should not be in quotes. Some attributes require boolean values (true or false). These can be specified as either unquoted true, on, and yes, or false, off, and no. function attribute syntax {include file="header.tpl"} {include file=$includeFile} {include file=#includeFile#} {html_select_date display_days=yes} <SELECT name=company> {html_options values=$vals selected=$selected output=$output} </SELECT> Embedding Vars in Double Quotes Smarty will recognize assigned variables embedded in double quotes so long as the variables contain only numbers, letters, underscores and brackets []. With any other characters (period, object reference, etc.) the variable must be surrounded by backticks. embedded quotes syntax SYNTAX EXAMPLES: {func var="test $foo test"} <-- sees $foo {func var="test $foo_bar test"} <-- sees $foo_bar {func var="test $foo[0] test"} <-- sees $foo[0] {func var="test $foo[bar] test"} <-- sees $foo[bar] {func var="test $foo.bar test"} <-- sees $foo (not $foo.bar) {func var="test `$foo.bar` test"} <-- sees $foo.bar PRACTICAL EXAMPLES: {include file="subdir/$tpl_name.tpl"} <-- will replace $tpl_name with value {cycle values="one,two,`$smarty.config.myval`"} <-- must have backticks Variables Smarty has several different types of variables. The type of the variable depends on what symbol it is prefixed with (or enclosed within). Variables in Smarty can be either displayed directly or used as arguments for function attributes and modifiers, inside conditional expressions, etc. To print a variable, simply enclose it in the delimiters so that it is the only thing contained between them. Examples: {$Name} {$Contacts[row].Phone} <body bgcolor="{#bgcolor#}"> Variables assigned from PHP Variables that are assigned from PHP are referenced by preceding them with a dollar sign $. Variables assigned from within the template with the assign function are also displayed this way. assigned variables Hello {$firstname}, glad to see you could make it. <p> Your last login was on {$lastLoginDate}. OUTPUT: Hello Doug, glad to see you could make it. <p> Your last login was on January 11th, 2001. Associative arrays You can also reference associative array variables that are assigned from PHP by specifying the key after the '.' (period) symbol. accessing associative array variables index.php: $smarty = new Smarty; $smarty->assign('Contacts', array('fax' => '555-222-9876', 'email' => 'zaphod@slartibartfast.com', 'phone' => array('home' => '555-444-3333', 'cell' => '555-111-1234'))); $smarty->display('index.tpl'); index.tpl: {$Contacts.fax}<br> {$Contacts.email}<br> {* you can print arrays of arrays as well *} {$Contacts.phone.home}<br> {$Contacts.phone.cell}<br> OUTPUT: 555-222-9876<br> zaphod@slartibartfast.com<br> 555-444-3333<br> 555-111-1234<br> Array indexes You can reference arrays by their index, much like native PHP syntax. accessing arrays by index index.php: $smarty = new Smarty; $smarty->assign('Contacts', array('555-222-9876', 'zaphod@slartibartfast.com', array('555-444-3333', '555-111-1234'))); $smarty->display('index.tpl'); index.tpl: {$Contacts[0]}<br> {$Contacts[1]}<br> {* you can print arrays of arrays as well *} {$Contacts[2][0]}<br> {$Contacts[2][1]}<br> OUTPUT: 555-222-9876<br> zaphod@slartibartfast.com<br> 555-444-3333<br> 555-111-1234<br> Objects Properties of objects assigned from PHP can be referenced by specifying the property name after the '->' symbol. accessing object properties name: {$person->name}<br> email: {$person->email}<br> OUTPUT: name: Zaphod Beeblebrox<br> email: zaphod@slartibartfast.com<br> Variables loaded from config files Variables that are loaded from the config files are referenced by enclosing them within hash marks (#), or with the smarty variable $smarty.config. The second syntax is useful for embedding into quoted attribute values. config variables foo.conf: pageTitle = "This is mine" bodyBgColor = "#eeeeee" tableBorderSize = "3" tableBgColor = "#bbbbbb" rowBgColor = "#cccccc" index.tpl: {config_load file="foo.conf"} <html> <title>{#pageTitle#}</title> <body bgcolor="{#bodyBgColor#}"> <table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}"> <tr bgcolor="{#rowBgColor#}"> <td>First</td> <td>Last</td> <td>Address</td> </tr> </table> </body> </html> index.tpl: (alternate syntax) {config_load file="foo.conf"} <html> <title>{$smarty.config.pageTitle}</title> <body bgcolor="{$smarty.config.bodyBgColor}"> <table border="{$smarty.config.tableBorderSize}" bgcolor="{$smarty.config.tableBgColor}"> <tr bgcolor="{$smarty.config.rowBgColor}"> <td>First</td> <td>Last</td> <td>Address</td> </tr> </table> </body> </html> OUTPUT: (same for both examples) <html> <title>This is mine</title> <body bgcolor="#eeeeee"> <table border="3" bgcolor="#bbbbbb"> <tr bgcolor="#cccccc"> <td>First</td> <td>Last</td> <td>Address</td> </tr> </table> </body> </html> Config file variables cannot be used until after they are loaded in from a config file. This procedure is explained later in this document under config_load. {$smarty} reserved variable The reserved {$smarty} variable can be used to access several special template variables. The full list of them follows. Request variables The request variables such as get, post, cookies, server, environment, and session variables can be accessed as demonstrated in the examples below: displaying request variables {* display value of page from URL (GET) http://www.domain.com/index.php?page=foo *} {$smarty.get.page} {* display the variable "page" from a form (POST) *} {$smarty.post.page} {* display the value of the cookie "username" *} {$smarty.cookies.username} {* display the server variable "SERVER_NAME" *} {$smarty.server.SERVER_NAME} {* display the system environment variable "PATH" *} {$smarty.env.PATH} {* display the php session variable "id" *} {$smarty.session.id} {* display the variable "username" from merged get/post/cookies/server/env *} {$smarty.request.username} {$smarty.now} The current timestamp can be accessed with {$smarty.now}. The number reflects the number of seconds passed since the so-called Epoch (January 1, 1970) and can be passed directly to date_format modifier for display purposes. using {$smarty.now} {* use the date_format modifier to show current date and time *} {$smarty.now|date_format:"%Y-%m-%d %H:%M:%S"} {$smarty.const} You can access PHP constant values directly. using {$smarty.const} {$smarty.const._MY_CONST_VAL} {$smarty.capture} The output captured via {capture}..{/capture} construct can be accessed using {$smarty} variable. See section on capture for an example. {$smarty.config} {$smarty} variable can be used to refer to loaded config variables. {$smarty.config.foo} is a synonyn for {#foo#}. See the section on config_load for an example. {$smarty.section}, {$smarty.foreach} {$smarty} variable can be used to refer to 'section' and 'foreach' loop properties. See docs for section and foreach. {$smarty.template} This variable contains the name of the current template being processed. Variable Modifiers Variable modifiers can be applied to variables, custom functions or strings. To apply a modifier, specify the value followed by the | (pipe) and the modifier name. A modifier may accept additional parameters that affect its behavior. These parameters follow the modifer name and are separated by : (colon). modifier example {* Uppercase the title *} <h2>{$title|upper}</h2> {* Truncate the topic to 40 characters use ... at the end *} Topic: {$topic|truncate:40:"..."} {* format a literal string *} {"now"|date_format:"%Y/%m/%d"} {* apply modifier to a custom function *} {mailto|upper address="me@domain.dom"} If you apply a modifier to an array variable instead of a single value variable, the modifier will be applied to every value in that array. If you really want the modifier to work on an entire array as a value, you must prepend the modifier name with an @ symbol like so: {$articleTitle|@count} (this will print out the number of elements in the $articleTitle array.) capitalize This is used to capitalize the first letter of all words in a variable. capitalize index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Police begin campaign to rundown jaywalkers.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|capitalize} OUTPUT: Police begin campaign to rundown jaywalkers. Police Begin Campaign To Rundown Jaywalkers. count_characters This is used to count the number of characters in a variable. count_characters index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Cold Wave Linked to Temperatures.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|count_characters} OUTPUT: Cold Wave Linked to Temperatures. 32 cat Parameter Position Type Required cat Description 1 string No empty This value to catentate to the given variable. This value is concatenated to the given variable. cat index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "Psychics predict world didn't end"); $smarty->display('index.tpl'); index.tpl: {$articleTitle|cat:" yesterday."} OUTPUT: Psychics predict world didn't end yesterday. count_paragraphs This is used to count the number of paragraphs in a variable. count_paragraphs index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "War Dims Hope for Peace. Child's Death Ruins Couple's Holiday.\n\nMan is Fatally Slain. Death Causes Loneliness, Feeling of Isolation."); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|count_paragraphs} OUTPUT: War Dims Hope for Peace. Child's Death Ruins Couple's Holiday. Man is Fatally Slain. Death Causes Loneliness, Feeling of Isolation. 2 count_sentences This is used to count the number of sentences in a variable. count_sentences index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Two Soviet Ships Collide - One Dies. Enraged Cow Injures Farmer with Axe.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|count_sentences} OUTPUT: Two Soviet Ships Collide - One Dies. Enraged Cow Injures Farmer with Axe. 2 count_words This is used to count the number of words in a variable. count_words index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Dealers Will Hear Car Talk at Noon.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|count_words} OUTPUT: Dealers Will Hear Car Talk at Noon. 7 date_format Parameter Position Type Required Default Description 1 string No %b %e, %Y This is the format for the outputted date. 2 string No n/a This is the default date if the input is empty. This formats a date and time into the given strftime() format. Dates can be passed to Smarty as unix timestamps, mysql timestamps or any string made up of month day year (parsable by strtotime). Designers can then use date_format to have complete control of the formatting of the date. If the date passed to date_format is empty and a second parameter is passed, that will be used as the date to format. date_format index.php: $smarty = new Smarty; $smarty->assign('yesterday', strtotime('-1 day')); $smarty->display('index.tpl'); index.tpl: {$smarty.now|date_format} {$smarty.now|date_format:"%A, %B %e, %Y"} {$smarty.now|date_format:"%H:%M:%S"} {$yesterday|date_format} {$yesterday|date_format:"%A, %B %e, %Y"} {$yesterday|date_format:"%H:%M:%S"} OUTPUT: Feb 6, 2001 Tuesday, February 6, 2001 14:33:00 Feb 5, 2001 Monday, February 5, 2001 14:33:00 date_format conversion specifiers %a - abbreviated weekday name according to the current locale %A - full weekday name according to the current locale %b - abbreviated month name according to the current locale %B - full month name according to the current locale %c - preferred date and time representation for the current locale %C - century number (the year divided by 100 and truncated to an integer, range 00 to 99) %d - day of the month as a decimal number (range 00 to 31) %D - same as %m/%d/%y %e - day of the month as a decimal number, a single digit is preceded by a space (range 1 to 31) %g - Week-based year within century [00,99] %G - Week-based year, including the century [0000,9999] %h - same as %b %H - hour as a decimal number using a 24-hour clock (range 00 to 23) %I - hour as a decimal number using a 12-hour clock (range 01 to 12) %j - day of the year as a decimal number (range 001 to 366) %k - Hour (24-hour clock) single digits are preceded by a blank. (range 0 to 23) %l - hour as a decimal number using a 12-hour clock, single digits preceeded by a space (range 1 to 12) %m - month as a decimal number (range 01 to 12) %M - minute as a decimal number %n - newline character %p - either `am' or `pm' according to the given time value, or the corresponding strings for the current locale %r - time in a.m. and p.m. notation %R - time in 24 hour notation %S - second as a decimal number %t - tab character %T - current time, equal to %H:%M:%S %u - weekday as a decimal number [1,7], with 1 representing Monday %U - week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week %V - The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. %w - day of the week as a decimal, Sunday being 0 %W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week %x - preferred date representation for the current locale without the time %X - preferred time representation for the current locale without the date %y - year as a decimal number without a century (range 00 to 99) %Y - year as a decimal number including the century %Z - time zone or name or abbreviation %% - a literal `%' character PROGRAMMERS NOTE: date_format is essentially a wrapper to PHP's strftime() function. You may have more or less conversion specifiers available depending on your system's strftime() function where PHP was compiled. Check your system's manpage for a full list of valid specifiers. default Parameter Position Type Required Default Description 1 string No empty This is the default value to output if the variable is empty. This is used to set a default value for a variable. If the variable is empty or unset, the given default value is printed instead. Default takes one argument. default index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Dealers Will Hear Car Talk at Noon.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle|default:"no title"} {$myTitle|default:"no title"} OUTPUT: Dealers Will Hear Car Talk at Noon. no title escape Parameter Position Type Required Possible Values Default Description 1 string No html,htmlall,url,quotes,hex,hexentity,javascript html This is the escape format to use. This is used to html escape, url escape, escape single quotes on a variable not already escaped, hex escape, hexentity or javascript escape. By default, the variable is html escaped. escape index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "'Stiff Opposition Expected to Casketless Funeral Plan'"); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|escape} {$articleTitle|escape:"html"} {* escapes & " ' < > *} {$articleTitle|escape:"htmlall"} {* escapes ALL html entities *} {$articleTitle|escape:"url"} {$articleTitle|escape:"quotes"} <a href="mailto:{$EmailAddress|escape:"hex"}">{$EmailAddress|escape:"hexentity"}</a> OUTPUT: 'Stiff Opposition Expected to Casketless Funeral Plan' 'Stiff%20Opposition%20Expected%20to%20Casketless%20Funeral%20Plan' 'Stiff%20Opposition%20Expected%20to%20Casketless%20Funeral%20Plan' 'Stiff%20Opposition%20Expected%20to%20Casketless%20Funeral%20Plan' 'Stiff+Opposition+Expected+to+Casketless+Funeral+Plan' \'Stiff Opposition Expected to Casketless Funeral Plan\' <a href="mailto:%62%6f%62%40%6d%65%2e%6e%65%74">&#x62;&#x6f;&#x62;&#x40;&#x6d;&#x65;&#x2e;&#x6e;&#x65;&#x74;</a> indent Parameter Position Type Required Default Description 1 integer No 4 This determines how many characters to indent to. 2 string No (one space) This is the character used to indent with. This indents a string at each line, default is 4. As an optional parameter, you can specify the number of characters to indent. As an optional second parameter, you can specify the character to use to indent with. (Use "\t" for tabs.) indent index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'NJ judge to rule on nude beach.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|indent} {$articleTitle|indent:10} {$articleTitle|indent:1:"\t"} OUTPUT: NJ judge to rule on nude beach. Sun or rain expected today, dark tonight. Statistics show that teen pregnancy drops off significantly after 25. NJ judge to rule on nude beach. Sun or rain expected today, dark tonight. Statistics show that teen pregnancy drops off significantly after 25. NJ judge to rule on nude beach. Sun or rain expected today, dark tonight. Statistics show that teen pregnancy drops off significantly after 25. NJ judge to rule on nude beach. Sun or rain expected today, dark tonight. Statistics show that teen pregnancy drops off significantly after 25. lower This is used to lowercase a variable. lower index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Two Convicts Evade Noose, Jury Hung.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|lower} OUTPUT: Two Convicts Evade Noose, Jury Hung. two convicts evade noose, jury hung. nl2br All linebreaks will be converted to <br /> tags in the given variable. This is equivalent to the PHP nl2br() function. nl2br index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "Sun or rain expected\ntoday, dark tonight"); $smarty->display('index.tpl'); index.tpl: {$articleTitle|nl2br} OUTPUT: Sun or rain expected<br />today, dark tonight regex_replace Parameter Position Type Required Default Description 1 string Yes n/a This is the regular expression to be replaced. 2 string Yes n/a This is the string of text to replace with. A regular expression search and replace on a variable. Use the syntax for preg_replace() from the PHP manual. regex_replace index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "Infertility unlikely to\nbe passed on, experts say."); $smarty->display('index.tpl'); index.tpl: {* replace each carriage return, tab & new line with a space *} {$articleTitle} {$articleTitle|regex_replace:"/[\r\t\n]/":" "} OUTPUT: Infertility unlikely to be passed on, experts say. Infertility unlikely to be passed on, experts say. replace Parameter Position Type Required Default Description 1 string Yes n/a This is the string of text to be replaced. 2 string Yes n/a This is the string of text to replace with. A simple search and replace on a variable. replace index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "Child's Stool Great for Use in Garden."); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|replace:"Garden":"Vineyard"} {$articleTitle|replace:" ":" "} OUTPUT: Child's Stool Great for Use in Garden. Child's Stool Great for Use in Vineyard. Child's Stool Great for Use in Garden. spacify Parameter Position Type Required Default Description 1 string No one space This what gets inserted between each character of the variable. spacify is a way to insert a space between every character of a variable. You can optionally pass a different character (or string) to insert. spacify index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Something Went Wrong in Jet Crash, Experts Say.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|spacify} {$articleTitle|spacify:"^^"} OUTPUT: Something Went Wrong in Jet Crash, Experts Say. S o m e t h i n g W e n t W r o n g i n J e t C r a s h , E x p e r t s S a y . S^^o^^m^^e^^t^^h^^i^^n^^g^^ ^^W^^e^^n^^t^^ ^^W^^r^^o^^n^^g^^ ^^i^^n^^ ^^J^^e^^t^^ ^^C^^r^^a^^s^^h^^,^^ ^^E^^x^^p^^e^^r^^t^^s^^ ^^S^^a^^y^^. string_format Parameter Position Type Required Default Description 1 string Yes n/a This is what format to use. (sprintf) This is a way to format strings, such as decimal numbers and such. Use the syntax for sprintf for the formatting. string_format index.php: $smarty = new Smarty; $smarty->assign('number', 23.5787446); $smarty->display('index.tpl'); index.tpl: {$number} {$number|string_format:"%.2f"} {$number|string_format:"%d"} OUTPUT: 23.5787446 23.58 24 strip This replaces all repeated spaces, newlines and tabs with a single space, or with a supplied string. Note If you want to strip blocks of template text, use the strip function. strip index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "Grandmother of\neight makes\t hole in one."); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|strip} {$articleTitle|strip:"&nbsp;"} OUTPUT: Grandmother of eight makes hole in one. Grandmother of eight makes hole in one. Grandmother&nbsp;of&nbsp;eight&nbsp;makes&nbsp;hole&nbsp;in&nbsp;one. strip_tags This strips out markup tags, basically anything between < and >. strip_tags index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "Blind Woman Gets <font face=\"helvetica\">New Kidney</font> from Dad she Hasn't Seen in <b>years</b>."); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|strip_tags} OUTPUT: Blind Woman Gets <font face="helvetica">New Kidney</font> from Dad she Hasn't Seen in <b>years</b>. Blind Woman Gets New Kidney from Dad she Hasn't Seen in years. truncate Parameter Position Type Required Default Description 1 integer No 80 This determines how many characters to truncate to. 2 string No ... This is the text to append if truncation occurs. 3 boolean No false This determines whether or not to truncate at a word boundary (false), or at the exact character (true). This truncates a variable to a character length, default is 80. As an optional second parameter, you can specify a string of text to display at the end if the variable was truncated. The characters in the string are included with the original truncation length. By default, truncate will attempt to cut off at a word boundary. If you want to cut off at the exact character length, pass the optional third parameter of true. truncate index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Two Sisters Reunite after Eighteen Years at Checkout Counter.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|truncate} {$articleTitle|truncate:30} {$articleTitle|truncate:30:""} {$articleTitle|truncate:30:"---"} {$articleTitle|truncate:30:"":true} {$articleTitle|truncate:30:"...":true} OUTPUT: Two Sisters Reunite after Eighteen Years at Checkout Counter. Two Sisters Reunite after Eighteen Years at Checkout Counter. Two Sisters Reunite after... Two Sisters Reunite after Two Sisters Reunite after--- Two Sisters Reunite after Eigh Two Sisters Reunite after E... upper This is used to uppercase a variable. upper index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "If Strike isn't Settled Quickly it may Last a While."); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|upper} OUTPUT: If Strike isn't Settled Quickly it may Last a While. IF STRIKE ISN'T SETTLED QUICKLY IT MAY LAST A WHILE. wordwrap Parameter Position Type Required Default Description 1 integer No 80 This determines how many columns to wrap to. 2 string No \n This is the string used to wrap words with. 3 boolean No false This determines whether or not to wrap at a word boundary (false), or at the exact character (true). This wraps a string to a column width, default is 80. As an optional second parameter, you can specify a string of text to wrap the text to the next line (default is carriage return \n). By default, wordwrap will attempt to wrap at a word boundary. If you want to cut off at the exact character length, pass the optional third parameter of true. wordwrap index.php: $smarty = new Smarty; $smarty->assign('articleTitle', "Blind woman gets new kidney from dad she hasn't seen in years."); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|wordwrap:30} {$articleTitle|wordwrap:20} {$articleTitle|wordwrap:30:"<br>\n"} {$articleTitle|wordwrap:30:"\n":true} OUTPUT: Blind woman gets new kidney from dad she hasn't seen in years. Blind woman gets new kidney from dad she hasn't seen in years. Blind woman gets new kidney from dad she hasn't seen in years. Blind woman gets new kidney<br> from dad she hasn't seen in years. Blind woman gets new kidney fr om dad she hasn't seen in year s. Combining Modifiers You can apply any number of modifiers to a variable. They will be applied in the order they are combined, from left to right. They must be separated with a | (pipe) character. combining modifiers index.php: $smarty = new Smarty; $smarty->assign('articleTitle', 'Smokers are Productive, but Death Cuts Efficiency.'); $smarty->display('index.tpl'); index.tpl: {$articleTitle} {$articleTitle|upper|spacify} {$articleTitle|lower|spacify|truncate} {$articleTitle|lower|truncate:30|spacify} {$articleTitle|lower|spacify|truncate:30:". . ."} OUTPUT: Smokers are Productive, but Death Cuts Efficiency. S M O K E R S A R E P R O D U C T I V E , B U T D E A T H C U T S E F F I C I E N C Y . s m o k e r s a r e p r o d u c t i v e , b u t d e a t h c u t s... s m o k e r s a r e p r o d u c t i v e , b u t . . . s m o k e r s a r e p. . . Built-in Functions Smarty comes with several built-in functions. Built-in functions are integral to the template language. You cannot create custom functions with the same names, nor can you modify built-in functions. capture capture is used to collect the output of the template into a variable instead of displaying it. Any content between {capture name="foo"} and {/capture} is collected into the variable specified in the name attribute. The captured content can be used in the template from the special variable $smarty.capture.foo where foo is the value passed in the name attribute. If you do not supply a name attribute, then "default" will be used. All {capture} commands must be paired with {/capture}. You can nest capture commands. Technical Note Smarty 1.4.0 - 1.4.4 placed the captured content into the variable named $return. As of 1.4.5, this behavior was changed to use the name attribute, so update your templates accordingly. Be careful when capturing insert output. If you have caching turned on and you have insert commands that you expect to run within cached content, do not capture this content. capturing template content {* we don't want to print a table row unless content is displayed *} {capture name=banner} {include file="get_banner.tpl"} {/capture} {if $smarty.capture.banner ne ""} <tr> <td> {$smarty.capture.banner} </td> </tr> {/if} config_load Attribute Name Type Required Default Description file string Yes n/a The name of the config file to include section string No n/a The name of the section to load scope string no local How the scope of the loaded variables are treated, which must be one of local, parent or global. local means variables are loaded into the local template context. parent means variables are loaded into both the local context and the parent template that called it. global means variables are available to all templates. global boolean No No Whether or not variables are visible to the parent template, same as scope=parent. NOTE: This attribute is deprecated by the scope attribute, but still supported. If scope is supplied, this value is ignored. This function is used for loading in variables from a configuration file into the template. See Config Files for more info. function config_load {config_load file="colors.conf"} <html> <title>{#pageTitle#}</title> <body bgcolor="{#bodyBgColor#}"> <table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}"> <tr bgcolor="{#rowBgColor#}"> <td>First</td> <td>Last</td> <td>Address</td> </tr> </table> </body> </html> Config files may also contain sections. You can load variables from within a section with the added attribute section. NOTE: Config file sections and the built-in template function called section have nothing to do with each other, they just happen to share a common naming convention. function config_load with section {config_load file="colors.conf" section="Customer"} <html> <title>{#pageTitle#}</title> <body bgcolor="{#bodyBgColor#}"> <table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}"> <tr bgcolor="{#rowBgColor#}"> <td>First</td> <td>Last</td> <td>Address</td> </tr> </table> </body> </html> foreach,foreachelse Attribute Name Type Required Default Description from string Yes n/a The name of the array you are looping through item string Yes n/a The name of the variable that is the current element key string No n/a The name of the variable that is the current key name string No n/a The name of the foreach loop for accessing foreach properties foreach loops are an alternative to section loops. foreach is used to loop over a single associative array. The syntax for foreach is much easier than section, but as a tradeoff it can only be used for a single array. foreach tags must be paired with /foreach tags. Required parameters are from and item. The name of the foreach loop can be anything you like, made up of letters, numbers and underscores. foreach loops can be nested, and the nested foreach names must be unique from each other. The from variable (usually an array of values) determines the number of times foreach will loop. foreachelse is executed when there are no values in the from variable. foreach {* this example will print out all the values of the $custid array *} {foreach from=$custid item=curr_id} id: {$curr_id}<br> {/foreach} OUTPUT: id: 1000<br> id: 1001<br> id: 1002<br> foreach key {* The key contains the key for each looped value assignment looks like this: $smarty->assign("contacts", array(array("phone" => "1", "fax" => "2", "cell" => "3"), array("phone" => "555-4444", "fax" => "555-3333", "cell" => "760-1234"))); *} {foreach name=outer item=contact from=$contacts} {foreach key=key item=item from=$contact} {$key}: {$item}<br> {/foreach} {/foreach} OUTPUT: phone: 1<br> fax: 2<br> cell: 3<br> phone: 555-4444<br> fax: 555-3333<br> cell: 760-1234<br> Foreach-loops also have their own variables that handle foreach properties. These are indicated like so: {$smarty.foreach.foreachname.varname} with foreachname being the name specified as the name attribute of foreach iteration iteration is used to display the current loop iteration. Iteration always starts with 1 and is incremented by one one each iteration. first first is set to true if the current foreach iteration is the first one. last last is set to true if the current foreach iteration is the last one. show show is used as a parameter to foreach. show is a boolean value, true or false. If false, the foreach will not be displayed. If there is a foreachelse present, that will be alternately displayed. total total is used to display the number of iterations that this foreach will loop. This can be used inside or after the foreach. include Attribute Name Type Required Default Description file string Yes n/a The name of the template file to include assign string No n/a The name of the variable that the output of include will be assigned to [var ...] [var type] No n/a variable to pass local to template Include tags are used for including other templates in the current template. Any variables available in the current template are also available within the included template. The include tag must have the attribute "file", which contains the template resource path. You can optionally pass the assign attribute, which will specify a template variable name that the output of include will be assigned to instead of displayed. function include {include file="header.tpl"} {* body of template goes here *} {include file="footer.tpl"} You can also pass variables to included templates as attributes. Any variables explicitly passed to an included template as attributes are only available within the scope of the included file. Attribute variables override current template variables, in the case they are named alike. function include passing variables {include file="header.tpl" title="Main Menu" table_bgcolor="#c0c0c0"} {* body of template goes here *} {include file="footer.tpl" logo="http://my.domain.com/logo.gif"} Use the syntax for template resources to include files outside of the $template_dir directory. function include template resource examples {* absolute filepath *} {include file="/usr/local/include/templates/header.tpl"} {* absolute filepath (same thing) *} {include file="file:/usr/local/include/templates/header.tpl"} {* windows absolute filepath (MUST use "file:" prefix) *} {include file="file:C:/www/pub/templates/header.tpl"} {* include from template resource named "db" *} {include file="db:header.tpl"} include_php Attribute Name Type Required Default Description file string Yes n/a The name of the php file to include once boolean No true whether or not to include the php file more than once if included multiple times assign string No n/a The name of the variable that the output of include_php will be assigned to include_php tags are used to include a php script in your template. If security is enabled, then the php script must be located in the $trusted_dir path. The include_php tag must have the attribute "file", which contains the path to the included php file, either relative to $trusted_dir, or an absolute path. include_php is a nice way to handle componentized templates, and keep PHP code separate from the template files. Lets say you have a template that shows your site navigation, which is pulled dynamically from a database. You can keep your PHP logic that grabs database content in a separate directory, and include it at the top of the template. Now you can include this template anywhere without worrying if the database information was assigned by the application before hand. By default, php files are only included once even if called multiple times in the template. You can specify that it should be included every time with the once attribute. Setting once to false will include the php script each time it is included in the template. You can optionally pass the assign attribute, which will specify a template variable name that the output of include_php will be assigned to instead of displayed. The smarty object is available as $this within the PHP script that you include. function include_php load_nav.php ------------- <?php // load in variables from a mysql db and assign them to the template require_once("MySQL.class.php"); $sql = new MySQL; $sql->query("select * from site_nav_sections order by name",SQL_ALL); $this->assign('sections',$sql->record); ?> index.tpl --------- {* absolute path, or relative to $trusted_dir *} {include_php file="/path/to/load_nav.php"} {foreach item="curr_section" from=$sections} <a href="{$curr_section.url}">{$curr_section.name}</a><br> {/foreach} insert Attribute Name Type Required Default Description name string Yes n/a The name of the insert function (insert_name) assign string No n/a The name of the template variable the output will be assigned to script string No n/a The name of the php script that is included before the insert function is called [var ...] [var type] No n/a variable to pass to insert function Insert tags work much like include tags, except that insert tags are not cached when you have template caching enabled. They will be executed on every invocation of the template. Let's say you have a template with a banner slot at the top of the page. The banner can contain any mixture of HTML, images, flash, etc. so we can't just use a static link here, and we don't want this contents cached with the page. In comes the insert tag: the template knows #banner_location_id# and #site_id# values (gathered from a config file), and needs to call a function to get the banner contents. function insert {* example of fetching a banner *} {insert name="getBanner" lid=#banner_location_id# sid=#site_id#} In this example, we are using the name "getBanner" and passing the parameters #banner_location_id# and #site_id#. Smarty will look for a function named insert_getBanner() in your PHP application, passing the values of #banner_location_id# and #site_id# as the first argument in an associative array. All insert function names in your application must be prepended with "insert_" to remedy possible function name-space conflicts. Your insert_getBanner() function should do something with the passed values and return the results. These results are then displayed in the template in place of the insert tag. In this example, Smarty would call this function: insert_getBanner(array("lid" => "12345","sid" => "67890")); and display the returned results in place of the insert tag. If you supply the "assign" attribute, the output of the insert tag will be assigned to this template variable instead of being output to the template. NOTE: assigning the output to a template variable isn't too useful with caching enabled. If you supply the "script" attribute, this php script will be included (only once) before the insert function is executed. This is the case where the insert function may not exist yet, and a php script must be included first to make it work. The path can be either absolute, or relative to $trusted_dir. When security is enabled, the script must reside in $trusted_dir. The Smarty object is passed as the second argument. This way you can reference and modify information in the Smarty object from within the insert function. Technical Note It is possible to have portions of the template not cached. If you have caching turned on, insert tags will not be cached. They will run dynamically every time the page is created, even within cached pages. This works good for things like banners, polls, live weather, search results, user feedback areas, etc. if,elseif,else if statements in Smarty have much the same flexibility as php if statements, with a few added features for the template engine. Every if must be paired with an /if. else and elseif are also permitted. "eq", "ne","neq", "gt", "lt", "lte", "le", "gte" "ge","is even","is odd", "is not even","is not odd","not","mod","div by","even by","odd by","==","!=",">", "<","<=",">=" are all valid conditional qualifiers, and must be separated from surrounding elements by spaces. if statements {if $name eq "Fred"} Welcome Sir. {elseif $name eq "Wilma"} Welcome Ma'am. {else} Welcome, whatever you are. {/if} {* an example with "or" logic *} {if $name eq "Fred" or $name eq "Wilma"} ... {/if} {* same as above *} {if $name == "Fred" || $name == "Wilma"} ... {/if} {* the following syntax will NOT work, conditional qualifiers must be separated from surrounding elements by spaces *} {if $name=="Fred" || $name=="Wilma"} ... {/if} {* parenthesis are allowed *} {if ( $amount < 0 or $amount > 1000 ) and $volume >= #minVolAmt#} ... {/if} {* you can also embed php function calls *} {if count($var) gt 0} ... {/if} {* test if values are even or odd *} {if $var is even} ... {/if} {if $var is odd} ... {/if} {if $var is not odd} ... {/if} {* test if var is divisible by 4 *} {if $var is div by 4} ... {/if} {* test if var is even, grouped by two. i.e., 0=even, 1=even, 2=odd, 3=odd, 4=even, 5=even, etc. *} {if $var is even by 2} ... {/if} {* 0=even, 1=even, 2=even, 3=odd, 4=odd, 5=odd, etc. *} {if $var is even by 3} ... {/if} ldelim,rdelim ldelim and rdelim are used for displaying the literal delimiter, in our case "{" or "}". The template engine always tries to interpret delimiters, so this is the way around that. ldelim, rdelim {* this will print literal delimiters out of the template *} {ldelim}funcname{rdelim} is how functions look in Smarty! OUTPUT: {funcname} is how functions look in Smarty! literal Literal tags allow a block of data to be taken literally, not being interpreted by the Smarty engine. This is handy for things like javascript sections, where there maybe curly braces and such things that would confuse the template parser. Anything within {literal}{/literal} tags is not interpreted, but displayed as-is. literal tags {literal} <script language=javascript> <!-- function isblank(field) { if (field.value == '') { return false; } else { document.loginform.submit(); return true; } } // --> </script> {/literal} php php tags allow php to be embedded directly into the template. They will not be escaped, regardless of the $php_handling setting. This is for advanced users only, not normally needed. php tags {php} // including a php script directly // from the template. include("/path/to/display_weather.php"); {/php} section,sectionelse Attribute Name Type Required Default Description name string Yes n/a The name of the section loop [$variable_name] Yes n/a The name of the variable to determine # of loop iterations start integer No 0 The index position that the section will begin looping. If the value is negative, the start position is calculated from the end of the array. For example, if there are seven values in the loop array and start is -2, the start index is 5. Invalid values (values outside of the length of the loop array) are automatically truncated to the closest valid value. step integer No 1 The step value that will be used to traverse the loop array. For example, step=2 will loop on index 0,2,4, etc. If step is negative, it will step through the array backwards. max integer No 1 Sets the maximum number of times the section will loop. show boolean No true determines whether or not to show this section Template sections are used for looping over arrays of data. All section tags must be paired with /section tags. Required parameters are name and loop. The name of the section can be anything you like, made up of letters, numbers and underscores. Sections can be nested, and the nested section names must be unique from each other. The loop variable (usually an array of values) determines the number of times the section will loop. When printing a variable within a section, the section name must be given next to variable name within brackets []. sectionelse is executed when there are no values in the loop variable. section {* this example will print out all the values of the $custid array *} {section name=customer loop=$custid} id: {$custid[customer]}<br> {/section} OUTPUT: id: 1000<br> id: 1001<br> id: 1002<br> section loop variable {* the loop variable only determines the number of times to loop. you can access any variable from the template within the section. This example assumes that $custid, $name and $address are all arrays containing the same number of values *} {section name=customer loop=$custid} id: {$custid[customer]}<br> name: {$name[customer]}<br> address: {$address[customer]}<br> <p> {/section} OUTPUT: id: 1000<br> name: John Smith<br> address: 253 N 45th<br> <p> id: 1001<br> name: Jack Jones<br> address: 417 Mulberry ln<br> <p> id: 1002<br> name: Jane Munson<br> address: 5605 apple st<br> <p> section names {* the name of the section can be anything you like, and it is used to reference the data within the section *} {section name=mydata loop=$custid} id: {$custid[mydata]}<br> name: {$name[mydata]}<br> address: {$address[mydata]}<br> <p> {/section} nested sections {* sections can be nested as deep as you like. With nested sections, you can access complex data structures, such as multi-dimensional arrays. In this example, $contact_type[customer] is an array of contact types for the current customer. *} {section name=customer loop=$custid} id: {$custid[customer]}<br> name: {$name[customer]}<br> address: {$address[customer]}<br> {section name=contact loop=$contact_type[customer]} {$contact_type[customer][contact]}: {$contact_info[customer][contact]}<br> {/section} <p> {/section} OUTPUT: id: 1000<br> name: John Smith<br> address: 253 N 45th<br> home phone: 555-555-5555<br> cell phone: 555-555-5555<br> e-mail: john@mydomain.com<br> <p> id: 1001<br> name: Jack Jones<br> address: 417 Mulberry ln<br> home phone: 555-555-5555<br> cell phone: 555-555-5555<br> e-mail: jack@mydomain.com<br> <p> id: 1002<br> name: Jane Munson<br> address: 5605 apple st<br> home phone: 555-555-5555<br> cell phone: 555-555-5555<br> e-mail: jane@mydomain.com<br> <p> sections and associative arrays {* This is an example of printing an associative array of data within a section *} {section name=customer loop=$contacts} name: {$contacts[customer].name}<br> home: {$contacts[customer].home}<br> cell: {$contacts[customer].cell}<br> e-mail: {$contacts[customer].email}<p> {/section} OUTPUT: name: John Smith<br> home: 555-555-5555<br> cell: 555-555-5555<br> e-mail: john@mydomain.com<p> name: Jack Jones<br> home phone: 555-555-5555<br> cell phone: 555-555-5555<br> e-mail: jack@mydomain.com<p> name: Jane Munson<br> home phone: 555-555-5555<br> cell phone: 555-555-5555<br> e-mail: jane@mydomain.com<p> sectionelse {* sectionelse will execute if there are no $custid values *} {section name=customer loop=$custid} id: {$custid[customer]}<br> {sectionelse} there are no values in $custid. {/section} Sections also have their own variables that handle section properties. These are indicated like so: {$smarty.section.sectionname.varname} NOTE: As of Smarty 1.5.0, the syntax for section property variables has been changed from {%sectionname.varname%} to {$smarty.section.sectionname.varname}. The old syntax is still supported, but you will only see reference to the new syntax in the manual examples. index index is used to display the current loop index, starting with zero (or the start attribute if given), and incrementing by one (or by the step attribute if given.) Technical Note If the step and start section properties are not modified, then this works the same as the iteration section property, except it starts on 0 instead of 1. section property index {section name=customer loop=$custid} {$smarty.section.customer.index} id: {$custid[customer]}<br> {/section} OUTPUT: 0 id: 1000<br> 1 id: 1001<br> 2 id: 1002<br> index_prev index_prev is used to display the previous loop index. on the first loop, this is set to -1. section property index_prev {section name=customer loop=$custid} {$smarty.section.customer.index} id: {$custid[customer]}<br> {* FYI, $custid[customer.index] and $custid[customer] are identical in meaning *} {if $custid[customer.index_prev] ne $custid[customer.index]} The customer id changed<br> {/if} {/section} OUTPUT: 0 id: 1000<br> The customer id changed<br> 1 id: 1001<br> The customer id changed<br> 2 id: 1002<br> The customer id changed<br> index_next index_next is used to display the next loop index. On the last loop, this is still one more than the current index (respecting the setting of the step attribute, if given.) section property index_next {section name=customer loop=$custid} {$smarty.section.customer.index} id: {$custid[customer]}<br> {* FYI, $custid[customer.index] and $custid[customer] are identical in meaning *} {if $custid[customer.index_next] ne $custid[customer.index]} The customer id will change<br> {/if} {/section} OUTPUT: 0 id: 1000<br> The customer id will change<br> 1 id: 1001<br> The customer id will change<br> 2 id: 1002<br> The customer id will change<br> iteration iteration is used to display the current loop iteration. NOTE: This is not affected by the section properties start, step and max, unlike the index property. Iteration also starts with 1 instead of 0 like index. rownum is an alias to iteration, they work identical. section property iteration {section name=customer loop=$custid start=5 step=2} current loop iteration: {$smarty.section.customer.iteration}<br> {$smarty.section.customer.index} id: {$custid[customer]}<br> {* FYI, $custid[customer.index] and $custid[customer] are identical in meaning *} {if $custid[customer.index_next] ne $custid[customer.index]} The customer id will change<br> {/if} {/section} OUTPUT: current loop iteration: 1 5 id: 1000<br> The customer id will change<br> current loop iteration: 2 7 id: 1001<br> The customer id will change<br> current loop iteration: 3 9 id: 1002<br> The customer id will change<br> first first is set to true if the current section iteration is the first one. section property first {section name=customer loop=$custid} {if $smarty.section.customer.first} <table> {/if} <tr><td>{$smarty.section.customer.index} id: {$custid[customer]}</td></tr> {if $smarty.section.customer.last} </table> {/if} {/section} OUTPUT: <table> <tr><td>0 id: 1000</td></tr> <tr><td>1 id: 1001</td></tr> <tr><td>2 id: 1002</td></tr> </table> last last is set to true if the current section iteration is the last one. section property last {section name=customer loop=$custid} {if $smarty.section.customer.first} <table> {/if} <tr><td>{$smarty.section.customer.index} id: {$custid[customer]}</td></tr> {if $smarty.section.customer.last} </table> {/if} {/section} OUTPUT: <table> <tr><td>0 id: 1000</td></tr> <tr><td>1 id: 1001</td></tr> <tr><td>2 id: 1002</td></tr> </table> rownum rownum is used to display the current loop iteration, starting with one. It is an alias to iteration, they work identically. section property rownum {section name=customer loop=$custid} {$smarty.section.customer.rownum} id: {$custid[customer]}<br> {/section} OUTPUT: 1 id: 1000<br> 2 id: 1001<br> 3 id: 1002<br> loop loop is used to display the last index number that this section looped. This can be used inside or after the section. section property index {section name=customer loop=$custid} {$smarty.section.customer.index} id: {$custid[customer]}<br> {/section} There were {$smarty.section.customer.loop} customers shown above. OUTPUT: 0 id: 1000<br> 1 id: 1001<br> 2 id: 1002<br> There were 3 customers shown above. show show is used as a parameter to section. show is a boolean value, true or false. If false, the section will not be displayed. If there is a sectionelse present, that will be alternately displayed. section attribute show {* $show_customer_info may have been passed from the PHP application, to regulate whether or not this section shows *} {section name=customer loop=$custid show=$show_customer_info} {$smarty.section.customer.rownum} id: {$custid[customer]}<br> {/section} {if $smarty.section.customer.show} the section was shown. {else} the section was not shown. {/if} OUTPUT: 1 id: 1000<br> 2 id: 1001<br> 3 id: 1002<br> the section was shown. total total is used to display the number of iterations that this section will loop. This can be used inside or after the section. section property total {section name=customer loop=$custid step=2} {$smarty.section.customer.index} id: {$custid[customer]}<br> {/section} There were {$smarty.section.customer.total} customers shown above. OUTPUT: 0 id: 1000<br> 2 id: 1001<br> 4 id: 1002<br> There were 3 customers shown above. strip Many times web designers run into the issue where white space and carriage returns affect the output of the rendered HTML (browser "features"), so you must run all your tags together in the template to get the desired results. This usually ends up in unreadable or unmanageable templates. Anything within {strip}{/strip} tags in Smarty are stripped of the extra spaces or carriage returns at the beginnings and ends of the lines before they are displayed. This way you can keep your templates readable, and not worry about extra white space causing problems. Technical Note {strip}{/strip} does not affect the contents of template variables. See the strip modifier function. strip tags {* the following will be all run into one line upon output *} {strip} <table border=0> <tr> <td> <A HREF="{$url}"> <font color="red">This is a test</font> </A> </td> </tr> </table> {/strip} OUTPUT: <table border=0><tr><td><A HREF="http://my.domain.com"><font color="red">This is a test</font></A></td></tr></table> Notice that in the above example, all the lines begin and end with HTML tags. Be aware that all the lines are run together. If you have plain text at the beginning or end of any line, they will be run together, and may not be desired results. Custom Functions Smarty comes with several custom functions that you can use in the templates. 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. 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 name string No default The name 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 name for each one. If you do not supply a name, the name 'default' will be used. 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. 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> cycle Attribute Name Type Required Default Description name string No default The name of the cycle values mixed Yes N/A The values to cycle through, either a comma delimited list (see delimiter attribute), or an array of values. print boolean No true Whether to print the value or not advance boolean No true Whether or not to advance to the next value delimiter string No , The delimiter to use in the values attribute. assign string No n/a the template variable the output will be assigned to Cycle is used to cycle though a set of values. This makes it easy to alternate between two or more colors in a table, or cycle through an array of values. You can cycle through more than one set of values in your template by supplying a name attribute. Give each set of values a unique name. You can force the current value not to print with the print attribute set to false. This would be useful for silently skipping a value. The advance attribute is used to repeat a value. When set to true, the next call to cycle will print the same value. If you supply the special "assign" attribute, the output of the cycle function will be assigned to this template variable instead of being output to the template. cycle {section name=rows loop=$data} <tr bgcolor="{cycle values="#eeeeee,#d0d0d0"}"> <td>{$data[rows]}</td> </tr> {/section} OUTPUT: <tr bgcolor="#eeeeee"> <td>1</td> </tr> <tr bgcolor="#d0d0d0"> <td>2</td> </tr> <tr bgcolor="#eeeeee"> <td>3</td> </tr> debug Attribute Name Type Required Default Description output string No html output type, html or javascript {debug} dumps the debug console to the page. This works regardless of the debug settings in Smarty. Since this gets executed at runtime, this is only able to show the assigned variables, not the templates that are in use. But, you see all the currently available variables within the scope of this template. 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. 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) 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:password@ftp.domain.com/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_checkboxes Attribute Name Type Required Default Description name string No checkbox name of checkbox list values array Yes, unless using options attribute n/a an array of values for checkbox buttons output array Yes, unless using options attribute n/a an array of output for checkbox buttons checked string No empty the checked checkbox element options associative array Yes, unless using values and output n/a an associative array of values and output separator string No empty string of text to separate each checkbox item html_checkboxes is a custom function that creates an html checkbox group with provided data. It takes care of which item(s) are selected by default as well. Required attributes are values and output, unless you use options instead. All output is XHTML compatible. All parameters that are not in the list above are printed as name/value-pairs inside each of the created <input>-tags. html_checkboxes index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->assign('cust_ids', array(1000,1001,1002,1003)); $smarty->assign('cust_names', array('Joe Schmoe','Jack Smith','Jane Johnson','Charlie Brown')); $smarty->assign('customer_id', 1001); $smarty->display('index.tpl'); index.tpl: {html_checkboxes values=$cust_ids checked=$customer_id output=$cust_names separator="<br />"} index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->assign('cust_checkboxes', array( 1001 => 'Joe Schmoe', 1002 => 'Jack Smith', 1003 => 'Jane Johnson','Charlie Brown')); $smarty->assign('customer_id', 1001); $smarty->display('index.tpl'); index.tpl: {html_checkboxes name="id" options=$cust_checkboxes checked=$customer_id separator="<br />"} OUTPUT: (both examples) <input type="checkbox" name="id[]" value="1000">Joe Schmoe<br /> <input type="checkbox" name="id[]" value="1001" checked="checked"><br /> <input type="checkbox" name="id[]" value="1002">Jane Johnson<br /> <input type="checkbox" name="id[]" value="1003">Charlie Brown<br /> html_image Attribute Name Type Required Default Description file string Yes n/a name/path to image border string No 0 size of border around image height string No actual image height height to display image width string No actual image width width to display image basedir string no web server doc root directory to base relative paths from link string no n/a href value to link the image to html_image is a custom function that generates an HTML tag for an image. The height and width are automatically calculated from the image file if none are supplied. basedir is the base directory that relative image paths are based from. If not given, the web server document root (env variable DOCUMENT_ROOT) is used as the base. If security is enabled, the path to the image must be within a secure directory. link is the href value to link the image to. If link is supplied, an <a href="LINKVALUE"><a> tag is put around the image tag. Technical Note html_image requires a hit to the disk to read the image and calculate the height and width. If you don't use template caching, it is generally better to avoid html_image and leave image tags static for optimal performance. html_image index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->display('index.tpl'); index.tpl: {html_image file="pumpkin.jpg"} {html_image file="/path/from/docroot/pumpkin.jpg"} {html_image file="../path/relative/to/currdir/pumpkin.jpg"} OUTPUT: (possible) <img src="pumpkin.jpg" border="0" width="44" height="68"> <img src="/path/under/docroot/pumpkin.jpg" border="0" width="44" height="68"> <img src="../path/relative/to/currdir/pumpkin.jpg" border="0" width="44" height="68"> 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/array No empty the selected option element(s) options associative array Yes, unless using values and output n/a an associative array of values and output name string No empty name of select group html_options is a custom function that creates html option group with provided data. It takes care of which item(s) are selected by default as well. Required attributes are values and output, unless you use options instead. If a given value is an array, it will treat it as an html OPTGROUP, and display the groups. Recursion is supported with OPTGROUP. All output is XHTML compatible. If the optional name attribute is given, the <select name="groupname"></select> tags will enclose the option list. Otherwise only the option list is generated. All parameters that are not in the list above are printed as name/value-pairs inside the <select>-tag. They are ignored if the optional name is not given. html_options index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->assign('cust_ids', array(1000,1001,1002,1003)); $smarty->assign('cust_names', array('Joe Schmoe','Jack Smith','Jane Johnson','Carlie Brown')); $smarty->assign('customer_id', 1001); $smarty->display('index.tpl'); index.tpl: <select name=customer_id> {html_options values=$cust_ids selected=$customer_id output=$cust_names} </select> index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->assign('cust_options', array( 1001 => 'Joe Schmoe', 1002 => 'Jack Smith', 1003 => 'Jane Johnson', 1004 => 'Charlie Brown')); $smarty->assign('customer_id', 1001); $smarty->display('index.tpl'); index.tpl: <select name=customer_id> {html_options options=$cust_options selected=$customer_id} </select> OUTPUT: (both examples) <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_radios Attribute Name Type Required Default Description name string No radio name of radio list values array Yes, unless using options attribute n/a an array of values for radio buttons output array Yes, unless using options attribute n/a an array of output for radio buttons checked string No empty the checked radio element options associative array Yes, unless using values and output n/a an associative array of values and output separator string No empty string of text to separate each radio item html_radios is a custom function that creates html radio button group 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. All output is XHTML compatible. All parameters that are not in the list above are printed as name/value-pairs inside each of the created <input>-tags. html_radios index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->assign('cust_ids', array(1000,1001,1002,1003)); $smarty->assign('cust_names', array('Joe Schmoe','Jack Smith','Jane Johnson','Carlie Brown')); $smarty->assign('customer_id', 1001); $smarty->display('index.tpl'); index.tpl: {html_radios values=$cust_ids checked=$customer_id output=$cust_names separator="<br />"} index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->assign('cust_radios', array( 1001 => 'Joe Schmoe', 1002 => 'Jack Smith', 1003 => 'Jane Johnson', 1004 => 'Charlie Brown')); $smarty->assign('customer_id', 1001); $smarty->display('index.tpl'); index.tpl: {html_radios name="id" options=$cust_radios checked=$customer_id separator="<br />"} OUTPUT: (both examples) <input type="radio" name="id[]" value="1000">Joe Schmoe<br /> <input type="radio" name="id[]" value="1001" checked="checked"><br /> <input type="radio" name="id[]" value="1002">Jane Johnson<br /> <input type="radio" name="id[]" value="1003">Charlie Brown<br /> html_select_date Attribute Name Type Required Default Description prefix string No Date_ what to prefix the var name with time timestamp/YYYY-MM-DD No current time in unix timestamp or YYYY-MM-DD format 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 output should be in (sprintf) day_value_format string No %d what format the day value 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 month_value_format string No %m strftime format of the month values, default is %m for month numbers. html_select_date is a custom function that creates date dropdowns for you. It can display any or all of year, month, and day. 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> 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 all_extra string No null adds extra attributes to select/input tags if given hour_extra string No null adds extra attributes to select/input tags if given minute_extra string No null adds extra attributes to select/input tags if given second_extra string No null adds extra attributes to select/input tags if given meridian_extra string No null adds extra attributes to select/input tags if given 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. 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> html_table Attribute Name Type Required Default Description loop array Yes n/a array of data to loop through cols integer No 3 number of columns in the table table_attr string No border="1" attributes for table tag tr_attr string No empty attributes for tr tag (arrays are cycled) td_attr string No empty attributes for td tag (arrays are cycled) trailpad string No &nbsp; value to pad the trailing cells on last row with (if any) html_table is a custom function that dumps an array of data into an HTML table. The cols attribute determines how many columns will be in the table. The table_attr, tr_attr and td_attr values determine the attributes given to the table, tr and td tags. If tr_attr or td_attr are arrays, they will be cycled through. trailpad is the value put into the trailing cells on the last table row if there are any present. html_table index.php: require('Smarty.php.class'); $smarty = new Smarty; $smarty->assign('data',array(1,2,3,4,5,6,7,8,9)); $smarty->assign('tr',array('bgcolor="#eeeeee"','bgcolor="#dddddd"')); $smarty->display('index.tpl'); index.tpl: {html_table loop=$data} {html_table loop=$data cols=4 table_attr='border="0"'} {html_table loop=$data cols=4 tr_attr=$tr} OUTPUT: <table border="1"> <tr><td>1</td><td>2</td><td>3</td></tr> <tr><td>4</td><td>5</td><td>6</td></tr> <tr><td>7</td><td>8</td><td>9</td></tr> </table> <table border="0"> <tr><td>1</td><td>2</td><td>3</td><td>4</td></tr> <tr><td>5</td><td>6</td><td>7</td><td>8</td></tr> <tr><td>9</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr> </table> <table border="1"> <tr bgcolor="#eeeeee"><td>1</td><td>2</td><td>3</td><td>4</td></tr> <tr bgcolor="#dddddd"><td>5</td><td>6</td><td>7</td><td>8</td></tr> <tr bgcolor="#eeeeee"><td>9</td><td>&nbsp;</td><td>&nbsp;</td><td>&nbsp;</td></tr> </table> 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 documentation 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. Technical Note math is an expensive function in performance due to its use of the php eval() function. Doing the math in PHP is much more efficient, so whenever possible do the math calculations in PHP and assign the results to the template. Definately avoid repetitive math function calls, like within section loops. 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 mailto Attribute Name Type Required Default Description address string Yes n/a the e-mail address text string No n/a the text to display, default is the e-mail address encode string No none How to encode the e-mail. Can be one of none, hex or javascript. cc string No n/a e-mail addresses to carbon copy. Separate entries by a comma. bcc string No n/a e-mail addresses to blind carbon copy. Separate entries by a comma. subject string No n/a e-mail subject. newsgroups string No n/a newsgroups to post to. Separate entries by a comma. followupto string No n/a addresses to follow up to. Separate entries by a comma. extra string No n/a any extra information you want passed to the link, such as style sheet classes mailto automates the creation of mailto links and optionally encodes them. Encoding e-mails makes it more difficult for web spiders to pick up e-mail addresses off of your site. Technical Note javascript is probably the most thorough form of encoding, although you can use hex encoding too. mailto {mailto address="me@domain.com"} {mailto address="me@domain.com" text="send me some mail"} {mailto address="me@domain.com" encode="javascript"} {mailto address="me@domain.com" encode="hex"} {mailto address="me@domain.com" subject="Hello to you!"} {mailto address="me@domain.com" cc="you@domain.com,they@domain.com"} {mailto address="me@domain.com" extra='class="email"'} OUTPUT: <a href="mailto:me@domain.com" >me@domain.com</a> <a href="mailto:me@domain.com" >send me some mail</a> <SCRIPT language="javascript">eval(unescape('%64%6f%63%75%6d%65%6e%74%2e%77%72%6 9%74%65%28%27%3c%61%20%68%72%65%66%3d%22%6d%61%69%6c%74%6f%3a%6d%65%40%64%6f%6d% 61%69%6e%2e%63%6f%6d%22%20%3e%6d%65%40%64%6f%6d%61%69%6e%2e%63%6f%6d%3c%2f%61%3e %27%29%3b'))</SCRIPT> <a href="mailto:%6d%65@%64%6f%6d%61%69%6e.%63%6f%6d" >&#x6d;&#x65;&#x40;&#x64;& #x6f;&#x6d;&#x61;&#x69;&#x6e;&#x2e;&#x63;&#x6f;&#x6d;</a> <a href="mailto:me@domain.com?subject=Hello%20to%20you%21" >me@domain.com</a> <a href="mailto:me@domain.com?cc=you@domain.com%2Cthey@domain.com" >me@domain.com</a> <a href="mailto:me@domain.com" class="email">me@domain.com</a> 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/. As of Smarty version 2.1.2, overLib does NOT come with the release. Download overLib, place the overlib.js file under your document root and supply the relative path to this file as the "src" parameter to popup_init. popup_init {* popup_init must be called once at the top of the page *} {popup_init src="/javascripts/overlib.js"} 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. popup {* popup_init must be called once at the top of the page *} {popup_init src="/javascripts/overlib.js"} {* 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.) textformat Attribute Name Type Required Default Description style string No n/a preset style indent number No 0 The number of chars to indent every line indent_first number No 0 The number of chars to indent the first line indent_char string No (single space) The character (or string of chars) to indent with wrap number No 80 How many characters to wrap each line to wrap_char string No \n The character (or string of chars) to break each line with wrap_cut boolean No false If true, wrap will break the line at the exact character instead of at a word boundary assign string No n/a the template variable the output will be assigned to textformat is a block function used to format text. It basically cleans up spaces and special characters, and formats paragraphs by wrapping at a boundary and indenting lines. You can set the parameters explicitly, or use a preset style. Currently "email" is the only available style. textformat {textformat wrap=40} This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. {/textformat} OUTPUT: This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. {textformat wrap=40 indent=4} This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. {/textformat} OUTPUT: This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. {textformat wrap=40 indent=4 indent_first=4} This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. {/textformat} OUTPUT: This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. {textformat style="email"} This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. {/textformat} OUTPUT: This is foo. This is foo. This is foo. This is foo. This is foo. This is foo. This is bar. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. bar foo bar foo foo. Config Files Config files are handy for designers to manage global template variables from one file. One example is template colors. Normally if you wanted to change the color scheme of an application, you would have to go through each and every template file and change the colors. With a config file, the colors can be kept in one place, and only one file needs to be updated. Example of config file syntax # global variables pageTitle = "Main Menu" bodyBgColor = #000000 tableBgColor = #000000 rowBgColor = #00ff00 [Customer] pageTitle = "Customer Info" [Login] pageTitle = "Login" focus = "username" Intro = """This is a value that spans more than one line. you must enclose it in triple quotes.""" # hidden section [.Database] host=my.domain.com db=ADDRESSBOOK user=php-user pass=foobar Values of config file variables can be in quotes, but not necessary. You can use either single or double quotes. If you have a value that spans more than one line, enclose the entire value with triple quotes ("""). You can put comments into config files by any syntax that is not a valid config file syntax. We recommend using a # (hash) at the beginning of the line. This config file example has two sections. Section names are enclosed in brackets []. Section names can be arbitrary strings not containing [ or ] symbols. The four variables at the top are global variables, or variables not within a section. These variables are always loaded from the config file. If a particular section is loaded, then the global variables and the variables from that section are also loaded. If a variable exists both as a global and in a section, the section variable is used. If you name two variables the same within a section, the last one will be used. Config files are loaded into templates with the built-in function config_load. You can hide variables or entire sections by prepending the variable name or section name with a period. This is useful if your application reads the config files and gets sensitive data from them that the template engine does not need. If you have third parties doing template editing, you can be certain that they cannot read sensitive data from the config file by loading it into the template. Debugging Console There is a debugging console included with Smarty. The console informs you of all the included templates, assigned variables and config file variables for the current invocation of the template. A template named "debug.tpl" is included with the distribution of Smarty which controls the formatting of the console. Set $debugging to true in Smarty, and if needed set $debug_tpl to the template resource path for debug.tpl (this is in SMARTY_DIR by default.) When you load the page, a javascript console window should pop up and give you the names of all the included templates and assigned variables for the current page. To see the available variables for a particular templates, see the {debug} template function. To disable the debugging console, set $debugging to false. You can also temporarily turn on the debugging console by putting SMARTY_DEBUG in the URL if you enable this option with $debugging_ctrl. Technical Note The debugging console does not work when you use the fetch() API, only when using display(). It is a set of javascript statements added to the very bottom of the generated template. If you do not like javascript, you can edit the debug.tpl template to format the output however you like. Debug data is not cached and debug.tpl info is not included in the output of the debug console. The load times of each template and config file are in seconds, or fractions thereof.