WIP on API docs

smarty-php · Mar 10, 2023 · 1afd49e · 1afd49e
1 parent f4b94d4
commit 1afd49e
Show file tree

Hide file tree

Showing 5 changed files with 227 additions and 59 deletions.
diff --git 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
+<?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');
+```
diff --git 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
+<?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.
diff --git 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
diff --git 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'