diff --git a/README.md b/README.md index b8991e7a..404ef673 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,4 @@ To get the latest stable version of Smarty use: composer require smarty/smarty ```` -To get the latest, unreleased version, use: -```bash -composer require smarty/smarty:dev-master -```` - -To get the previous stable version of Smarty, Smarty 3, use: -```bash -composer require smarty/smarty:^3 -```` +More in the [Getting Started](./docs/getting-started.md) section of the docs. diff --git a/docs/designers/language-basic-syntax.md b/docs/designers/language-basic-syntax.md index 18512659..2509857c 100644 --- a/docs/designers/language-basic-syntax.md +++ b/docs/designers/language-basic-syntax.md @@ -1,6 +1,18 @@ Basic Syntax ============ +A simple Smarty template could look like this: +```html +

{$title|escape}

+ +``` + All Smarty template tags are enclosed within delimiters. By default these are `{` and `}`, but they can be [changed](../programmers/api-variables/variable-left-delimiter.md). @@ -11,6 +23,7 @@ displayed as static content, or unchanged. When Smarty encounters template tags, it attempts to interpret them, and displays the appropriate output in their place. +The basis components of the Smarty syntax are: - [Comments](./language-basic-syntax/language-syntax-comments.md) - [Variables](./language-basic-syntax/language-syntax-variables.md) - [Functions](./language-basic-syntax/language-syntax-functions.md) diff --git a/docs/designers/language-builtin-functions.md b/docs/designers/language-builtin-functions.md index ac258c07..6c0879d6 100644 --- a/docs/designers/language-builtin-functions.md +++ b/docs/designers/language-builtin-functions.md @@ -21,7 +21,6 @@ Built-in Functions {#language.builtin.functions} - [{ldelim},{rdelim}](./language-builtin-functions/language-function-ldelim.md) - [{literal}](./language-builtin-functions/language-function-literal.md) - [{nocache}](./language-builtin-functions/language-function-nocache.md) -- [{php}](./language-builtin-functions/language-function-php.md) - [{section},{sectionelse}](./language-builtin-functions/language-function-section.md) - [{setfilter}](./language-builtin-functions/language-function-setfilter.md) - [{strip}](./language-builtin-functions/language-function-strip.md) diff --git a/docs/designers/language-builtin-functions/language-function-php.md b/docs/designers/language-builtin-functions/language-function-php.md deleted file mode 100644 index 5b2b3f5c..00000000 --- a/docs/designers/language-builtin-functions/language-function-php.md +++ /dev/null @@ -1,45 +0,0 @@ -{php} {#language.function.php} -===== - -> **Note** -> -> `{php}` tags are deprecated from Smarty, and should not be used. Put -> your PHP logic in PHP scripts or plugin functions instead. - -> **Note** -> -> As of Smarty 3.1 the `{php}` tags are only available from -> [SmartyBC](#bc). - -The `{php}` tags allow PHP code to be embedded directly into the -template. They will not be escaped, regardless of the -[`$php_handling`](#variable.php.handling) setting. - - - {php} - // including a php script directly from the template. - include('/path/to/display_weather.php'); - {/php} - - - - - {* this template includes a {php} block that assign's the variable $varX *} - {php} - global $foo, $bar; - if($foo == $bar){ - echo 'This will be sent to browser'; - } - // assign a variable to Smarty - $this->assign('varX','Toffee'); - {/php} - {* output the variable *} - {$varX} is my fav ice cream :-) - - - -See also [`$php_handling`](#variable.php.handling), -[`{include_php}`](#language.function.include.php), -[`{include}`](#language.function.include), -[`{insert}`](#language.function.insert) and [componentized -templates](#tips.componentized.templates). diff --git a/docs/features.md b/docs/features.md new file mode 100644 index 00000000..0c9fee81 --- /dev/null +++ b/docs/features.md @@ -0,0 +1,152 @@ +Features +======= + +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](#variable.compile.check) only the + template files that have changed. +- You can easily create your own custom + [functions](#language.custom.functions) and [variable + modifiers](#language.modifiers), so the template language is + extremely extensible. +- Configurable template [{delimiter}](#variable.left.delimiter) tag + syntax, so you can use `{$foo}`, `{{$foo}}`, ``, etc. +- The [`{if}..{elseif}..{else}..{/if}`](#language.function.if) + constructs are passed to the PHP parser, so the `{if...}` expression + syntax can be as simple or as complex an evaluation as you like. +- Allows unlimited nesting of + [`sections`](#language.function.section), `if's` etc. +- Built-in [caching](#caching) support +- Arbitrary [template](#resources) sources +- [Template Inheritance](#advanced.features.template.inheritance) for + easy management of template content. +- [Plugin](#plugins) architecture + +## Seperation of presentation from application code +- This means templates can certainly contain logic under the condition + that it is for presentation only. Things such as + [including](./designers/language-builtin-functions/language-function-include.md) other templates, + [alternating](./designers/language-custom-functions/language-function-cycle.md) table row colors, + [upper-casing](./designers/language-modifiers/language-modifier-upper.md) a variable, + [looping](./designers/language-builtin-functions/language-function-foreach.md) over an array of data and + rendering 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 desire *no* logic in your templates you certainly can + do so by boiling the content down to text and variables only. + +## How does it work? + +Under the hood, Smarty "compiles" (basically copies and converts) the +templates into PHP scripts. This happens once when each template is +first invoked, and then the compiled versions are used from that point +forward. Smarty takes care of this for you, so the template designer +just edits the Smarty templates and never has to manage the compiled +versions. This approach keeps the templates easy to maintain, and yet +keeps execution times extremely fast since the compiled code is just +PHP. And of course, all PHP scripts take advantage of PHP op-code caches +such as APC. + +## Template Inheritance + +Template inheritance was introduced in Smarty 3. Before template +inheritance, we managed our templates in +pieces such as header and footer templates. This organization lends +itself to many problems that require some hoop-jumping, such as managing +content within the header/footer on a per-page basis. With template +inheritance, instead of including other templates we maintain our +templates as single pages. We can then manipulate blocks of content +within by inheriting them. This makes templates intuitive, efficient and +easy to manage. See +[Template Inheritance](./programmers/advanced-features/advanced-features-template-inheritance.md) +for more info. + +## Why not use XML/XSLT syntax? +There are a couple of good reasons. First, Smarty can be used for more +than just XML/HTML based templates, such as generating emails, +javascript, CSV, and PDF documents. Second, XML/XSLT syntax is even more +verbose and fragile than PHP code! It is perfect for computers, but +horrible for humans. Smarty is about being easy to read, understand and +maintain. + +## Template Security +Although Smarty insulates you from PHP, you still have the option to use +it in certain ways if you wish. Template security forces the restriction +of PHP (and select Smarty functions.) This is useful if you have third +parties editing templates, and you don't want to unleash the full power +of PHP or Smarty to them. + +## Integration +Sometimes Smarty gets compared to Model-View-Controller (MVC) +frameworks. Smarty is not an MVC, it is just the presentation layer, +much like the View (V) part of an MVC. As a matter of fact, Smarty can +easily be integrated as the view layer of an MVC. Many of the more +popular ones have integration instructions for Smarty, or you may find +some help here in the forums and documentation. + +## Other Template Engines +Smarty is not the only engine following the *"Separate Programming Code +from Presentation"* philosophy. For instance, Python has template +engines built around the same principles such as Django Templates and +CheetahTemplate. *Note: Languages such as Python do not mix with HTML +natively, which give them the advantage of proper programming code +separation from the outset. There are libraries available to mix Python +with HTML, but they are typically avoided.* + +## What Smarty is Not + +Smarty is not an application development framework. Smarty is not an +MVC. Smarty is not an alternative to Laravel, Symfony, CodeIgniter, +or any of the other application development frameworks for PHP. + +Smarty is a template engine, and works as the (V)iew component of your +application. Smarty can easily be coupled to any of the engines listed +above as the view component. No different than any other software, +Smarty has a learning curve. Smarty does not guarantee good application +design or proper separation of presentation, this still needs to be +addressed by a competent developer and web designer. + +## Is Smarty Right for Me? + +Smarty is not meant to be a tool for every job. The important thing is +to identify if Smarty fits your needs. There are some important +questions to ask yourself: + +### Template Syntax +Are you content with PHP tags mixed with HTML? Are your +web designers comfortable with PHP? Would your web designers prefer a +tag-based syntax designed for presentation? Some experience working with +both Smarty and PHP helps answer these questions. + +### The Business Case +Is there a requirement to insulate the templates from +PHP? Do you have untrusted parties editing templates that you do not +wish to unleash the power of PHP to? Do you need to programmatically +control what is and is not available within the templates? Smarty +supplies these capabilities by design. + +## Feature set +Does Smarty's features such as caching, template +inheritance and plugin architecture save development cycles writing code +that would be needed otherwise? Does the codebase or framework you plan +on using have the features you need for the presentation component? + +## Sites using Smarty +Many well-known PHP projects make use of Smarty such as XOOPS CMS, CMS Made Simple, Tiki +CMS/Groupware and X-Cart to name a few. + +## Summary +Whether you are using Smarty for a small website or massive enterprise +solution, it can accommodate your needs. There are numerous features +that make Smarty a great choice: + +- separation of PHP from HTML/CSS just makes sense +- readability for organization and management +- security for 3rd party template access +- feature completeness, and easily extendable to your own needs +- massive user base, Smarty is here to stay +- LGPL license for commercial use +- 100% free to use, open source project diff --git a/docs/getting-started.md b/docs/getting-started.md index 0d594a46..cd21b96a 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,267 +1,56 @@ 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](#api.assign) into Smarty by the - application. - -- Then the template designer edits the templates and uses a - combination of HTML tags and [template tags](#language.basic.syntax) - to format the presentation of these - [variables](#language.syntax.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 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](#language.function.include) other templates, - [alternating](#language.function.cycle) table row colors, - [upper-casing](#language.modifier.upper) a variable, - [looping](#language.function.foreach) over an array of data and - [displaying](#api.display) 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 desire *no* logic in your templates you certainly can - do so by boiling the content down to text and variables only. - -**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](#variable.compile.check) only the - template files that have changed. - -- You can easily create your own custom - [functions](#language.custom.functions) and [variable - modifiers](#language.modifiers), so the template language is - extremely extensible. - -- Configurable template [{delimiter}](#variable.left.delimiter) tag - syntax, so you can use `{$foo}`, `{{$foo}}`, ``, etc. - -- The [`{if}..{elseif}..{else}..{/if}`](#language.function.if) - constructs are passed to the PHP parser, so the `{if...}` expression - syntax can be as simple or as complex an evaluation as you like. - -- Allows unlimited nesting of - [`sections`](#language.function.section), `if's` etc. - -- Built-in [caching](#caching) support - -- Arbitrary [template](#resources) sources - -- [Template Inheritance](#advanced.features.template.inheritance) for - easy management of template content. - -- [Plugin](#plugins) architecture - -Installation -============ - -Requirements {#installation.requirements} -============ - -Smarty requires a web server running PHP 5.2 or greater. - -Basic Installation {#installing.smarty.basic} -================== - -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 environment. - - - - - Smarty-v.e.r/ - libs/ - Smarty.class.php - debug.tpl - sysplugins/* (everything) - plugins/* (everything) - - - -Smarty uses a PHP [constant](&url.php-manual;define) named -[`SMARTY_DIR`](#constant.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`](#constant.smarty.dir) as Smarty will figure it out on its -own. Therefore, if `Smarty.class.php` is not in your -[include\_path](&url.php-manual;ini.core.php#ini.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/**. - -::: {.informalexample} -Here\'s how you create an instance of Smarty in your PHP scripts: - - - - - -::: - -Try running the above script. If you get an error saying the -`Smarty.class.php` file could not be found, you need to do one of the -following: - - - - - - - - - - - - - ;;;;;;;;;;;;;;;;;;;;;;;;; - ; Paths and Directories ; - ;;;;;;;;;;;;;;;;;;;;;;;;; - - ; *nix: "/path1:/path2" - include_path = ".:/usr/share/php:/usr/local/lib/Smarty-v.e.r/libs/" - - ; Windows: "\path1;\path2" - include_path = ".;c:\php\includes;c:\webroot\libs\Smarty-v.e.r\libs\" - - - - - - -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`](#variable.template.dir), - [`$compile_dir`](#variable.compile.dir), - [`$config_dir`](#variable.config.dir), and - [`$cache_dir`](#variable.cache.dir) respectively - -- It is highly recommended that you setup a separate set of these - directories for each application that will use Smarty - -- You can verify if your system has the correct access rights for - these directories with [`testInstall()`](#api.test.install). - -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 application. - - - /usr/local/lib/Smarty-v.e.r/libs/ - Smarty.class.php - debug.tpl - sysplugins/* - plugins/* - - /web/www.example.com/ - guestbook/ - templates/ - index.tpl - templates_c/ - configs/ - cache/ - htdocs/ - index.php - - - -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`](#variable.compile.dir) and -[`$cache_dir`](#variable.cache.dir) directories (`templates_c/` and -`cache/`), so be sure the web server user account can write to them. +============== + +## Requirements +Smarty can be run with PHP 7.1 to PHP 8.0. + +## Installation +Smarty versions 3.1.11 or later can be installed with [Composer](https://getcomposer.org/). + +To get the latest stable version of Smarty use: +```bash +composer require smarty/smarty +```` + +To get the latest, unreleased version, use: +```bash +composer require smarty/smarty:dev-master +```` + +To get the previous stable version of Smarty, Smarty 3, use: +```bash +composer require smarty/smarty:^3 +```` + +Here's how you create an instance of Smarty in your PHP scripts: +```php +setTemplateDir('/some/template/dir'); +$smarty->setConfigDir('/some/config/dir'); +$smarty->setCompileDir('/some/compile/dir'); +$smarty->setCacheDir('/some/cache/dir'); +``` + +The compile dir and cache dir need to be writable for the user running the PHP script. > **Note** > @@ -270,66 +59,62 @@ Smarty will need **write access** (windows users please ignore) to the > can look in your `httpd.conf` file to see what user and group are > being used. +```bash +chown nobody:nobody /web/www.example.com/guestbook/templates_c/ +chmod 770 /web/www.example.com/guestbook/templates_c/ - chown nobody:nobody /web/www.example.com/guestbook/templates_c/ - chmod 770 /web/www.example.com/guestbook/templates_c/ +chown nobody:nobody /web/www.example.com/guestbook/cache/ +chmod 770 /web/www.example.com/guestbook/cache/ +``` - chown nobody:nobody /web/www.example.com/guestbook/cache/ - chmod 770 /web/www.example.com/guestbook/cache/ +You can verify if your system has the correct access rights for + these directories with [`testInstall()`](./programmers/api-functions/api-test-install.md): - +```php +$smarty = new Smarty(); +$smarty->setTemplateDir('/some/template/dir'); +$smarty->setConfigDir('/some/config/dir'); +$smarty->setCompileDir('/some/compile/dir'); +$smarty->setCacheDir('/some/cache/dir'); +$smarty->testInstall(); +``` + +Now, let's create the `index.tpl` file that Smarty will display. This +needs to be located in the [`$template_dir`](./programmers/api-variables/variable-template-dir.md). + +```html +{* Smarty *} +Hello {$name}, welcome to Smarty! +``` > **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 display. This -needs to be located in the [`$template_dir`](#variable.template.dir). - - - {* Smarty *} - - Hello {$name}, welcome to Smarty! - - - -> **Note** -> -> `{* Smarty *}` is a template [comment](#language.syntax.comments). It +> `{* Smarty *}` is a template [comment](./designers/language-basic-syntax/language-syntax-comments.md). 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()`](#api.assign) a template variable and -[`display()`](#api.display) the `index.tpl` file. +Now lets edit our php file. We'll create an instance of Smarty, +[`assign()`](./programmers/api-functions/api-assign.md) a template variable and +[`display()`](./programmers/api-functions/api-display.md) the `index.tpl` file. +```php +setTemplateDir('/web/www.example.com/guestbook/templates/'); +$smarty->setCompileDir('/web/www.example.com/guestbook/templates_c/'); +$smarty->setConfigDir('/web/www.example.com/guestbook/configs/'); +$smarty->setCacheDir('/web/www.example.com/guestbook/cache/'); - $smarty->setTemplateDir('/web/www.example.com/guestbook/templates/'); - $smarty->setCompileDir('/web/www.example.com/guestbook/templates_c/'); - $smarty->setConfigDir('/web/www.example.com/guestbook/configs/'); - $smarty->setCacheDir('/web/www.example.com/guestbook/cache/'); +$smarty->assign('name', 'Ned'); +$smarty->display('index.tpl'); - $smarty->assign('name','Ned'); - - //** un-comment the following line to show the debug console - //$smarty->debugging = true; - - $smarty->display('index.tpl'); - - ?> - - +``` > **Note** > @@ -340,78 +125,45 @@ Now lets edit `index.php`. We\'ll create an instance of Smarty, > absolute paths. This ensures that Smarty is getting files from the > directories you intended. -Now navigate to the `index.php` file with the web browser. You should -see *\"Hello Ned, welcome to Smarty!\"* +Now, run your PHP file. You should see *\"Hello Ned, welcome to Smarty!\"* You have completed the basic setup for Smarty! -Extended Setup {#installing.smarty.extended} +## Extended Setup {#installing.smarty.extended} ============== This is a continuation of the [basic installation](#installing.smarty.basic), please read that first! -A slightly more flexible way to setup Smarty is to [extend the -class](&url.php-manual;ref.classobj) and initialize your Smarty +A slightly more flexible way to setup Smarty is to extend the Smarty +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. +```php +setTemplateDir('/web/www.example.com/guestbook/templates/'); + $this->setCompileDir('/web/www.example.com/guestbook/templates_c/'); + $this->setConfigDir('/web/www.example.com/guestbook/configs/'); + $this->setCacheDir('/web/www.example.com/guestbook/cache/'); - // The setup.php file is a good place to load - // required application library files, and you - // can do that right here. An example: - // require('guestbook/guestbook.lib.php'); + $this->caching = Smarty::CACHING_LIFETIME_CURRENT; + $this->assign('app_name', 'Guest Book'); + } - class Smarty_GuestBook extends Smarty { +} +``` - function __construct() - { - - // Class Constructor. - // These automatically get set with each new instance. - - parent::__construct(); - - $this->setTemplateDir('/web/www.example.com/guestbook/templates/'); - $this->setCompileDir('/web/www.example.com/guestbook/templates_c/'); - $this->setConfigDir('/web/www.example.com/guestbook/configs/'); - $this->setCacheDir('/web/www.example.com/guestbook/cache/'); - - $this->caching = Smarty::CACHING_LIFETIME_CURRENT; - $this->assign('app_name', 'Guest Book'); - } - - } - ?> - - - -Now lets alter the `index.php` file to use `setup.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. +Now, we can use `Smarty_GuestBook` instead of `Smarty` in our scripts: +```php +$smarty = new Smarty_GuestBook(); +$smarty->assign('name','Ned'); +$smarty->display('index.tpl'); +``` diff --git a/docs/index.md b/docs/index.md index 84413cd2..cf2b2ddc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,12 +1,31 @@ # Smarty 4 Documentation - Smarty is a template engine for PHP, facilitating the separation of presentation (HTML/CSS) from application logic. +It allows you to write **templates**, using **variables**, **modifiers**, **functions** and **comments**, like this: +```html +

{$title|escape}

+ +

+ The number of pixels is: {math equation="x * y" x=$height y=$width}. +

+``` + +When this template is rendered, with the value "Hello world" for the variable $title, 640 for $width, +and 480 for $height, the result is: +```html +

Hello world

+ +

+ The number of pixels is: 307200. +

+``` + ## Introduction -- [Preface](./preface.md) +- [Philosophy](./philosophy.md) - or "Why do I need a template engine?" +- [Features](./features.md) - or "Why do I want Smarty?" - [Getting Started](./getting-started.md) -## Smarty for template developers +## Smarty for template designers - [Basic Syntax](./designers/language-basic-syntax.md) - [Variables](./designers/language-variables.md) - [Variable Modifiers](./designers/language-modifiers.md) @@ -27,5 +46,5 @@ Smarty is a template engine for PHP, facilitating the separation of presentation - [Extending Smarty With Plugins](./programmers/plugins.md) ## Other -- Some random [tips & tricks](./appendixes/tips.md) +- [Some random tips & tricks](./appendixes/tips.md) - [Troubleshooting](./appendixes/troubleshooting.md) diff --git a/docs/philosophy.md b/docs/philosophy.md new file mode 100644 index 00000000..86f6c46e --- /dev/null +++ b/docs/philosophy.md @@ -0,0 +1,108 @@ +Philosophy +======= + +## 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](#api.assign) into Smarty by the + application. + +- Then the template designer edits the templates and uses a + combination of HTML tags and [template tags](#language.basic.syntax) + to format the presentation of these + [variables](#language.syntax.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 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. + +## Goals + +The Smarty design was largely driven by these goals: +- clean separation of presentation from application code +- PHP backend, Smarty template frontend +- complement PHP, not replace it +- fast development/deployment for programmers and designers +- quick and easy to maintain +- syntax easy to understand, no PHP knowledge necessary +- flexibility for custom development +- security: insulation from PHP +- free, open source + + + +## Two camps of thought + +When it comes to templating in PHP, there are basically two camps of +thought. The first camp exclaims that \"PHP is a template engine\". This +approach simply mixes PHP code with HTML. Although this approach is +fastest from a pure script-execution point of view, many would argue +that the PHP syntax is messy and complicated when mixed with tagged +markup such as HTML. + +The second camp exclaims that presentation should be void of all +programming code, and instead use simple tags to indicate where +application content is revealed. This approach is common with other +template engines (even in other programming languages), and is also the +approach that Smarty takes. The idea is to keep the templates focused +squarely on presentation, void of application code, and with as little +overhead as possible. + +## Why is separating PHP from templates important? + +Two major benefits: + +- SYNTAX: Templates typically consist of semantic markup such as HTML. + PHP syntax works well for application code, but quickly degenerates + when mixed with HTML. Smarty\'s simple {tag} syntax is designed + specifically to express presentation. Smarty focuses your templates + on presentation and less on \"code\". This lends to quicker template + deployment and easier maintenance. Smarty syntax requires no working + knowledge of PHP, and is intuitive for programmers and + non-programmers alike. + +- INSULATION: When PHP is mixed with templates, there are no + restrictions on what type of logic can be injected into a template. + Smarty insulates the templates from PHP, creating a controlled + separation of presentation from business logic. Smarty also has + security features that can further enforce restrictions on + templates. + +## Web designers and PHP + +A common question: "Web designers have to learn a syntax anyway, why +not PHP?" Of course web designers can learn PHP, and they may already +be familiar with it. The issue isn't their ability to learn PHP, it is +about the consequences of mixing PHP with HTML. If designers use PHP, it +is too easy to add code into templates that doesn't belong there (you +just handed them a swiss-army knife when they just needed a knife.) You +can teach them the rules of application design, but this is probably +something they don't really need to learn (now they are developers!) +The PHP manual is also an overwhelming pile of information to sift +through. It is like handing the owner of a car the factory assembly +manual when all they need is the owners manual. Smarty gives web +designers exactly the tools they need, and gives developers fine-grained +control over those tools. The simplicity of the tag-based syntax is also +a huge welcome for designers, it helps them streamline the organization +and management of templates. + diff --git a/docs/preface.md b/docs/preface.md deleted file mode 100644 index 866bfa8e..00000000 --- a/docs/preface.md +++ /dev/null @@ -1,212 +0,0 @@ -Preface -======= - -**The Philosophy** - -The Smarty design was largely driven by these goals: - -- clean separation of presentation from application code -- PHP backend, Smarty template frontend -- complement PHP, not replace it -- fast development/deployment for programmers and designers -- quick and easy to maintain -- syntax easy to understand, no PHP knowledge necessary -- flexibility for custom development -- security: insulation from PHP -- free, open source - -**What is Smarty?** - -Smarty is a template engine for PHP, facilitating the separation of -presentation (HTML/CSS) from application logic. This implies that *PHP -code is application logic*, and is separated from the presentation. - -**Two camps of thought** - -When it comes to templating in PHP, there are basically two camps of -thought. The first camp exclaims that \"PHP is a template engine\". This -approach simply mixes PHP code with HTML. Although this approach is -fastest from a pure script-execution point of view, many would argue -that the PHP syntax is messy and complicated when mixed with tagged -markup such as HTML. - -The second camp exclaims that presentation should be void of all -programming code, and instead use simple tags to indicate where -application content is revealed. This approach is common with other -template engines (even in other programming languages), and is also the -approach that Smarty takes. The idea is to keep the templates focused -squarely on presentation, void of application code, and with as little -overhead as possible. - -**Why is separating PHP from templates important?** - -Two major benefits: - -- SYNTAX: Templates typically consist of semantic markup such as HTML. - PHP syntax works well for application code, but quickly degenerates - when mixed with HTML. Smarty\'s simple {tag} syntax is designed - specifically to express presentation. Smarty focuses your templates - on presentation and less on \"code\". This lends to quicker template - deployment and easier maintenance. Smarty syntax requires no working - knowledge of PHP, and is intuitive for programmers and - non-programmers alike. - -- INSULATION: When PHP is mixed with templates, there are no - restrictions on what type of logic can be injected into a template. - Smarty insulates the templates from PHP, creating a controlled - separation of presentation from business logic. Smarty also has - security features that can further enforce restrictions on - templates. - -**Web designers and PHP** - -A common question: \"Web designers have to learn a syntax anyways, why -not PHP?\" Of course web designers can learn PHP, and they may already -be familiar with it. The issue isn\'t their ability to learn PHP, it is -about the consequences of mixing PHP with HTML. If designers use PHP, it -is too easy to add code into templates that doesn\'t belong there (you -just handed them a swiss-army knife when they just needed a knife.) You -can teach them the rules of application design, but this is probably -something they don\'t really need to learn (now they are developers!) -The PHP manual is also an overwhelming pile of information to sift -through. It is like handing the owner of a car the factory assembly -manual when all they need is the owners manual. Smarty gives web -designers exactly the tools they need, and gives developers fine-grained -control over those tools. The simplicity of the tag-based syntax is also -a huge welcome for designers, it helps them streamline the organization -and management of templates. - -**Implementation is Important** - -Although Smarty gives you the tools to make a clean separation of -presentation from application code, it also gives you plenty of room to -bend those rules. A poor implementation (i.e. injecting PHP in -templates) will cause more problems than the presentation separation was -meant to resolve. The documentation does a good job of indicating what -things to watch out for. Also see the Best Practices section of the -Smarty website. - -**How does it work?** - -Under the hood, Smarty \"compiles\" (basically copies and converts) the -templates into PHP scripts. This happens once when each template is -first invoked, and then the compiled versions are used from that point -forward. Smarty takes care of this for you, so the template designer -just edits the Smarty templates and never has to manage the compiled -versions. This approach keeps the templates easy to maintain, and yet -keeps execution times extremely fast since the compiled code is just -PHP. And of course, all PHP scripts take advantage of PHP op-code caches -such as APC. - -**Template Inheritance** - -Template inheritance is new to Smarty 3, and it\'s one of many great new -features. Before template inheritance, we managed our templates in -pieces such as header and footer templates. This organization lends -itself to many problems that require some hoop-jumping, such as managing -content within the header/footer on a per-page basis. With template -inheritance, instead of including other templates we maintain our -templates as single pages. We can then manipulate blocks of content -within by inheriting them. This makes templates intuitive, efficient and -easy to manage. See the Template Inheritance section of th Smarty -website for more info. - -**Why not use XML/XSLT syntax?** - -There are a couple of good reasons. First, Smarty can be used for more -than just XML/HTML based templates, such as generating emails, -javascript, CSV, and PDF documents. Second, XML/XSLT syntax is even more -verbose and fragile than PHP code! It is perfect for computers, but -horrible for humans. Smarty is about being easy to read, understand and -maintain. - -**Template Security** - -Although Smarty insulates you from PHP, you still have the option to use -it in certain ways if you wish. Template security forces the restriction -of PHP (and select Smarty functions.) This is useful if you have third -parties editing templates, and you don\'t want to unleash the full power -of PHP or Smarty to them. - -**Integration** - -Sometimes Smarty gets compared to Model-View-Controller (MVC) -frameworks. Smarty is not an MVC, it is just the presentation layer, -much like the View (V) part of an MVC. As a matter of fact, Smarty can -easily be integrated as the view layer of an MVC. Many of the more -popular ones have integration instructions for Smarty, or you may find -some help here in the forums and documentation. - -**Other Template Engines** - -Smarty is not the only engine following the *\"Separate Programming Code -from Presentation\"* philosophy. For instance, Python has template -engines built around the same principles such as Django Templates and -CheetahTemplate. *Note: Languages such as Python do not mix with HTML -natively, which give them the advantage of proper programming code -separation from the outset. There are libraries available to mix Python -with HTML, but they are typically avoided.* - -**What Smarty is Not** - -Smarty is not an application development framework. Smarty is not an -MVC. Smarty is not an alternative to Zend Framework, CodeIgniter, -PHPCake, or any of the other application development frameworks for PHP. - -Smarty is a template engine, and works as the (V)iew component of your -application. Smarty can easily be coupled to any of the engines listed -above as the view component. No different than any other software, -Smarty has a learning curve. Smarty does not guarantee good application -design or proper separation of presentation, this still needs to be -addressed by a competent developer and web designer. - -**Is Smarty Right for Me?** - -Smarty is not meant to be a tool for every job. The important thing is -to identify if Smarty fits your needs. There are some important -questions to ask yourself: - -TEMPLATE SYNTAX. Are you content with PHP tags mixed with HTML? Are your -web designers comfortable with PHP? Would your web designers prefer a -tag-based syntax designed for presentation? Some experience working with -both Smarty and PHP helps answer these questions. - -THE BUSINESS CASE: Is there a requirement to insulate the templates from -PHP? Do you have untrusted parties editing templates that you do not -wish to unleash the power of PHP to? Do you need to programmatically -control what is and is not available within the templates? Smarty -supplies these capabilities by design. - -FEATURE SET: Does Smarty\'s features such as caching, template -inheritance and plugin architecture save development cycles writing code -that would be needed otherwise? Does the codebase or framework you plan -on using have the features you need for the presentation component? - -Templating in PHP is a hot topic, and opinions widely vary. It is -important that you understand Smarty, understand your own requirements, -and make an informed decision for yourself. You are welcome to ask -specific questions in the forums or the IRC channel. - -See also the section about \"Use Cases and Work Flow\" on the Smarty -website. - -**Sites using Smarty** - -There are tens of thousands of unique visitors on the Smarty website -daily, mostly developers reading documentation. Many well-known PHP -projects make use of Smarty such as XOOPS CMS, CMS Made Simple, Tiki -CMS/Groupware and X-Cart to name a few. - -**Summary** - -Whether you are using Smarty for a small website or massive enterprise -solution, it can accommodate your needs. There are numerous features -that make Smarty a great choice: - -- separation of PHP from HTML/CSS just makes sense -- readability for organization and management -- security for 3rd party template access -- feature completeness, and easily extendable to your own needs -- massive user base, Smarty is here to stay -- LGPL license for commercial use -- 100% free to use, open source project