smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-08-03 09:54:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

WIP on API docs

Browse Source
This commit is contained in:
Simon Wisselink
2023-03-10 23:49:41 +01:00
parent f4b94d4f03
commit 1afd49e973
5 changed files with 227 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/api/rendering.md
View File

@@ -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
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$smarty->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
<?php
use Smarty\Smarty;
$smarty = new Smarty;
// create template object with its private variable scope
$tpl = $smarty->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
<html>
<head>
<title>{$title|escape}</title>
</head>
<body>
{* include middle content page *}
{include file=$content_template}
</body>
</html>
```
And the php script:
```php
<?php
// set the filename eg index.inc.tpl
$mid_template = $_GET['page'].'.inc.tpl';
if (!$smarty->templateExists($mid_template)){
$mid_template = 'page_not_found.tpl';
}
$smarty->assign('content_template', $mid_template);
$smarty->display('page_container.tpl');
```

139
docs/api/variables/assigning.md
View File

@@ -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
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$smarty->assign('companyName', 'AC & ME Corp.');
$smarty->display('footer.tpl');
```
footer.tpl:
```smarty
<small>Copyright {$companyName|escape}</small>
```
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
<small>Copyright AC &amp; ME Corp.</small>
```
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
<?php
// This is effectively the same as assign()
$smarty->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
<?php
use Smarty\Smarty;
$smarty = new Smarty();
$tplBlue = $smarty->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
<?php
use Smarty\Smarty;
$smarty = new Smarty;
// create a data object
$data = $smarty->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
<?php
// assigning data to the Smarty object
$smarty->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.

1
docs/api/variables/config-files.md
View File

@@ -0,0 +1 @@
# Loading data from config files

58
docs/programmers/api-functions/api-template-exists.md
View File

@@ -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`
<html>
<head><title>{$title}</title></head>
<body>
{include file='page_top.tpl'}
{* include middle content page *}
{include file=$content_template}
{include file='page_footer.tpl'}
</body>
And the php script
<?php
// set the filename eg index.inc.tpl
$mid_template = $_GET['page'].'.inc.tpl';
if( !$smarty->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)

2
mkdocs.yml
View File

@@ -118,7 +118,7 @@ nav:
- 'Rendering a template': 'api/rendering.md' - 'Rendering a template': 'api/rendering.md'
- 'Using data in templates': - 'Using data in templates':
- 'Assigning variables': 'api/variables/assigning.md' - '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' - 'Using streams': 'api/variables/streams.md'
- 'Objects': 'api/variables/objects.md' - 'Objects': 'api/variables/objects.md'
- 'Static class methods': 'api/variables/static-class-methods.md' - 'Static class methods': 'api/variables/static-class-methods.md'