From 3d6624628287d1b6250eed9db7e6bf4e9095badc Mon Sep 17 00:00:00 2001 From: pete_morgan Date: Mon, 9 Oct 2006 22:07:53 +0000 Subject: [PATCH] Tidied up formatting so more readable, tidied up the install to the paths are more clear (ta jj) --- docs/en/getting-started.xml | 439 +++++++++++++++++++++--------------- 1 file changed, 261 insertions(+), 178 deletions(-) diff --git a/docs/en/getting-started.xml b/docs/en/getting-started.xml index 62bdecb7..32ded647 100644 --- a/docs/en/getting-started.xml +++ b/docs/en/getting-started.xml @@ -12,46 +12,88 @@ programmer and the template designer play different roles, or in most cases are not the same person. + For example, let's say you are creating a web page that is displaying a - newspaper article. The article headline, tagline, author and body are + newspaper article. + + + + The article $headline, $tagline, + $author and $body are content elements, they contain no information about how they will be - presented. They are passed into Smarty by the application, then the + presented. They are passed into Smarty + by the application. + + + Then the template designer edits the templates and uses a combination of - HTML tags and template tags to format the presentation of these elements - (HTML tables, background colors, font sizes, style sheets, etc.) One day - the programmer needs to change the way the article content is retrieved (a - change in application logic.) This change does not affect the template + HTML tags and template tags + to format the presentation of these + variables with elements + such as tables, div's, background colors, font sizes, style sheets, svg etc. + + + One day + the programmer needs to change the way the article content is retrieved, ie a + change in application logic. This change does not affect the template designer, the content will still arrive in the template exactly the same. + + + Likewise, if the template designer wants to completely redesign the - templates, this requires no changes to the application logic. Therefore, + templates, this would require no change to the application logic. + + + Therefore, the programmer can make changes to the application logic without the need to restructure templates, and the template designer can make changes to templates without breaking application logic. - + + + One design goal of Smarty is the separation of business logic and - presentation logic. This means templates can certainly contain logic under - the condition that it is for presentation only. Things such as including - other templates, altering table row colors, upper-casing a variable, - looping over an array of data and displaying it, etc. are all examples of - presentation logic. This does not mean that Smarty forces a separation of + presentation logic. + + + + + This means templates can certainly contain logic under + the condition that it is for presentation only. Things such as + including + other templates, + alternating table row colors, + upper-casing a variable, + looping + over an array of data and displaying it + are examples of presentation logic. + + + This does not mean however that Smarty forces a separation of business and presentation logic. Smarty has no knowledge of which is which, - so placing business logic in the template is your own doing. Also, if you + so placing business logic in the template is your own doing. + + Also, if you desire no logic in your templates you certainly can do so by boiling the content down to text and variables only. - + + + One of the unique aspects about Smarty is the template compiling. This means Smarty reads the template files and creates PHP scripts from them. Once they are created, they are executed from then on. Therefore there is - no costly template file parsing for each request, and each template can - take full advantage of PHP compiler cache solutions such as Zend - Accelerator (&url.zend;) or PHP Accelerator - (&url.php-accelerator;). + no costly template file parsing for each request. Each template can + take full advantage of PHP compiler and cache solutions such as + eAccelerator, + ionCube + mmCache + or Zend Accelerator + to name a few. - Some of Smarty's features: + Some of Smarty's features: @@ -71,40 +113,40 @@ - It is smart about recompiling only the template files that have changed. + It is smart about recompiling + only the template files that have changed. - You can make custom functions - and custom variable modifiers, so the + You can easily create your own custom functions + and variable modifiers, so the template language is extremely extensible. Configurable template - delimiter tag + {delimiter} tag syntax, so you can use - {}, {{}}, <!--{}-->, etc. + {$foo}, {{$foo}}, + <!--{$foo}-->, etc. - The if/elseif/else/endif + The + {if}..{elseif}..{else}..{/if} constructs are passed to the - PHP parser, so the {if ...} expression syntax can be as simple or as - complex as you like. + PHP parser, so the {if...} expression syntax can be as + simple or as complex an evaluation as you like. - Unlimited nesting of - sections, - ifs, etc. allowed. + Allows unlimited nesting of + sections, if's etc. @@ -113,7 +155,7 @@ embed PHP code right in your template files, although this may not be needed (nor recommended) since the engine is so - customizable. + customizable. @@ -123,8 +165,7 @@ - Arbitrary template sources + Arbitrary template sources @@ -143,58 +184,77 @@ + + + Installation Requirements - Smarty requires a web server running PHP 4.0.6 or later. + Smarty requires a web server running PHP 4.0.6 or greater. Basic Installation + - Install the Smarty library files which are in the /libs/ - sub directory of - the distribution. These are PHP files that you SHOULD NOT edit. They - are shared among all applications and they only get updated when you - upgrade to a new version of Smarty. + Install the Smarty library files which are in the + /libs/ sub directory of + the distribution. These are .php files that you + SHOULD NOT edit. They are shared among all applications and only get + changed when you upgrade to a new version of Smarty. + In the examples below the Smarty tarball has been unpacked to: + + + /usr/local/lib/Smarty-v.e.r/ for *nix + machines + and + c:\webroot\libs\Smarty-v.e.r\ for the + windows enviroment. + + + Required Smarty library files + - Smarty uses a PHP constant named - SMARTY_DIR which is the - full system file path to the Smarty - libs/ directory. - Basically, if your application - can find the Smarty.class.php file, you do not need - to set SMARTY_DIR - as Smarty will figure it out on its own. Therefore, if - Smarty.class.php is not in your include_path, or you - do not supply an absolute path to it in your application, then you must - define SMARTY_DIR manually. + Smarty uses a PHP constant + named SMARTY_DIR + which is the full system file path + to the Smarty libs/ directory. + Basically, if your application can find the + Smarty.class.php file, you do not need to set the + SMARTY_DIR + as Smarty will figure it out on its own. + Therefore, if + Smarty.class.php is not in your + include_path, + or you do not supply an absolute path to it in your application, + then you must define SMARTY_DIR manually. SMARTY_DIR must include a trailing slash/. - - Create an instance of Smarty - + + Here's how you create an instance of Smarty in your PHP scripts: @@ -206,11 +266,11 @@ $smarty = new Smarty(); ?> ]]> - + Try running the above script. If you get an error saying the - Smarty.class.php file could not be found, you have to + Smarty.class.php file could not be found, you need to do one of the following: @@ -220,7 +280,7 @@ $smarty = new Smarty(); - Add library directory to PHP include_path + Add the library path to the <filename>php.ini</filename> file + + + + + + + Appending the include path in a php script with + <literal><ulink url="&url.e-accel;">ini_set()</ulink></literal> ]]> - - Now that the library files are in place, it's time to setup the Smarty - directories for your application. - + directories for your application: + + + Smarty requires four directories which - are by default named 'templates/', - 'templates_c/', 'configs/' and 'cache/'. - - Each of these are definable by the + are by default named templates/, + templates_c/, configs/ and cache/ + + + Each of these are definable by the Smarty class properties $template_dir, @@ -289,103 +368,97 @@ $smarty = new Smarty(); $config_dir, and - $cache_dir respectively. + $cache_dir respectively + + + It is highly recommended that you setup a separate set of these directories for each application - that will use Smarty. - - - Be sure you know the location of your web server document root. In our - examples, the document root is /web/www.example.com/docs/. The Smarty - directories are only accessed by the Smarty library and never accessed - directly by the web browser. Therefore to avoid any security concerns, it - is recommended to place these directories outside of - the document root. - - + that will use Smarty + + + + For our installation example, we will be setting up the Smarty environment for a guest book application. We picked an application only for the purpose of a directory naming convention. You can use the same environment for any - application, just replace guestbook with the name of your app. - We'll place our Smarty directories under - /web/www.example.com/smarty/guestbook/. - - - You will need as least one file under your document root, and that is the - script accessed by the web browser. We will call our script - index.php, and place it in a subdirectory under the - document root called /guestbook/. - + application, just replace guestbook/ with + the name of your application. + - - Technical Note - - It is convenient to setup the web server so that index.php - can be identified as the default directory index, so if you access - http://www.example.com/guestbook/, the index.php - script will be executed without adding index.php to - the URL. In Apache you can set this up by adding - index.php onto the end of your - DirectoryIndex setting (separate - each entry with a space) as in the following httpd.conf example. - - - - - - - - - - Lets take a look at the file structure so far: - - File structure so far + What the file structure looks like + + Be sure that you know the location of your web server's document root as a + file path. In the following examples, the document root is /web/www.example.com/guestbook/htdocs/. + The Smarty + directories are only accessed by the Smarty library and never accessed + directly by the web browser. Therefore to avoid any security concerns, it + is recommended (but not mandatory) to place these directories + outside of the web server's document root. + + + + You will need as least one file under your document root, and that is the + script accessed by the web browser. We will name our script + index.php, and place it in a subdirectory under the + document root /htdocs/. + + + Smarty will need write access (windows users please ignore) to the $compile_dir and - $cache_dir, - so be sure the web server user can write - to them. This is usually user "nobody" and group "nobody". For OS X users, - the default is user "www" and group "www". If you are using Apache, you can - look in your httpd.conf file to see - what user and group are being used. - + $cache_dir directories + (templates_c/ and + cache/), so be sure the web server + user account can write to them. + + This is usually user nobody and + group nobody. For OS X users, + the default is user www and group www. + If you are using Apache, you can look in your + httpd.conf file to see + what user and group are being used. + - Setting file permissions + Permissions and making directories writable @@ -393,21 +466,22 @@ chmod 770 /web/www.example.com/smarty/guestbook/cache/ Note - chmod 770 will be fairly tight security, it only allows user "nobody" and - group "nobody" read/write access to the directories. If you would like to - open up read access to anyone (mostly for your own convenience of viewing - these files), you can use 775 instead. + chmod 770 will be fairly tight security, it only allows + user nobody and group nobody read/write access + to the directories. If you would like to open up read access to anyone + (mostly for your own convenience of viewing + these files), you can use 775 instead. We need to create the index.tpl file that Smarty will - load. This needs to be located in the + display. This needs to be located in the $template_dir. - Our /web/www.example.com/smarty/guestbook/templates/index.tpl + /web/www.example.com/guestbook/templates/index.tpl template_dir = '/web/www.example.com/smarty/guestbook/templates/'; -$smarty->compile_dir = '/web/www.example.com/smarty/guestbook/templates_c/'; -$smarty->config_dir = '/web/www.example.com/smarty/guestbook/configs/'; -$smarty->cache_dir = '/web/www.example.com/smarty/guestbook/cache/'; +$smarty->template_dir = '/web/www.example.com/guestbook/templates/'; +$smarty->compile_dir = '/web/www.example.com/guestbook/templates_c/'; +$smarty->config_dir = '/web/www.example.com/guestbook/configs/'; +$smarty->cache_dir = '/web/www.example.com/guestbook/cache/'; $smarty->assign('name','Ned'); $smarty->display('index.tpl'); + ?> ]]> - Technical Note + Note In our example, we are setting absolute paths to all of the Smarty directories. If /web/www.example.com/smarty/guestbook/ is + class="directory">/web/www.example.com/guestbook/ is within your PHP include_path, then these settings are not necessary. However, it is more efficient and (from experience) less error-prone to set them to absolute paths. This ensures that Smarty is getting files @@ -476,7 +550,7 @@ $smarty->display('index.tpl'); Now naviagate to the index.php file with the web browser. - You should see "Hello Ned, welcome to Smarty!" + You should see "Hello Ned, welcome to Smarty!" You have completed the basic setup for Smarty! @@ -484,6 +558,9 @@ $smarty->display('index.tpl'); + + + Extended Setup @@ -493,17 +570,22 @@ $smarty->display('index.tpl'); that first! - A slightly more flexible way to setup Smarty is to extend the class and + A slightly more flexible way to setup Smarty is to + extend the class and initialize your Smarty environment. So instead of repeatedly setting directory paths, assigning the same vars, etc., we can do that in one place. - Lets create a new directory /php/includes/guestbook/ + + + Lets create a new directory /php/includes/guestbook/ and make a new file called setup.php. In our example - environment, /php/includes is in our include_path. + environment, /php/includes is in our + include_path. Be sure you set this up too, or use absolute file paths. - Editing /php/includes/guestbook/setup.php + /php/includes/guestbook/setup.php Smarty(); - $this->template_dir = '/web/www.example.com/smarty/guestbook/templates/'; - $this->compile_dir = '/web/www.example.com/smarty/guestbook/templates_c/'; - $this->config_dir = '/web/www.example.com/smarty/guestbook/configs/'; - $this->cache_dir = '/web/www.example.com/smarty/guestbook/cache/'; + $this->template_dir = '/web/www.example.com/guestbook/templates/'; + $this->compile_dir = '/web/www.example.com/guestbook/templates_c/'; + $this->config_dir = '/web/www.example.com/guestbook/configs/'; + $this->cache_dir = '/web/www.example.com/guestbook/cache/'; $this->caching = true; $this->assign('app_name', 'Guest Book'); @@ -542,11 +624,12 @@ class Smarty_GuestBook extends Smarty { - Now lets alter the index.php file to use setup.php: + Now lets alter the index.php file to use + setup.php: - Editing /web/www.example.com/docs/guestbook/index.php + /web/www.example.com/guestbook/htdocs/index.php