diff --git a/Smarty.addons.php b/Smarty.addons.php index d5eee926..c6a1f2e7 100644 --- a/Smarty.addons.php +++ b/Smarty.addons.php @@ -82,7 +82,7 @@ function smarty_mod_date_format($string, $format) } -function smarty_mod_string_format($string, $format) +function smarty_mod_string_format($string, $format="%b %e, %Y") { return sprintf($format, $string); } diff --git a/doc.sgm b/doc.sgm index c579567a..d4479e30 100644 --- a/doc.sgm +++ b/doc.sgm @@ -780,8 +780,9 @@ Intro = """This is a value that spans more if statements in Smarty have much the same flexability as php if statements, with a few added features for the template engine. Every if must be paired with /if. else and elseif are also permitted. - "eq", "ne","neq", "gt", "lt", "lte", "le", "gte" "ge","is","is not","not", - "mod","by","==","!=",">","<","<=",">=" are all valid conditional qualifiers. + "eq", "ne","neq", "gt", "lt", "lte", "le", "gte" "ge","is even","is odd", + "is not even","is not odd","not","mod","even by","odd by","==","!=",">", + "<","<=",">=" are all valid conditional qualifiers. Template example of if statements @@ -806,7 +807,7 @@ Intro = """This is a value that spans more {/if} {* you can also imbed php functionality, where appropriate *} -{if count($var) lt 0} +{if count($var) gt 0} ... {/if} @@ -907,74 +908,248 @@ Intro = """This is a value that spans more This way you can keep your templates readable, and not worry about extra white space causing problems. - Template example of strip tags +{* the following will be all run into one line upon output *} {strip} - - - - -
- - This is a test - -
+<table border=0> + <tr> + <td> + <A HREF="{$url}"> + <font color="red">This is a test</font> + </A> + </td> + </tr> +</table> {/strip} + Custom Functions - + + Custom functions in Smarty work much the same as the built-in functions + syntactically. Two custom functions come bundled with Smarty. You can + also write your own. + html_options - + + html_options is a custom function that creates html option + lists with provided data. It takes care of which item is + selected by default as well. + + +Template example of html_options + + +{* assume that $cust_ids, and $cust_names are arrays of values, + and $customer_id may or may not be set to a value *} + +<select name=customer_id> + {html_options values=$cust_ids selected=$customer_id output=$cust_names} +</select> + + + + + + This will create an option dropdown list using the values + of the variables supplied in the template. + html_select_date - + + html_select_date is a custom function that creates date dropdowns + for you. It can display any or all of year, month, and day. Possible + attributes are (attr name, type, default val): + + + prefix,string,"Date_" + time,timestamp,(current time) + start_year,int,(current year) + end_year int (current year) + display_days, boolean, true + display_months, boolean, true + display_years, boolean, true + month_format, strftime, "%B" + day_format, strftime, "%02d" + year_as_text, boolean, true + + +Template example of html_select_date + + +{html_select_date} + +{html_select_date prefix="Date_" time=$time start_year=1995 end_year=2001} + + + + + + + Creating your own Custom Functions + + Creating your own functions is a fairly straight forward process. + The best way is to look at the two that come with Smarty as + examples. They are located in the Smarty.addons.php file. + + + add your function to the Smarty.addons.php file. + it is recommended that you prepend your function name + with smarty_func_ + map a template function name to your PHP function. + This is done at the top of the Smarty.class.php file + in the $custom_funcs array. + Thats it! you can now call that function + from within Smarty. + + + All attributes passed to custom functions are passed into the + first argument as an indexed array. One way to get to those + values is to call extract(func_get_arg(0)); at the top of your + function. Anything that the function returns gets displayed + in place of the tag in the template. + - Custom Modifiers - + Variable Modifiers + + Variable modifiers are a bit different than custom functions. + They do just what they sound like, they modify variables before + they are displayed to the template. The best way to explain + these are by example. + + +Template example of variable modifiers + + +{* this displays a variable, unmodified *} +{$articleTitle} + +{* this displays the variable in all upper case *} +{$articleTitle|upper} + +{* this displays the variable html escaped *} +{$articleTitle|escape} + +{* this displays the variable uppercased AND html escaped *} +{$articleTitle|upper|escape} + +{* an example of passing a parameter to a modifier: + this displays the variable url escaped *} +{$articleTitle|escape:"url"} + +{* print the hour, minute and second portion of a date *} +{$startTime|date_format:"%h:%m:%s"} + +{* print the first 24 characters of this variable, and + follow with ... if it was longer *} +{$articleTitle|truncate:24:"..."} + +{* print a number to the first two decimals *} +{$amount|string_format:"%.2f"} + + + + + Hopefully you get a good picture of how these work, and the + power they have in a template engine. All modifiers will get + the value of the variable as the first argument, and must return + a single value. Modifier parameters are separated by colons. Any + additional parameters passed to a modifier are passed as-is positionally, + much like calling a PHP function. You can also use native + PHP functions as modifiers, but only if they expect the correct + arguments. If they do not, you can always write a wrapper function + in Smarty to get what you want (date_format is a wrapper function + to strftime() for example.) You can chain as many modifiers + together on a variable as you like. + + + Another thing to be aware of: if you pass an array to a modifier + instead of a single value, the modifier will be applied to every + value in that array. If you really want the entire array passed + to the modifier, you must prepend it with an "@" sign like so: + {$articleTitle|@count} (this will print out the number of elements + in the $articleTitle array.) + date_format - + + This formats a date into the given strftime() format. All dates + should be passed to Smarty as a timestamp so that the template + designer has full control of how this date is formatted. The + default format is "%b %e, %Y". + escape - + + This is used to html or url escape a variable. By default, + the variable is html escaped. possible arguments are "url" or "html". + replace - + + A simple search and replace on a variable. The first argument is + what to search for, the second argument is what to replace it with. + spacify - + + spacify is a way to insert spaces between every character of a variable. + You can optionally pass a different character (or string) to insert. + string_format - + + This is a way to format strings, such as decimal numbers and such. + Use the syntax for sprintf for the formatting. + strip_tags - + + This strips out markup tags, basically anything between < and >. + truncate - + + This truncates a variable to a certain 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 indeed truncated. + + + + Creating your own Variable Modifiers + + Creating your own modifiers is a fairly straight forward process. + The best way is to look at the ones that come with Smarty as + examples. They are located in the Smarty.addons.php file. + + + add your modifier to the Smarty.addons.php file. + it is recommended that you prepend your function name + with smarty_mod_ + map a template modifier name to your PHP function. + This is done at the top of the Smarty.class.php file + in the $custom_mods array. + Thats it! you can now use that modifier + from within Smarty. + - - Adding your own Custom Functions and Modifiers - - Troubleshooting