diff --git a/Smarty.addons.php b/Smarty.addons.php index 4c9a767a..d5eee926 100644 --- a/Smarty.addons.php +++ b/Smarty.addons.php @@ -208,12 +208,4 @@ function smarty_func_html_select_date() print $html_result; } -/*============================================*\ - Insert tag functions -\*============================================*/ - -function insert_paginate() -{ - echo "test paginate\n"; -} ?> diff --git a/demo/index.php b/demo/index.php index 79ceaf6f..83565f8a 100644 --- a/demo/index.php +++ b/demo/index.php @@ -12,4 +12,10 @@ $smarty->assign("Class",array(array("A","B","C","D"), array("E", "F", "G", "H"), $smarty->display("./templates/index.tpl"); + +function insert_paginate() +{ + echo "test paginate\n"; +} + ?> diff --git a/doc.sgm b/doc.sgm new file mode 100644 index 00000000..f81f359a --- /dev/null +++ b/doc.sgm @@ -0,0 +1,861 @@ + + + + Smarty - the compiling PHP template engine + MonteOhrt + AndreiZmievski + 2001ispi, Inc. + + + Overview + + It is undoubtedly one of the most asked questions on the PHP mailing + lists: how do I make my PHP scripts independent of the layout? While + PHP is billed as "HTML embedded scripting language", after writing a + couple of projects that mixed PHP and HTML freely one comes up with + the idea that separation of form and content is a Good Thing [TM]. In + addition, in many companies the roles of layout designer and programmer + are separate. Consequently, the search for a templating solution ensues. + + + In our company for example, the development of an application goes on + as follows. After the requirements docs are done, the interface designer + makes mockups of the interface and gives them to the programmer. The + programmer implements business logic in PHP and uses interface mockups + to create skeleton templates. The project is then handed off to the HTML + designer/web page layout person who brings the templates up to their full + glory. The project may go back and forth between programming/HTML a couple + of times. Thus, it's important to have good template support because + programmers don't want anything to do with HTML and don't want HTML + designers mucking around with PHP code, and designers need support for + config files, dynamic blocks and other stuff, but they don't want to + have to deal with intricacies of the PHP programming language. + + + Looking at many templating solutions available for PHP today, + most of them provide a rudimentary way of substituting variables into + templates and do a limited form of dynamic block functionality (a section + of a template that is looped over and over with a set of indexed variables). + But our needs were a bit more than that. We didn't want programmers to be + dealing with HTML layout at ALL, but this was almost inevitable. For + instance, if a designer wanted background colors to alternate on dynamic + blocks, this had to be worked out with the programmer in advance. We also + needed designers to be able to use their own configuration files, and pull + variables from them into the templates. The list goes on. + + + We started out writing out a spec for a template engine about a year ago. + After finishing the spec, we began to work on a template engine written in + C that would hopefully be accepted for inclusion with PHP. Not only did we + run into many complicated technical barriers, but there was also much heated + debate about exactly what a template engine should and should not do. From + this experience, we decided that the template engine should be written in PHP + as a class, for anyone to use as they see fit. So we wrote an engine that did + just that. "SmartTemplate" came to existance (note: this class was never + submitted to the public). It was a class that did almost everything we wanted: + regular variable substitution, supported including other templates, integration + with config files, embedding PHP code, limited 'if' statement functionality and + much more robust dynamic blocks which could be multiply nested. It did all this + with regular expressions and the code turned out to be rather, shall we say, + impenetrable. It was also noticably slow in large applications from all the + parsing and regular expression work it had to do on each invocation. + + + Then came the vision of what ultimately became Smarty. We know how fast PHP + code is without the overhead of template parsing. We also know how meticulous + and overbearing the language may look to the average designer, and this could + be masked with a much simpler templating syntax. So what if we combined the two + strengths? Thus, Smarty was born... + + What is Smarty? + + Smarty is a template engine for PHP. One of the unique aspects about + Smarty that sets it apart from other templating solutions is that it + compiles the templates into native php scripts upon the first + invocation. After that, it merely executes the compiled PHP scripts. + Therefore, there is no costly template file parsing for each request. + + + Some of Smarty's features: + + + It is extremely fast. + It is relatively simple since the PHP parser does the + dirty work. + No template parsing overhead, only compiles once. + It is smart about recompiling only the template + files that have changed. + You can make custom functions and custom variable modifiers, so + the template language is extremely extensible. + Configurable template delimiter tag syntax, so you can use + {}, {{}}, <!--{}-->, or whatever you like. + Template if/else/endif constructs are passed to the PHP parser, + so the if syntax can be as simple or as complex as you like. + Unlimited nesting of sections,ifs, etc. allowed. + It is possible to imbed PHP code right in your template files, + although doubtfully needed since the engine is so customizable. + + + + How Smarty works + compiling + + Smarty compiles the templates into native PHP code on-the-fly. The actual + PHP scripts that are generated are created implicitly, so theoretically you + should never have to worry about touching these files, or even know of their + existance. The exception to this is debugging Smarty template syntax errors, + discussed later in this document. + + + caching + + Our initial intention was to build caching into Smarty. However, + since the template engine is actually executing PHP scripts instead of + parsing template files, the need for a cache was dramatically reduced. + We may implement this in a future version of Smarty as the need arises. + + + + + + Installation + + Requirements + + Smarty requires PHP 4.0.4pl1 or later. 4.0.4 contains a bug that + crashes PHP when certain Smarty features are used (such as the @count modifier). + 4.0.3 and earlier contain a bug in preg_grep() that won't allow the parser to + function properly. We may make some adjusments to work around these + issues in future versions of Smarty. For now, get the very latest version of PHP. + As of this writing, 4.0.4pl1 is not yet available, so a CVS snapshot is necessary. + + + + Installing Smarty + + Installing Smarty is fairly straight forward, 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 template directory, a config file directory and a compiled + template directory. By default these are named "templates","configs" and "templates_c" + respectively. + + + Copy the Smarty.class.php and Smarty.addons.php scripts to a + directory that is in your PHP include_path. NOTE: php will try to create a + directory along side the index.php script called "templates_c". Be sure + that directory permissions allow this to happen. You will see appropriate + error messages if this fails. You can also create the directory yourself + before hand, and change the file ownership accordingly. See below. + + + Example of installing Smarty + + +# be sure you are in the web server document tree +# this assumes your web server runs as user "nobody" +# and you are in a unix environment +gtar -zxvf Smarty-1.0.tar.gz +touch templates_c +chown nobody:nobody templates_c + + + + Next, try running the index.php script from your web browser. + + + + + 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 thier default settings. This is a list + of them and what each one does. + + + Configuration variables + + + $compile_check + + Upon each invocation of the PHP application, Smarty traverses all the template + files and searches for any that have changed (later datestamp) since the last time the + application was invoked. For each one that has changed, it recompiles that + template. By default this is set to true. The compile check has very + minimal impact on the application performance. However, once an application + is put into production and it is initially compiled, the compile_check step + is no longer needed. You may set this to "false" *after* the initial compile. Then + Smarty will no longer check for changed template files. Note that if you change + this to "false" and a template file is changed, you will *not* see the change since + the template will not get recompiled. Set it to "true", invoke the application, + then set it back to "false". + + + + $template_dir + + This is the directory name that template files are kept in. + + + + $compile_dir_ext + + This is the extension used for the name of the directory that compiled templates + are kept in. By default this is "_c". Therefore if your template directory is + named "templates", then the compile directory will be named "templates_c". + + + + $tpl_file_ext + + This is the extention used for template files. By default this is ".tpl". + All other files in the template directory are ignored. + + + + $max_recursion_depth + + This is the maximum depth you can include other templates within templates. + This is to help catch infinite loops when template files accidentally include + each other. + + + + $allow_php + + Whether or not to allow PHP code to be imbedded into the + templates. If set to false, PHP code is escaped and not interpreted. Imbedding + PHP code into templates is highly discouraged. Use custom functions or modifiers + instead. Default is "false". + + + + $left_delimiter + + This is the left delimiter syntax in the templates. Default is "{". + + + + $right_delimiter + + This is the right delimiter syntax in the templates. Default is "}". + + + + $config_dir + + This is the directory used to store config files used in the templates. + Default is "configs". + + + + $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. + + + + $custom_mods + + 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. + + + + $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. + + + + + + Smarty API + + These functions are used in the PHP portion of your application. + + + Smarty API Functions + + assign + + + void assign + mixed var + + + + + void assign + string varname + mixed var + + + + This is used to assign values to the templates. This is usually + data gathered from database queries or other sources of data. + + + + append + + + void append + mixed var + + + + + void append + string varname + mixed var + + + + This is used to append data to existing variables in the template. + + + + clear_assign + + + void clear_assign + string var + + + + This clears the value of an assigned variable. + + + + clear_all_assign + + + void clear_all_assign + + + + + This clears the values of all assigned variables. + + + + get_template_vars + + + array get_template_vars + + + + + This gets an array of the currently assigned template vars. + + + + display + + + void display + string template + + + + This displays the template. + + + + fetch + + + string fetch + string template + + + + This returns the template output. + + + + Using Smarty API + + Example use of Smarty API + + +include("Smarty.class.php"); +$smarty = new Smarty; + +// dummy up some data +$address = "245 N 50th"; +$db_data = array( + "City" => "Lincoln", + "State" => "Nebraska", + "Zip" = > "68502" + ); + +$smarty->assign("Name","Fred"); +$smarty->assign("Address",$address); +$smarty->assign($db_data); + +// display the output +$smarty->display("./templates/index.tpl"); + +// alternatively capture the output +$output = $smarty->fetch("./templates/index.tpl"); + + + + + + + Smarty Templates + + The templates are the heart of Smarty. These are the files that the designers + work with. They're basically pages made up of static content interspersed with + template markup tags. These tags are placeholders for variables or blocks of logic. + + + Syntax + + For these examples, we will assume that you are using the default + template tag delimiters, which are "{" and "}". In Smarty, all content + outside of delimiter tags is displayed as static content, or unchanged. + When Smarty encounters template tags {}, it attempts to interpret what is + between the tags, and displays the appropriate output in place of them. + + + Variables + + There are three basic types of variables in Smarty, each with thier + own unique syntax. + + + Variables assigned from PHP + + Variables that are assigned from PHP are displayed by preceeding + them with a dollar sign ($) and enclosing the variable in delimiters + like so: {$varname} + + +Template example of displaying assigned variables + + +Hello {$firstname}, glad to see you could make it. +<p> +Your last login was on {$lastLoginDate} + + + + There are also variables within looping sections that are displayed + a bit differently, with the section name prepended like so: {$secname/varname}. + Those are exaplained later in this document under Built-in Functions. + + + + Variables passed from config files + + Variables that are passed in from config files are displayed by enclosing + them with hash marks (#) and enclosing the variable in delimiters + like so: {#varname#} + + +Template example of displaying config variables + + +<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 file variables cannot be displayed until + after they are loaded in from a config file. This procedure is + explained later in this document under Built-in Functions. + + + + Variables internal to template + + Variables that are internal to the templates are displayed by enclosing + them with percent signs (%) and enclosing the variable in delimiters + like so: {%varname%} These are usually used in looping sections, so + you will most likely see the variable prepended with the section name + like so: {%secname.varname%}. These are explained in detail later + in this document under Built-in Functions. + + + + + Functions + + Functions are processed and displayed by enclosing the function and its + attributes into delimiters like so: {funcname attr1="val" attr2="val"} + + +Template example of function syntax + + +{config_load file="colors.conf"} + +{include file="header.tpl"} + +{if $name eq "Fred"} + You are not allowed here +{else} + Welcome, <font color="{#fontColor#}">{$name}!</font> +{/if} + +{include file="footer.tpl"} + + + + Both built-in functions and custom functions work exactly the same + way syntactically. + + + + Attributes + + Attributes to functions are much like HTML attributes. Static + values must be enclosed in parenthesis. Variable values may + also be used, and should not be in parenthesis. + + +Template example of function attribute syntax + + +{include file="header.tpl"} + +{include file=$includeFile} + +{include file=#includeFile#} + +{html_options values=$vals selected=$selected output=$output} + + + + + 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 mainly for making the templates more understandable. + + +Template example of Comments + + +{* Smarty *} + +{* include the header file here *} +{include file="header.tpl"} + +{include file=$includeFile} + +{include file=#includeFile#} + +{* display dropdown lists *} +{html_options values=$vals selected=$selected output=$output} + + + + + + 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.""" + + + + Values of config file variables can be in qoutes, 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 hashmark (#) at the + beginning of the line. + + + This config file example has two sections. Section names are enclosed + in brackets []. 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 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 + called config_load. See Built-In functions for examples. + + + + 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. + + + config_load + + This function is used for loading in variables from a + configuration file into the template. + + +Template example of 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". + + +Template example of 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> + + + + + 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. + + +Template example of 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. + 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 content or other variables to included templates. + + +Template example of function include passing variables + + +{include file="header.tpl" title="Main Menu" company=$companyName} + +{* body of template goes here *} + +{include file="footer.tpl" logo="http://my.domain.com/logo.gif"} + + + + + + insert + + The insert tag in Smarty serves a special purpose. You may + run into the situation where it is impossible to pass data to a template + before the template is executed because there is info in the template + needed to aquire the data, kind of a catch 22. The insert tag is a way + to callback a function in PHP during runtime of the template. + + + Let's say you have a page with a banner slot at the top. The template + has a banner_id value, and needs to call a function to get the banner. + + +Template example of function insert + + +{* example of fetching a banner *} +{insert name="getBanner" banner_id=#banner_id# page_id=#page_id#} + + + + + In this example, we are using the name "getBanner" and passing #banner_id# + and #page_id# (which was pulled out of a configuration file). Smarty will look + for a function named insert_getBanner() in your PHP application, passing + the value of #banner_id# and #page_id# as the first argument in an indexed + array. All insert function names in + your application must be prepended with "insert_" to be sure there are + no 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. All values + passed to an insert function are passed as the first argument in an indexed + array. In this example, it would call + insert_getBanner(array("banner_id" => "12345","page_id" => "67890")); + + + Another thing to keep in mind for the insert tag is caching. Smarty does not + currently support caching but if we decide to implement that, insert + tags will not be cached. They will run dynamically every time the page + is created. This works good for things like banners, polls, live weather, + user feedback areas, etc. + + + + if,elseif,else + + + + ldelim,rdelim + + + + literal + + + + section,sectionelse + + + + strip + + + + + Custom Functions + + + html_options + + + + html_select_date + + + + + Custom Modifiers + + + date_format + + + + escape + + + + replace + + + + spacify + + + + string_format + + + + strip_tags + + + + truncate + + + + + Adding your own Custom Functions and Modifiers + + + + + Troubleshooting + + + Smarty/PHP errors + + + + + Using Nedit Macros & Syntax Highlighting + + + + FAQ + + + diff --git a/index.php b/index.php index 79ceaf6f..83565f8a 100644 --- a/index.php +++ b/index.php @@ -12,4 +12,10 @@ $smarty->assign("Class",array(array("A","B","C","D"), array("E", "F", "G", "H"), $smarty->display("./templates/index.tpl"); + +function insert_paginate() +{ + echo "test paginate\n"; +} + ?>