diff --git a/docs/api/rendering.md b/docs/api/rendering.md index e69de29bb..a66b61269 100644 --- a/docs/api/rendering.md +++ b/docs/api/rendering.md @@ -0,0 +1,86 @@ +# Rendering templates + +## Fetching or rendering templates directly +As explained in [basics](basics.md), you can use `$smarty->fetch()` or `$smarty->display()` +to render a template directly. + +```php +display('homepage.tpl'); + +// or + +$output = $smarty->fetch('homepage.tpl'); +``` + +When you use `display()`, Smarty renders the template to the standard output stream. +`fetch()` returns the output instead of echoing it. + +The example above uses simple filenames to load the template. Smarty also supports +[loading templates from resources](resources.md). + +## Creating a template object +You can also create a template object which later can be prepared first, +and rendered later. This can be useful, for example if you plan to re-use several +templates. + +```php +createTemplate('index.tpl'); + +// assign a variable (available only to this template) +$tpl->assign('title', 'My Homepage!'); + +// display the template +$tpl->display(); +``` + +More on assigning variables in [using data in templates](variables/assigning.md). + + +## Testing if a template exists +You can use `templateExists()` to check whether a template exists before you attempt to use it. + +It accepts either a path to the template on the filesystem or a +resource string specifying the template. + +This example uses `$_GET['page']` to +[`{include}`](../designers/language-builtin-functions/language-function-include.md) a content template. If the +template does not exist then an error page is displayed instead. First, +the `page_container.tpl` + +```smarty + + + {$title|escape} + + + {* include middle content page *} + {include file=$content_template} + + +``` + +And the php script: + +```php +templateExists($mid_template)){ + $mid_template = 'page_not_found.tpl'; +} +$smarty->assign('content_template', $mid_template); + +$smarty->display('page_container.tpl'); +``` diff --git a/docs/api/variables/assigning.md b/docs/api/variables/assigning.md index e69de29bb..3aa606b69 100644 --- a/docs/api/variables/assigning.md +++ b/docs/api/variables/assigning.md @@ -0,0 +1,139 @@ +# Assigning variables + +Templates start to become really useful once you know how to use variables. + +## Basic assigning +Let's revisit the example from the [basics section](../basics.md). The following script assigns a value to +the 'companyName' variable and renders the template: + +```php +assign('companyName', 'AC & ME Corp.'); + +$smarty->display('footer.tpl'); +``` + +footer.tpl: +```smarty +Copyright {$companyName|escape} +``` + +Smarty will apply the [escape modifier](../designers/language-modifiers/language-modifier-escape.md) +to the value assigned to the variable +`companyName` and replace `{$companyName|escape}` with the result. + +```html +Copyright AC & ME Corp. +``` + +Using `$smarty->assign()` is the most common way of assigning data to templates, but there are several other methods. + +## Appending data to an existing variable +Using `append()`, you can add data to an existing variable, usually an array. + +If you append to a string value, it is converted to an array value and +then appended to. You can explicitly pass name/value pairs, or +associative arrays containing the name/value pairs. If you pass the +optional third parameter of TRUE, the value will be merged with the +current array instead of appended. + +Examples: + +```php +append('foo', 'Fred'); +// After this line, foo will now be seen as an array in the template +$smarty->append('foo', 'Albert'); + +$array = [1 => 'one', 2 => 'two']; +$smarty->append('X', $array); +$array2 = [3 => 'three', 4 => 'four']; +// The following line will add a second element to the X array +$smarty->append('X', $array2); + +// passing an associative array +$smarty->append(['city' => 'Lincoln', 'state' => 'Nebraska']); +``` + +## Assigning to template objects +When you use a template objects, as explained in [rendering a template](../rendering.md#creating-a-template-object), +you can assign data to the template objects directly instead of assigning it to Smarty. This way, you can use different +sets of data for different templates. + +For example: +```php +createTemplate('blue.tpl'); +$tplBlue->assign('name', 'The one'); +$tplBlue->display(); + +$tplRed = $smarty->createTemplate('red.tpl'); +$tplRed->assign('name', 'Neo'); +$tplRed->display(); +``` + +## Using data objects +For more complex use cases, Smarty supports the concept of data objects. +Data objects are containers to hold data. Data objects can be attached to templates when creating them. +This allows for fine-grained re-use of data. + +For example: +```php +createData(); + +// assign variable to the data object +$data->assign('name', 'Neo'); + +// create template object which will use variables from the data object +$tpl = $smarty->createTemplate('index.tpl', $data); + +// display the template +$tpl->display(); +``` + +## Clearing assigned data +When re-using templates, you may need to clear data assigned in a previous run. Use `clearAllAssign()` to +clear the values of all assigned variables on data objects, template objects or the Smarty object. + +Examples: +```php +assign('Name', 'Fred'); +// ... +$smarty->clearAllAssign(); + +// using a data object +$data = $smarty->createData(); +$data->assign('name', 'Neo'); +// ... +$data->clearAllAssign(); + +// using a template +$tplBlue = $smarty->createTemplate('blue.tpl'); +$tplBlue->assign('name', 'The one'); +// ... +$tplBlue->clearAllAssign(); +``` + +Note that there it's only useful to clear assigned data if you: + +1. repeatedly re-use templates, and +2. the variables used may change on each repetition + +If your script simply runs once and then ends, or you always assign the same variables, clearing assigned data +is of no use. \ No newline at end of file diff --git a/docs/api/variables/config-files.md b/docs/api/variables/config-files.md index e69de29bb..2989d5059 100644 --- a/docs/api/variables/config-files.md +++ b/docs/api/variables/config-files.md @@ -0,0 +1 @@ +# Loading data from config files diff --git a/docs/programmers/api-functions/api-template-exists.md b/docs/programmers/api-functions/api-template-exists.md deleted file mode 100644 index 89c25d9f8..000000000 --- a/docs/programmers/api-functions/api-template-exists.md +++ /dev/null @@ -1,58 +0,0 @@ -templateExists() - -checks whether the specified template exists - -Description -=========== - -bool - -templateExists - -string - -template - -It can accept either a path to the template on the filesystem or a -resource string specifying the template. - -This example uses `$_GET['page']` to -[`{include}`](#language.function.include) a content template. If the -template does not exist then an error page is displayed instead. First -the `page_container.tpl` - - - - {$title} - - {include file='page_top.tpl'} - - {* include middle content page *} - {include file=$content_template} - - {include file='page_footer.tpl'} - - - - -And the php script - - - templateExists($mid_template) ){ - $mid_template = 'page_not_found.tpl'; - } - $smarty->assign('content_template', $mid_template); - - $smarty->display('page_container.tpl'); - - ?> - - - -See also [`display()`](#api.display), [`fetch()`](#api.fetch), -and [`{include}`](#language.function.include) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 71909647e..ce940ff0b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -118,7 +118,7 @@ nav: - 'Rendering a template': 'api/rendering.md' - 'Using data in templates': - 'Assigning variables': 'api/variables/assigning.md' - - 'Loading from config files': 'api/variables/config-files.md' + - 'Config files': 'api/variables/config-files.md' - 'Using streams': 'api/variables/streams.md' - 'Objects': 'api/variables/objects.md' - 'Static class methods': 'api/variables/static-class-methods.md'