From d8b24f8e2ecfc6de9ebd3b174ad93bc47b9c20f5 Mon Sep 17 00:00:00 2001 From: nlopess Date: Tue, 23 Mar 2004 18:25:47 +0000 Subject: [PATCH] remove this one too --- docs/getting-started.sgml | 518 -------------------------------------- 1 file changed, 518 deletions(-) delete mode 100644 docs/getting-started.sgml diff --git a/docs/getting-started.sgml b/docs/getting-started.sgml deleted file mode 100644 index 5b2de5c1..00000000 --- a/docs/getting-started.sgml +++ /dev/null @@ -1,518 +0,0 @@ - - Getting Started - - - What is Smarty? - - Smarty is a template engine for PHP. More specifically, it facilitates a - manageable way to separate application logic and content from its - presentation. This is best described in a situation where the application - 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 content elements, they contain no information about how - they will be 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 - 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, - 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 - 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 - 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 compling. 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 - (http://www.zend.com) or PHP Accelerator - (http://www.php-accelerator.co.uk). - - - Some of Smarty's features: - - - - - It is extremely fast. - - - - - It is efficient 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 - {}, {{}}, <!--{}-->, etc. - - - - - The if/elseif/else/endif constructs are passed to the - PHP parser, so the {if ...} expression syntax can be as simple or as complex - as you like. - - - - - Unlimited nesting of sections, ifs, etc. allowed. - - - - - It is possible to embed PHP code right in your template files, - although this may not be needed (nor recommended) - since the engine is so customizable. - - - - - Built-in caching support - - - - - Arbitrary template sources - - - - - Custom cache handling functions - - - - - Plugin architecture - - - - - - Installation - - - Requirements - - Smarty requires a web server running PHP 4.0.6 or later. - - - - - Basic Installation - - Install the Smarty library files which are in the /libs/ directory of - the distribution. These are the 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. - - - Smarty library files - - - - - - Smarty uses a PHP constant named SMARTY_DIR which is the system - filepath Smarty library directory. Basically, if your application can find - the Smarty.class.php file, you do not need to set - SMARTY_DIR, 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. - - - Here is how you create an instance of Smarty in your PHP scripts: - - - - Create Smarty instance of Smarty - - -]]> - - - - - Try running the above script. If you get an error saying the - Smarty.class.php file could not be found, you have to - do one of the following: - - - - Supply absolute path to library file - - -]]> - - - - - Add library directory to php_include path - - -]]> - - - - - Set SMARTY_DIR constant manually - - -]]> - - - - - Now that the library files are in place, it's time to setup the Smarty - 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 Smarty class - properties $template_dir, - $compile_dir, $config_dir, and - $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 - example, the document root is "/web/www.mydomain.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. - - - 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.mydomain.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/". - - - - 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.mydomain.com/guestbook/", the index.php script will be executed - without "index.php" in 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.) - - - - - Lets take a look at the file structure so far: - - - - Example file structure - - - - - - - Smarty will need write access 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 (usually in "/usr/local/apache/conf/") to see - what user and group are being used. - - - - Setting file permissions - - - - - - - Technical 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. - - - - - We need to create the index.tpl file that Smarty will load. This will be - located in your $template_dir. - - - - Editing /web/www.mydomain.com/smarty/guestbook/templates/index.tpl - - - - - - - Technical Note - - {* Smarty *} is a template comment. It is not required, but it is good - practice to start all your template files with this comment. It makes - the file easy to recognize regardless of the file extension. For - example, text editors could recognize the file and turn on special - syntax highlighting. - - - - - Now lets edit index.php. We'll create an instance of Smarty, assign a - template variable and display the index.tpl file. In our example - environment, "/usr/local/lib/php/Smarty" is in our include_path. Be sure you - do the same, or use absolute paths. - - - - Editing /web/www.mydomain.com/docs/guestbook/index.php - -template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/'; -$smarty->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/'; -$smarty->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/'; -$smarty->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/'; - -$smarty->assign('name','Ned'); - -$smarty->display('index.tpl'); -?> -]]> - - - - - Technical Note - - In our example, we are setting absolute paths to all of the Smarty - directories. If '/web/www.mydomain.com/smarty/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 from the - directories you intended. - - - - - Now load the index.php file from your web browser. You should see "Hello, - Ned!" - - - You have completed the basic setup for Smarty! - - - - Extended Setup - - - This is a continuation of the basic installation, please read - that first! - - - 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/" and make a new file - called "setup.php". In our example 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 - -Smarty(); - - $this->template_dir = '/web/www.mydomain.com/smarty/guestbook/templates/'; - $this->compile_dir = '/web/www.mydomain.com/smarty/guestbook/templates_c/'; - $this->config_dir = '/web/www.mydomain.com/smarty/guestbook/configs/'; - $this->cache_dir = '/web/www.mydomain.com/smarty/guestbook/cache/'; - - $this->caching = true; - $this->assign('app_name','Guest Book'); - } - -} -?> -]]> - - - - - Now lets alter the index.php file to use setup.php: - - - - Editing /web/www.mydomain.com/docs/guestbook/index.php - -assign('name','Ned'); - -$smarty->display('index.tpl'); -?> -]]> - - - - - Now you see it is quite simple to bring up an instance of Smarty, just use - Smarty_GuestBook which automatically initializes everything for our application. - - - - - - - -