diff --git a/doc.sgm b/doc.sgm index d4479e30..457fa1c4 100644 --- a/doc.sgm +++ b/doc.sgm @@ -802,7 +802,7 @@ Intro = """This is a value that spans more {/if} {* parenthesis are allowed *} -{if ( $amount lt 0 or $amount gt 1000 ) and $volume ne #minVolAmt#} +{if ( $amount < 0 or $amount > 1000 ) and $volume >= #minVolAmt#} ... {/if} @@ -851,6 +851,10 @@ Intro = """This is a value that spans more {ldelim}funcname{rdelim} is how functions look in Smarty! + +OUTPUT: + +{funcname} is how functions look in Smarty! @@ -890,12 +894,154 @@ Intro = """This is a value that spans more section,sectionelse - + + 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 + determines the number of times the section will loop. sectionelse + will be used if there are no values in the loop variable. + When printing a variable within a section, the section name + must be prepended to the variable name, separated by a slash (/). + sectionelse is executed when there are no values in the loop + variable. + + +example: section + + + +{* this example will print out all the values of the $custid array *} +{section name=customer loop=$custid} + id: {$customer/custid}<br> +{/section} + +OUTPUT: + +id: 1000<br> +id: 1001<br> +id: 1002<br> + + + + + +example: 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: {$customer/custid}<br> + name: {$customer/name}<br> + address: {$customer/address}<br> + <p> +{/section} + + +OUTPUT: + +id: 1000<br> +name: John Smith<br> +address: 253 N 45th +<p> +id: 1001<br> +name: Jack Jones<br> +address: 417 Mulberry ln +<p> +id: 1002<br> +name: Jane Munson +address: 5605 apple st +<p> + + + + + +example: 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: {$mydata/custid}<br> + name: {$mydata/name}<br> + address: {$mydata/address}<br> + <p> +{/section} + + + + + +example: 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, $customer/contact_type is an array of + contact types for the current customer. *} +{section name=customer loop=$custid} + id: {$customer/custid}<br> + name: {$customer/name}<br> + address: {$customer/address}<br> + {section name=contact loop=$customer/contact_type} + {$customer/contact/contact_type}: {$customer/contact/contact_info}<br> + {/section} + <p> +{/section} + + +OUTPUT: + +id: 1000<br> +name: John Smith<br> +address: 253 N 45th +home phone: 555-555-5555 +cell phone: 555-555-5555 +e-mail: john@mydomain.com +<p> +id: 1001<br> +name: Jack Jones<br> +address: 417 Mulberry ln +home phone: 555-555-5555 +cell phone: 555-555-5555 +e-mail: jack@mydomain.com +<p> +id: 1002<br> +name: Jane Munson +address: 5605 apple st +home phone: 555-555-5555 +cell phone: 555-555-5555 +e-mail: jane@mydomain.com +<p> + + + + + + +example: sectionelse + + +{* sectionelse will execute in the case there are no $custid values *} +{section name=customer loop=$custid} + id: {$customer/custid}<br> +{sectionelse} + there are no values in $custid. +{/section} + + + strip - strip is another nice feature of the template engine. Many times + Strip is another nice feature of the template engine. Many times you 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 @@ -904,7 +1050,8 @@ Intro = """This is a value that spans more Anything within {strip}{/strip} tags in Smarty are stripped of - the extra spaces or carriage returns before they are displayed. + 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. @@ -925,8 +1072,19 @@ Intro = """This is a value that spans more </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. + @@ -955,6 +1113,15 @@ Intro = """This is a value that spans more </select> +OUTPUT: + +<select name=customer_id> + <option value="1000">Joe Schmoe<option> + <option value="1001" selected>Jack Smith<option> + <option value="1002">Jane Johnson<option> + <option value="1003">Charlie Brown<option> +</select> + @@ -973,7 +1140,7 @@ Intro = """This is a value that spans more prefix,string,"Date_" time,timestamp,(current time) start_year,int,(current year) - end_year int (current year) + end_year int (same as start_year) display_days, boolean, true display_months, boolean, true display_years, boolean, true @@ -987,8 +1154,94 @@ Intro = """This is a value that spans more {html_select_date} -{html_select_date prefix="Date_" time=$time start_year=1995 end_year=2001} +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> + + + + + + +Template example of html_select_date + + + +{html_select_date prefix="StartDate" time=$time start_year=1995 end_year=2001 display_days=false} + +<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> @@ -997,12 +1250,13 @@ Intro = """This is a value that spans more 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. + The best way is to look at the ones that come with Smarty as + examples. The function names begin with smarty_func_ and 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 + 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 @@ -1034,60 +1288,184 @@ Intro = """This is a value that spans more {* this displays a variable, unmodified *} {$articleTitle} +OUTPUT: + +Burger King fire leaves seven pregnant teenagers <jobless> + + {* this displays the variable in all upper case *} {$articleTitle|upper} +OUTPUT: + +BURGER KING FIRE LEAVES SEVEN PREGNANT TEENAGERS <JOBLESS> + + {* this displays the variable html escaped *} {$articleTitle|escape} +OUTPUT: + +Burger King fire leaves seven pregnant teenagers &lt;jobless&gt; + + {* this displays the variable uppercased AND html escaped *} {$articleTitle|upper|escape} +OUTPUT: + +BURGER KING FIRE LEAVES SEVEN PREGNANT TEENAGERS &lt;JOBLESS&gt; + + {* 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"} +OUTPUT: + +Burger+King+fire+leaves+seven+pregnant+teenagers+%3Cjobless%3e + {* print the first 24 characters of this variable, and follow with ... if it was longer *} {$articleTitle|truncate:24:"..."} +OUTPUT: + +Burger King fire... + + +{* print the date in default format *} +{$startTime|date_format} + +OUTPUT: + +Dec 13, 2000 + + +{* print the hour, minute and second portion of a date *} +{$startTime|date_format:"%h:%m:%s"} + +OUTPUT: + +10:33:02 + {* print a number to the first two decimals *} {$amount|string_format:"%.2f"} +OUTPUT: + +24.02 + - 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, + 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. + together on a variable as you like, separating each with a vertical + pipe "|". - 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 + NOTE: if you apply a modifier to an array + instead of a single value variable, 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.) + + captialize + + This is used to capitalize the first letter of all words in a variable. + + 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". + default format is "%b %e, %Y", or "Jan 4, 2001" for example. + These are the possible conversion specifiers: + +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') + +%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) + +%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 - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week + +%w - day of the week as a decimal, Sunday being 0 + +%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 + + + escape @@ -1096,6 +1474,12 @@ Intro = """This is a value that spans more the variable is html escaped. possible arguments are "url" or "html". + + lower + + This is used to lowercase a variable. + + replace @@ -1126,9 +1510,19 @@ Intro = """This is a value that spans more truncate - This truncates a variable to a certain length, default is 80. As + 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 indeed truncated. + to display at the end if the variable was indeed 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. + + + + upper + + This is used to uppercase a variable. @@ -1136,11 +1530,12 @@ Intro = """This is a value that spans more 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. + examples. The function names begin with smarty_mod_ and 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 + 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 @@ -1156,12 +1551,30 @@ Intro = """This is a value that spans more Smarty/PHP errors - + + As of now, Smarty is not a validating template parser. This means that + the parser will blindly convert the template to PHP scripts, irregardless + of any syntax errors in the markup tags that may be present in the template. + These types of errors can end up in PHP run-time errors. + When you encounter a PHP error when attempting to display the + template in a browser, the error line number will correspond to the + compiled PHP template, not the template itself. This may be a bit confusing + or for the template designer. Our experience is to tell the + designers to check their work often, and ask the programmers for help + if they are really stuck. Usually you can look at the template and spot the + syntax error. Maybe you left a delimeter off, or you didn't properly close + an {if}{/if} or {section}{/section} tag. If you can't find it, you must open + the compiled PHP file and go to the line number to figure out what went wrong. + - Using Nedit Macros & Syntax Highlighting - + Syntax Highlighting in editors + + We have created some syntax highlighting for Nedit, a freely downloadable + text editor for X windows. You can find the files and instructions on the + Smarty web site. + FAQ