diff --git a/QUICKSTART b/QUICKSTART new file mode 100644 index 00000000..b9d202a5 --- /dev/null +++ b/QUICKSTART @@ -0,0 +1,283 @@ +SMARTY QUICKSTART GUIDE +----------------------- + +So you don't like reading documentation either? This guide is to help you +immediately get your feet wet in Smarty, get a feel for how it works, what it is +for and if it will work for you. + +We make a few assumptions here, such as you already have PHP installed on your +web server, you know the basics of unix file permissions, the basics of PHP and +how it works, etc. + +OK, Let's get started. + +INSTALLATION +------------ + +Unpack the Smarty tarball. You will see three class files: Smarty.class.php, +Smarty.addons.php and Config_File.class.php. You will need to have all three of +these files somewhere in your PHP include path, so when you call +require("Smarty.class.php") from within your application, it can find the class. + +Ok, now change directories somewhere inside of your web server document root. +For this guide, we'll create a directory under the document root named "Smarty", +and put all of our work here. + +$> cd /home/htdocs +$> mkdir Smarty +$> cd Smarty + +now, we need to create a few directories for Smarty to use: + +$> mkdir templates +$> mkdir templates_c +$> mkdir configs + +Smarty needs to be able to write to the templates_c directory. You can change +the ownership of this directory to your web server user, but we'll just +change the permissions to 777 (drwxrwxrwx) to make it easy for this guide. + +$> chmod 777 templates_c +$> ls -l +drwxrwxr-x 2 mohrt staff 512 Jan 18 14:18 configs/ +drwxrwxr-x 2 mohrt staff 512 Jan 18 14:18 templates/ +drwxrwxrwx 2 mohrt staff 512 Jan 18 14:18 templates_c/ + + +Now we need to create two files, index.php and templates/index.tpl. index.php +is the file that we will be calling from our web browser. index.tpl is the file +that Smarty will use as it's template file. (.tpl files are never called +directly from the browser, only Smarty calls them.) + + +--------- index.php -------- +assign("Name","Fred"); +$smarty->display("./templates/index.tpl"); +?> + + +--------- templates/index.tpl -------- + +Hello + + Hello, {$Name}! + + + + +Now, view the index.php file from your web browser: +http://your.host.com/Smarty/index.php + +You should see "Hello, Fred!" in your browser. If not, retrace the steps above +and make sure you follow the instructions exactly as they say. Also check the +installation instructions in the documenation, and check your installation of +PHP to be sure things are setup properly. + +You see "Hello, Fred!" in your browser? Good! + +What happened here is Smarty took the index.tpl file and compiled it into a php +script which you can take a look at in the templates_c directory. Smarty will +continue to use this compiled script until the index.tpl file is changed, then +it will automatically recompile. What this means for you: forget about the +templates_c directory. Out of site, out of mind. You don't need to worry about +it, Smarty takes care of this technical stuff. Out of curiosity you can see how +your templates look as compiled php scripts, but please don't touch them! + +Now that we have Smarty functioning properly, let's get into the guts of Smarty +and learn what thing is all about. I'll try to briefly show examples to cover +the most important features of Smarty. + + +ASSIGNING VARIABLES +------------------- + +Assigning variables to the template are very similar to the ways you see other +template engines assign them. Example: + + +--------- index.php -------- +assign("Name","Fred"); +$smarty->assign(array( + "FirstName" => "Fred", + "LastName" => "Flanders", + "Address" => "Springfield" + )); +$zipcode = "55555"; +$smarty->assign("Zipcode",$zipcode); +$smarty->display("./templates/index.tpl"); +?> + + +--------- templates/index.tpl -------- + +Hello + + Hello, {$Name}!
+ {$FirstName}, {$LastName}
+ {$Address}, {$Zipcode} + + + + +You can assign variables either single fasion, or as an associative array. There +is also a way to append to assigned variables. See the documentation for +details. + +INCLUDE +------- + +Now, let's see how Smarty can be used to include other template files. This is +handy if you have repetitive template data, such as headers and footers. You +will need to create a couple more template files: templates/header.tpl and +templates/footer.tpl. + +--------- index.php -------- +assign("Name","Fred"); +$smarty->assign(array( + "FirstName" => "Fred", + "LastName" => "Flanders", + "Address" => "Springfield" + )); +$zipcode = "55555"; +$smarty->assign("Zipcode",$zipcode); +$smarty->display("./templates/index.tpl"); +?> + + +--------- templates/index.tpl -------- +{include file="header.tpl" title="Home Page"} + Hello, {$Name}!
+ {$FirstName}, {$LastName}
+ {$Address}, {$Zipcode} +{include file="footer.tpl"} + +--------- templates/header.tpl -------- + +{$title|default:"Home Page"} + + +--------- templates/footer.tpl -------- + + + + +Notice we are passing the variable "title" when we include the header.tpl file. +You can pass as many variables as you want. The included file inherits all the +current template vars, plus any that are passed to it. The passed variables are +only available within the scope of the included file. Also notice the way the +$title variable is printed to the template. It uses a variable modifier called +"default". Printing {$title|default:"Home Page"} means that if the value of +$title is empty, the text "Home Page" will be printed instead of nothing. + +IF/ELSEIF/ELSE +-------------- + +This systax is very straight forward. The documention goes into depth on this +one, so you should be able to do just about anything you want to with it. +Example: + +--------- templates/index.tpl -------- +{include file="header.tpl" title="Home Page"} + {if $Name eq ""} + Hello, Noname!
+ {elseif $Name eq "Fred"} + Hello, Frederick!
+ {else} + Hello, {$Name}
+ {/if} + + {$FirstName}, {$LastName}
+ {$Address}, {$Zipcode} +{include file="footer.tpl"} + + +SECTIONS (Dynamic Blocks) +------------------------- + +Looping through arrays of data in Smarty is relatively simple, using the +{section} function. Two attributes are required: name and loop. name is the name +of the section, and loop is the name of the array that determines the number of +times the section will loop. + +--------- index.php -------- +assign("FirstName",array("Fred","Bart","Montgomery")); +$smarty->assign("LastName",array("Flanders","Simpson","Burns")); +$smarty->display("./templates/index.tpl"); +?> + +--------- templates/index.tpl -------- +{include file="header.tpl" title="Home Page"} + {section name=people loop=$FirstName} + {%people.rownum%} {$people/FirstName} {$people/LastName}
+ {sectionelse} + There are no values to loop through. + {/section} +

+ There were {%people.loop%} names in this list. +{include file="footer.tpl"} + + +Notice that when printing variables inside of the section, the section name must +be referenced in the name of the variable being displayed. This lets Smarty +understand that you want to print the value in the array postion indexed by the +current loop value. There are also internal template variables available within +the section that display the loop iteration and the total number of times the +section is looped. Also note the {sectionelse}. This would have been displayed +had the loop array $FirstName been empty. + +You can also do complex nested sections, like so: + +--------- index.php -------- +assign("FirstName",array("Fred","Bart","Montgomery")); +$smarty->assign("LastName",array("Flanders","Simpson","Burns")); +$smarty->assign("ContactNames",array( + array("email","home","cell"), + array("email","home"), + array("email","home","fax") + )); +$smarty->assign("ContactVals",array( + array("fred@simpsons.com","555-666-7777","555-444-3333"), + array("bart@simpsons.com","555-111-2222"), + array("monty@simpsons.com","555-888-9999","555-234-5678"), + )); + +$smarty->display("./templates/index.tpl"); +?> + +--------- templates/index.tpl -------- +{include file="header.tpl" title="Home Page"} + {section name=people loop=$FirstName} + {%people.rownum%} {$people/FirstName} {$people/LastName}
+ {section name=contacts loop=$people/ContactNames} + {* for fun, lets bold every other row *} + {if %contacts.rownum% is even}{/if} + {$people/contacts/ContactNames}: {$people/contacts/ContactVals}
+ {if %contacts.rownum% is even}{/if} + {/section} +
+ {sectionelse} + There are no values to loop through. + {/section} +

+ There were {%people.loop%} names in this list. +{include file="footer.tpl"} + + +This should be enough to get your feet wet. Also check out config file +variables, built-in functions, custom functions, variable modifiers, all sorts +of good stuff. Now go read the documentation, and Good Luck! diff --git a/doc.sgm b/doc.sgm index 316f7562..bb225c1d 100644 --- a/doc.sgm +++ b/doc.sgm @@ -1521,6 +1521,14 @@ OUTPUT: 24.02 +{* print "Home Page" if $title is empty *} +{$title|default:"Home Page"} + +OUTPUT: + +Home Page + + @@ -1631,6 +1639,14 @@ is the first week that has at least 4 days in the current year, and with Monday + + default + + 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, the value to use as the default value. + + escape