From ec925da432c25e96b30fbb3dff11f9e5390af85b Mon Sep 17 00:00:00 2001 From: mohrt Date: Fri, 9 Feb 2001 19:54:47 +0000 Subject: [PATCH] update documentation, add examples to test script. --- INSTALL | 4 + QUICKSTART | 2 +- demo/index.php | 4 + demo/templates/header.tpl | 2 +- demo/templates/index.tpl | 15 +++ docs.sgml | 247 ++++++++++++++++++++++++-------------- index.php | 4 + templates/header.tpl | 2 +- templates/index.tpl | 15 +++ 9 files changed, 199 insertions(+), 96 deletions(-) diff --git a/INSTALL b/INSTALL index 08bcb071..1f06c77e 100644 --- a/INSTALL +++ b/INSTALL @@ -23,3 +23,7 @@ INSTALLATION: * setup your php and template files. A good working example is included to get you started. Also see the QUICKSTART guide for some more examples. + +* TECHNICAL NOTE: If you do not have access to the php.ini file, you can change + non-server settings (such as your include_path) with the ini_set() command. + example: ini_set("include_path",".:/usr/local/lib/php"); diff --git a/QUICKSTART b/QUICKSTART index f5ed1af2..6098653a 100644 --- a/QUICKSTART +++ b/QUICKSTART @@ -42,7 +42,7 @@ Smarty needs to be able to write to the templates_c directory. It is recommended that you change the ownership and write permissions such that the web server user (usually nobody) has write access to this directory. You can chmod 777 the directory, but be aware of security concerns on multi-user -systems. +systems. See the documentation for more info on this. $> chown nobody:nobody templates_c $> chmod 700 templates_c diff --git a/demo/index.php b/demo/index.php index 41b66483..3794acb0 100644 --- a/demo/index.php +++ b/demo/index.php @@ -15,6 +15,10 @@ $smarty->assign("Class",array(array("A","B","C","D"), array("E", "F", "G", "H"), $smarty->assign("contacts", array(array("phone" => "1", "fax" => "2", "cell" => "3"), array("phone" => "555-4444", "fax" => "555-3333", "cell" => "760-1234"))); +$smarty->assign("option_values", array("NY","NE","KS","IA","OK","TX")); +$smarty->assign("option_output", array("New York","Nebraska","Kansas","Iowa","Oklahoma","Texas")); +$smarty->assign("option_selected", "NE"); + $smarty->display('index.tpl'); ?> diff --git a/demo/templates/header.tpl b/demo/templates/header.tpl index 018d027d..3724c783 100644 --- a/demo/templates/header.tpl +++ b/demo/templates/header.tpl @@ -1,3 +1,3 @@ - + {$title} - {$Name} diff --git a/demo/templates/index.tpl b/demo/templates/index.tpl index 55b2f2ad..edd54399 100644 --- a/demo/templates/index.tpl +++ b/demo/templates/index.tpl @@ -5,6 +5,7 @@ {* bold and title are read from the config file *} {if #bold#}{/if} +{* capitalize the first letters of each word of the title *} Title: {#title#|capitalize} {if #bold#}{/if} @@ -45,4 +46,18 @@ testing strip tags {/strip} +This is an example of the html_select_date function: + +
+{html_select_date start_year=1998 end_year=2010} +
+
+
+This is an example of the html_options function:
+
+
+ +
diff --git a/docs.sgml b/docs.sgml index 92f8e37b..98874efc 100644 --- a/docs.sgml +++ b/docs.sgml @@ -168,17 +168,37 @@ Installing Smarty - Installing Smarty is fairly straightforward, there is just one thing - you must be aware of. Remember that Smarty creates compiled versions of - the template code. This usually means allowing user "nobody" (or - whomever the web server runs as) to have permission to write the files. - Each installation of a Smarty application minimally needs a templates - directory and a compiled templates directory. If you use configuration - files you will also need a directory for those. By default these are - named "templates", and "templates_c" and "configs" respectively. If you - plan on using caching, you will need to create a "cache" directory, also - with permission to write files. + Installing Smarty is fairly straightforward, there is just one thing + you must be aware of. Smarty creates PHP scripts from the templates. + This usually means allowing user "nobody" (or whomever the web server + runs as) to have permission to write the files. Each installation of a + Smarty application minimally needs a templates directory and a compiled + templates directory. If you use configuration files you will also need + a directory for those. By default these are named "templates", and + "templates_c" and "configs" respectively. If you plan on using caching, + you will need to create a "cache" directory, also with permission to + write files. + + TECHNICAL NOTE: You can get around the need to allow the web server + user write access to compile templates. Smarty needs to compile the + templates only once. This can be done from the command line, using the + CGI version of PHP. example: "php -q index.php". Once the templates are + compiled, they should run fine from the web environment. If you change + a template, you must recompile from the command line again. If you do + not have the CGI version of PHP available and you are concerned about + world-writable directory access, you can chmod 777 the compile_dir, let + the templates compile once as the web server user, then change the + directory mode back to 700. If you are using the caching feature of + Smarty, the cache directory must always have write access for the web + server user. + + + TECHNICAL NOTE: If you do not have access to the php.ini file, you can + change non-server settings (such as your include_path) with the + ini_set() command (available in PHP 4.0.4 or later.) example: + ini_set("include_path",".:/usr/local/lib/php"); + Copy the Smarty.class.php, Smarty.addons.php and Config_File.class.php scripts to a directory that is in your PHP include_path. NOTE: PHP will @@ -195,10 +215,11 @@ # be sure you are in the web server document tree # this assumes your web server runs as user "nobody" # and you are in a un*x environment -gtar -zxvf Smarty-1.0.tar.gz +gtar -zxvf Smarty-[version].tar.gz mkdir templates_c chown nobody:nobody templates_c chmod 700 templates_c +# if you are using caching, do the following mkdir cache chown nobody:nobody cache chmod 700 cache @@ -212,9 +233,8 @@ chmod 700 cache Setting up Smarty - There are several variables that are at the top of the Smarty.class.php - file. You can usually get away with leaving these at their default - settings. This is a list of them and what each one does. + There are several variables that are at the top of the Smarty.class.php + file. The default settings work for all of the examples and tutorials. Configuration variables @@ -225,6 +245,10 @@ chmod 700 cache This is the name of the directory where template files are located. By default this is "./templates". + + TECHNICAL NOTE: It is not mandatory to put this directory under + the web server document root. + $compile_dir @@ -233,21 +257,34 @@ chmod 700 cache located. By default this is "./templates_c". This was added to Smarty version 1.2.1. + + TECHNICAL NOTE: This setting must be either a relative or + absolute path. include_path is not used for writing files. + + + TECHNICAL NOTE: It is not mandatory to put this directory under + the web server document root. + $config_dir This is the directory used to store config files used in the templates. - Default is "configs". + Default is "./configs". + + + TECHNICAL NOTE: It is not mandatory to put this directory under + the web server document root. $global_assign - This is a list of variables that are always implicitly assigned to the - template engine. This is usually handy for making global variables or server - variables available to the template without having to manually assign them to - the template every time. + This is a list of variables that are always implicitly assigned + to the template engine. This is handy for making global + variables or server variables available to all templates + without having to manually assign them. $SCRIPT_NAME is + globally assigned by default. @@ -279,16 +316,13 @@ chmod 700 cache $caching - This tells Smarty whether or not to cache the output of the - templates. By default this is set to false. If your templates - generate the same content over and over, it is advisable to - turn on caching. This will result significant performance - gains. Smarty uses a combination of the template being called - and the URL ($PHP_SELF) for the cache indentification. This way - you can have multiple caches for the same template. NOTE: If - you ever turn caching off after templates are compiled, be sure - to recompile all of your templates once. Otherwise you may get - undesireable results. This was added to Smarty 1.3.0. + This tells Smarty whether or not to cache the output of the + templates. By default this is set to false. If your templates + generate the same content over and over, it is advisable to + turn on caching. This will result significant performance + gains. You can also have multiple caches for the same template. + See is_cached for details. + This was added to Smarty 1.3.0. @@ -298,6 +332,14 @@ chmod 700 cache located. By default this is "./cache". This was added to Smarty version 1.3.0. + + TECHNICAL NOTE: This setting must be either a relative or + absolute path. include_path is not used for writing files. + + + TECHNICAL NOTE: It is not mandatory to put this directory under + the web server document root. + $cache_lifetime @@ -345,8 +387,10 @@ chmod 700 cache $custom_funcs This is a mapping of the names of custom functions in the template to - the names of functions in PHP. These are usually kept in Smarty.addons.php. + linkend="custom.functions">custom functions in the + template to the names of functions in PHP. The default custom + functions that come bundled with Smarty are located in + Smarty.addons.php. @@ -354,7 +398,9 @@ chmod 700 cache This is a mapping of the names of variable modifiers in the template to - the names of functions in PHP. These are usually kept in Smarty.addons.php. + the names of functions in PHP. The default variable modifiers + that come bundled with Smarty are located in + Smarty.addons.php. @@ -600,7 +646,7 @@ $smarty->clear_all_cache(); void is_cached - stringtemplate + string template @@ -623,6 +669,10 @@ $smarty->display("index.tpl"); + + You can also pass a cache id as an an optional second parameter + in the case you want multiple caches for the given template. + is_cached with multiple-cache template @@ -718,8 +768,9 @@ $smarty->display("index.tpl"); - This returns the template output. Supply a path relative to the - template directory + This returns the template output instead of displaying it. + Supply a path relative to the template directory fetch @@ -971,16 +1022,15 @@ zaphod@slartibartfast.com<br> 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. - Note that to use config files, you must include the Config_File.class.php - In your PHP include path. Config_File.class.php comes bundled with - Smarty. Smarty will implicitly include the file if you - don't already include it in your application. + 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. Note that to use config files, you must place the + Config_File.class.php in your PHP include path. Config_File.class.php + comes bundled with Smarty. Smarty will implicitly include the file if + you don't already include it in your application. Example of config file syntax @@ -1062,10 +1112,16 @@ Intro = """This is a value that spans more - Config files may also contain sections. You can load - variables from within a section with the added attribute - "section". + 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 @@ -1090,12 +1146,11 @@ Intro = """This is a value that spans more include - Include tags are used for including other templates into - the current template. When a template is included, it - inherits all the variables available to the current template. - The include tag must have the attribute "file", which - contains the path to the included template file relative - to the template directory. + 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 path to the included + template file relative to the template directory. function include @@ -1109,13 +1164,11 @@ Intro = """This is a value that spans more - You can also pass variables to included templates as attributes. - These will be passed to the template along with the current - template variables. Attribute variables override template - variables, in the case they are named alike. You can - pass either static values or variables to included templates - (although it doesn't make much sense to pass anything other than - static values since variables are inherited anyways). + 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 @@ -1313,17 +1366,19 @@ OUTPUT: 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. - 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. + 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 prepended to the variable name, separated by a + slash (/). If you are using an associative array, separate the key + and value with a period (.). sectionelse is + executed when there are no values in the loop variable. section @@ -1570,12 +1625,10 @@ There were 3 customers shown above. show - show is used both as a parameter to section, - as well as displaying its value. 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. + 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 property rownum @@ -1971,6 +2024,10 @@ OUTPUT: function. Anything that the function returns gets displayed in place of the tag in the template. + + You can also add custom functions programatically with the register_function API. + @@ -2573,6 +2630,10 @@ IF STRIKE ISN'T SETTLED QUICKLY IT MAY LAST A WHILE. Thats it! you can now use that modifier from within Smarty. + + You can also add modifiers programatically with the register_modifier API. + @@ -2601,18 +2662,19 @@ Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name - Smarty shows you the template name, the line number and the error. - Everything beyond that is PHP error messages which you can ignore. + Smarty shows you the template name, the line number and the error. + After that, the error consists of the actual line number in the Smarty + class that the error occured. - There are certain errors that Smarty cannot catch, such as missing - close tags. These types of errors can end up in PHP compile-time - errors. + There are certain errors that Smarty cannot catch, such as missing + close tags. These types of errors usually end up in PHP compile-time + parsing errors. -PHP errors +PHP parsing errors Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75 @@ -2621,15 +2683,14 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75 - 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 script, not the template itself. This may be a bit - confusing. Usually you can look at the template and spot the syntax - error. Here are some common things to look for: missing close tags for - {if}{/if} or {section}{/section}, or syntax of logic within an {if} - tag. If you can't find the error, you must open the compiled PHP file - and go to the line number to figure out where the corresponding error - is in the template. + When you encounter a PHP parsing error, the error line number will + correspond to the compiled PHP script, not the template itself. Usually + you can look at the template and spot the syntax error. Here are some + common things to look for: missing close tags for {if}{/if} or + {section}{/section}, or syntax of logic within an {if} tag. If you + can't find the error, you might have to open the compiled PHP file and + go to the line number to figure out where the corresponding error is in + the template. diff --git a/index.php b/index.php index 41b66483..3794acb0 100644 --- a/index.php +++ b/index.php @@ -15,6 +15,10 @@ $smarty->assign("Class",array(array("A","B","C","D"), array("E", "F", "G", "H"), $smarty->assign("contacts", array(array("phone" => "1", "fax" => "2", "cell" => "3"), array("phone" => "555-4444", "fax" => "555-3333", "cell" => "760-1234"))); +$smarty->assign("option_values", array("NY","NE","KS","IA","OK","TX")); +$smarty->assign("option_output", array("New York","Nebraska","Kansas","Iowa","Oklahoma","Texas")); +$smarty->assign("option_selected", "NE"); + $smarty->display('index.tpl'); ?> diff --git a/templates/header.tpl b/templates/header.tpl index 018d027d..3724c783 100644 --- a/templates/header.tpl +++ b/templates/header.tpl @@ -1,3 +1,3 @@ - + {$title} - {$Name} diff --git a/templates/index.tpl b/templates/index.tpl index 55b2f2ad..edd54399 100644 --- a/templates/index.tpl +++ b/templates/index.tpl @@ -5,6 +5,7 @@ {* bold and title are read from the config file *} {if #bold#}{/if} +{* capitalize the first letters of each word of the title *} Title: {#title#|capitalize} {if #bold#}{/if} @@ -45,4 +46,18 @@ testing strip tags {/strip} +This is an example of the html_select_date function: + +
+{html_select_date start_year=1998 end_year=2010} +
+
+
+This is an example of the html_options function:
+
+
+ +