From 86b7d45399e6c522626c8f69354be27bdd04f9b2 Mon Sep 17 00:00:00 2001 From: Simon Wisselink Date: Sun, 6 Aug 2023 01:09:31 +0200 Subject: [PATCH] Rewrote docs on filters and resources. --- docs/api/filters/output-filters.md | 35 ++ docs/api/filters/postfilters.md | 33 ++ docs/api/filters/prefilters.md | 26 ++ docs/api/inheritance.md | 2 +- docs/api/resources.md | 305 ++++++++++++++++++ .../advanced-features-outputfilters.md | 37 --- .../advanced-features-postfilters.md | 35 -- .../advanced-features-prefilters.md | 31 -- .../advanced-features/extending-smarty.md | 3 - docs/programmers/resources.md | 19 -- .../programmers/resources/resources-custom.md | 113 ------- .../resources/resources-extends.md | 36 --- docs/programmers/resources/resources-file.md | 154 --------- .../resources/resources-streams.md | 27 -- .../programmers/resources/resources-string.md | 73 ----- .../resources/template-resources.md | 132 -------- mkdocs.yml | 13 +- 17 files changed, 407 insertions(+), 667 deletions(-) delete mode 100644 docs/programmers/advanced-features/advanced-features-outputfilters.md delete mode 100644 docs/programmers/advanced-features/advanced-features-postfilters.md delete mode 100644 docs/programmers/advanced-features/advanced-features-prefilters.md delete mode 100644 docs/programmers/advanced-features/extending-smarty.md delete mode 100644 docs/programmers/resources.md delete mode 100644 docs/programmers/resources/resources-custom.md delete mode 100644 docs/programmers/resources/resources-extends.md delete mode 100644 docs/programmers/resources/resources-file.md delete mode 100644 docs/programmers/resources/resources-streams.md delete mode 100644 docs/programmers/resources/resources-string.md delete mode 100644 docs/programmers/resources/template-resources.md diff --git a/docs/api/filters/output-filters.md b/docs/api/filters/output-filters.md index e69de29b..9de31892 100644 --- a/docs/api/filters/output-filters.md +++ b/docs/api/filters/output-filters.md @@ -0,0 +1,35 @@ +# Output filters + +When a template is rendered, its output can be sent through one or more +output filters. + +> **Note** +> This differs from [`prefilters`](prefilters.md) and +> [`postfilters`](postfilters.md) because, pre- and postfilters +> operate on compiled templates before they are saved to the disk, whereas +> output filters operate on the template output when it is executed. + +Smarty will pass the template output as the first argument, and expect the function +to return the result of the processing. + +Output filters can be either added as part of an [Extension](../extending/extensions.md) or +registered as shown below. + +This will provide a rudimentary protection against spambots: +```php +registerFilter("output", "protect_email"); +$smarty->display("index.tpl'); + +``` diff --git a/docs/api/filters/postfilters.md b/docs/api/filters/postfilters.md index e69de29b..0f4ba9dc 100644 --- a/docs/api/filters/postfilters.md +++ b/docs/api/filters/postfilters.md @@ -0,0 +1,33 @@ +# Postfilters + +Template postfilters are PHP functions that your templates are ran +through *after they are compiled*. + +Smarty will +pass the compiled template code as the first argument, and expect the +function to return the result of the processing, which must also be valid PHP code. + +Prefilters can be either added as part of an [Extension](../extending/extensions.md) or +registered as shown below. + + +```php +\n\"; ?>\n".$tpl_source; +} + +// register the postfilter +$smarty->registerFilter('post', 'add_header_comment'); +$smarty->display('index.tpl'); +``` + +The postfilter above will make the compiled Smarty template `index.tpl` +look like: + +```smarty + +{* rest of template content... *} +``` diff --git a/docs/api/filters/prefilters.md b/docs/api/filters/prefilters.md index e69de29b..2d5c19f9 100644 --- a/docs/api/filters/prefilters.md +++ b/docs/api/filters/prefilters.md @@ -0,0 +1,26 @@ +# Prefilters + +Template prefilters are PHP functions that your templates are ran +through *before they are compiled*. This is good for preprocessing your +templates to remove unwanted comments, keeping an eye on what people are +putting in their templates, etc. + +Smarty will pass the template source code as the first argument, and +expect the function to return the resulting template source code. + +Prefilters can be either added as part of an [Extension](../extending/extensions.md) or +registered as shown below. + +This will remove all the html comments in the template source: +```php +/U",'',$tpl_source); +} + +// register the prefilter +$smarty->registerFilter('pre', 'remove_dw_comments'); +$smarty->display('index.tpl'); +``` diff --git a/docs/api/inheritance.md b/docs/api/inheritance.md index 5512f467..f58369e6 100644 --- a/docs/api/inheritance.md +++ b/docs/api/inheritance.md @@ -120,7 +120,7 @@ and parent templates can be merged by the `append` or `prepend` ## Extends resource type Instead of using [`{extends}`](../designers/language-builtin-functions/language-function-extends.md) tags in the template files you can define the inheritance tree in your PHP script by -using the [`extends:` resource](../resources/resources-extends.md) type. +using the [`extends:` resource](resources.md#the-extends-resource) type. The code below will return same result as the example above. diff --git a/docs/api/resources.md b/docs/api/resources.md index e69de29b..b0e1f2be 100644 --- a/docs/api/resources.md +++ b/docs/api/resources.md @@ -0,0 +1,305 @@ +# Template resources + +## The filesystem resource + +So far in our examples, we have used simple filenames or paths when loading a template. + +For example, to load a template file called `homepage.tpl`, from the filesystem, you could write: +```php +display('homepage.tpl'); +``` + +The filesystem is the default resource. Templates, however, may come +from a variety of sources. When you render a template, or +when you include a template from within another template, you supply a +resource type, followed by `:` and the appropriate path and template name. + +If a resource is not explicitly given, the default resource type is assumed. +The resource type for the filesystem is `file`, which means that the previous example +can be rewritten as follows: +```php +display('file:homepage.tpl'); +``` + +The file resource pulls templates source files from the directories +specified using `Smarty::setTemplateDir()` (see [Configuring Smarty](configuring.md)). + +`setTemplateDir` accepts a single path, but can also ben called with an array of paths. +In that case, the list of directories is traversed in the order they appear in the array. The +first template found is the one to process. + +### Templates from a specific directory + +Smarty 3.1 introduced the bracket-syntax for specifying an element from +`Smarty::setTemplateDir()`. This allows websites +employing multiple sets of templates better control over which template +to access. + +The bracket-syntax can be used as follows: +```php +setTemplateDir([ + './templates', // element: 0, index: 0 + './templates_2', // element: 1, index: 1 + '10' => 'templates_10', // element: 2, index: '10' + 'foo' => 'templates_foo', // element: 3, index: 'foo' +]); + +/* + assume the template structure + ./templates/foo.tpl + ./templates_2/foo.tpl + ./templates_2/bar.tpl + ./templates_10/foo.tpl + ./templates_10/bar.tpl + ./templates_foo/foo.tpl +*/ + +// regular access +$smarty->display('file:foo.tpl'); +// will load ./templates/foo.tpl + +// using numeric index +$smarty->display('file:[1]foo.tpl'); +// will load ./templates_2/foo.tpl + +// using numeric string index +$smarty->display('file:[10]foo.tpl'); +// will load ./templates_10/foo.tpl + +// using string index +$smarty->display('file:[foo]foo.tpl'); +// will load ./templates_foo/foo.tpl + +// using "unknown" numeric index (using element number) +$smarty->display('file:[2]foo.tpl'); +// will load ./templates_10/foo.tpl +``` + +And, from within a Smarty template: + +```smarty +{include file="file:foo.tpl"} +{* will load ./templates/foo.tpl *} + +{include file="file:[1]foo.tpl"} +{* will load ./templates_2/foo.tpl *} + +{include file="file:[foo]foo.tpl"} +{* will load ./templates_foo/foo.tpl *} +``` + +### Using absolute paths + +Templates outside the specified template directories +require the `file:` template resource type, followed by the absolute +path to the template (with leading slash). + +```php +display('file:/export/templates/index.tpl'); +$smarty->display('file:/path/to/my/templates/menu.tpl'); +```` + +And from within a Smarty template: +```smarty +{include file='file:/usr/local/share/templates/navigation.tpl'} +``` + +> **Note** +> +> With [`Security`](security.md) enabled, access to +> templates outside of the specified templates directories is +> not allowed unless you whitelist those directories. + +### Windows file paths +If you are running on Windows, file paths usually include a drive +letter (such as `C:`) at the beginning of the pathname. Be sure to use `file:` in +the path to avoid namespace conflicts and get the desired results. +```php +display('file:C:/export/templates/index.tpl'); +$smarty->display('file:F:/path/to/my/templates/menu.tpl'); +``` + +And from within Smarty template: +```smarty +{include file='file:D:/usr/local/share/templates/navigation.tpl'} +``` + +### Handling missing templates +If the file resource cannot find the requested template, it will check if there is +a default template handler to call. By default, there is none, and Smarty will return an error, +but you can register a default template handler calling `Smarty::registerDefaultTemplateHandler` +with any [callable](https://www.php.net/manual/en/language.types.callable.php). + +```php +registerDefaultTemplateHandler([$this, 'handleMissingTemplate']); + +// ... + +public function handleMissingTemplate($type, $name, &$content, &$modified, Smarty $smarty) { + if (/* ... */) { + // return corrected filepath + return "/tmp/some/foobar.tpl"; + } elseif (/* ... */) { + // return a template directly + $content = "the template source"; + $modified = time(); + return true; + } else { + // tell smarty that we failed + return false; + } +} + +``` + +## The string and eval resources + +Smarty can render templates from a string by using the `string:` or +`eval:` resource. + +- The `string:` resource behaves much the same as a template file. The + template source is compiled from a string and stores the compiled + template code for later reuse. Each unique template string will + create a new compiled template file. If your template strings are + accessed frequently, this is a good choice. If you have frequently + changing template strings (or strings with low reuse value), the + `eval:` resource may be a better choice, as it doesn\'t save + compiled templates to disk. + +- The `eval:` resource evaluates the template source every time a page + is rendered. This is a good choice for strings with low reuse value. + If the same string is accessed frequently, the `string:` resource + may be a better choice. + +> **Note** +> +> With a `string:` resource type, each unique string generates a +> compiled file. Smarty cannot detect a string that has changed, and +> therefore will generate a new compiled file for each unique string. It +> is important to choose the correct resource so that you do not fill +> your disk space with wasted compiled strings. + +```php +assign('foo', 'value'); +$template_string = 'display {$foo} here'; +$smarty->display('string:' . $template_string); // compiles for later reuse +$smarty->display('eval:' . $template_string); // compiles every time +``` +From within a Smarty template: +```smarty +{include file="string:$template_string"} {* compiles for later reuse *} +{include file="eval:$template_string"} {* compiles every time *} +``` + +Both `string:` and `eval:` resources may be encoded with +[`urlencode()`](https://www.php.net/urlencode) or +[`base64_encode()`](https://www.php.net/urlencode). This is not necessary +for the usual use of `string:` and `eval:`, but is required when using +either of them in conjunction with the [`extends resource`](#the-extends-resource). + +```php + assign('foo','value'); + $template_string_urlencode = urlencode('display {$foo} here'); + $template_string_base64 = base64_encode('display {$foo} here'); + $smarty->display('eval:urlencode:' . $template_string_urlencode); // will decode string using urldecode() + $smarty->display('eval:base64:' . $template_string_base64); // will decode string using base64_decode() +``` + +From within a Smarty template: +```smarty + {include file="string:urlencode:$template_string_urlencode"} {* will decode string using urldecode() *} + {include file="eval:base64:$template_string_base64"} {* will decode string using base64_decode() *} +``` + +## The extends resource + +The `extends:` resource is used to define child/parent relationships. For details see section of +[Template inheritance](inheritance.md). + +> **Note** +> +> Using the extends resource is usually not necessary. If you have a choice, it is normally more flexible and +> intuitive to handle inheritance chains from within the templates using the [{extends} tag](inheritance.md). + +When `string:` and `eval:` templates are used, make sure they are properly url or base64 encoded. + +The templates within an inheritance chain are not compiled separately. Only a single compiled template will be generated. +(If an `eval:` resource is found within an inheritance chain, its "don't save a compile file" property is superseded by +the `extends:` resource.) + +Example: +```php +display('extends:parent.tpl|child.tpl|grandchild.tpl'); + +// inheritance from multiple template sources +$smarty->display('extends:db:parent.tpl|file:child.tpl|grandchild.tpl|eval:{block name="fooBazVar_"}hello world{/block}'); +``` + +## The stream resource + +Smarty allow you to use [PHP streams](https://www.php.net/manual/en/function.stream-wrapper-register.php) +as a template resource. Smarty will first look for a registered template resource. If nothing is +found, it will check if a PHP stream is available. If a stream is available, Smarty will use it +to fetch the template. + +For example, +```php +display('myresource:bar.tpl'); +``` + +Or, from within a template: +```smarty + {include file="myresource:bar.tpl"} +``` + +## Adding your own resource type +You can create a class that extends `Smarty\Resource\CustomPlugin` to add your own resource type, +for example to load template from a database. + +For example: +```php +registerResource('helloworld', new HelloWorldResource()); +``` + +## Changing the default resource type +The default resource type is `file`. If you want to change it, use `Smarty::setDefaultResourceType`. + +The following example will change the default resource type to `mysql`: +```php +setDefaultResourceType('mysql'); +``` diff --git a/docs/programmers/advanced-features/advanced-features-outputfilters.md b/docs/programmers/advanced-features/advanced-features-outputfilters.md deleted file mode 100644 index 5aee0be0..00000000 --- a/docs/programmers/advanced-features/advanced-features-outputfilters.md +++ /dev/null @@ -1,37 +0,0 @@ -# Output Filters - -When the template is invoked via [`display()`](../api-functions/api-display.md) or -[`fetch()`](../api-functions/api-fetch.md), its output can be sent through one or more -output filters. This differs from -[`postfilters`](advanced-features-postfilters.md) because postfilters -operate on compiled templates before they are saved to the disk, whereas -output filters operate on the template output when it is executed. - -Output filters can be either [registered](../api-functions/api-register-filter.md) -or added as part of a [custom extension](extending-smarty.md). Smarty will -pass the template output as the first argument, and expect the function -to return the result of the processing. - -```php -registerFilter("output","protect_email"); -$smarty->display("index.tpl'); - -// now any occurrence of an email address in the template output will have -// a simple protection against spambots -``` - - -See also [`registerFilter()`](../api-functions/api-register-filter.md), -[`addExtension()`](../api-functions/add-extension.md) and -[postfilters](#advanced.features.postfilters). diff --git a/docs/programmers/advanced-features/advanced-features-postfilters.md b/docs/programmers/advanced-features/advanced-features-postfilters.md deleted file mode 100644 index 5fbf4693..00000000 --- a/docs/programmers/advanced-features/advanced-features-postfilters.md +++ /dev/null @@ -1,35 +0,0 @@ -# Postfilters - -Template postfilters are PHP functions that your templates are ran -through *after they are compiled*. - -Postfilters can be -[registered](../api-functions/api-register-filter.md) or added as part of a [custom extension](extending-smarty.md). Smarty will -pass the compiled template code as the first argument, and expect the -function to return the result of the processing. - -```php -\n\"; ?>\n".$tpl_source; -} - -// register the postfilter -$smarty->registerFilter('post','add_header_comment'); -$smarty->display('index.tpl'); -``` - -The postfilter above will make the compiled Smarty template `index.tpl` -look like: - -```smarty - -{* rest of template content... *} -``` - -See also [`registerFilter()`](../api-functions/api-register-filter.md), -[prefilters](advanced-features-prefilters.md), -[outputfilters](advanced-features-outputfilters.md), and -[`addExtension()`](../api-functions/add-extension.md). diff --git a/docs/programmers/advanced-features/advanced-features-prefilters.md b/docs/programmers/advanced-features/advanced-features-prefilters.md deleted file mode 100644 index 6b50fd33..00000000 --- a/docs/programmers/advanced-features/advanced-features-prefilters.md +++ /dev/null @@ -1,31 +0,0 @@ -# Prefilters - -Template prefilters are PHP functions that your templates are ran -through *before they are compiled*. This is good for preprocessing your -templates to remove unwanted comments, keeping an eye on what people are -putting in their templates, etc. - -Prefilters can be -[registered](../api-functions/api-register-filter.md) or added as part of a [custom extension](extending-smarty.md). - -Smarty will pass the template source code as the first argument, and -expect the function to return the resulting template source code. - -This will remove all the html comments in the template source. - -```php -/U",'',$tpl_source); -} - -// register the prefilter -$smarty->registerFilter('pre','remove_dw_comments'); -$smarty->display('index.tpl'); -``` - -See also [`registerFilter()`](../api-functions/api-register-filter.md), -[postfilters](advanced-features-postfilters.md), and -[`addExtension()`](../api-functions/add-extension.md). diff --git a/docs/programmers/advanced-features/extending-smarty.md b/docs/programmers/advanced-features/extending-smarty.md deleted file mode 100644 index c0a90a65..00000000 --- a/docs/programmers/advanced-features/extending-smarty.md +++ /dev/null @@ -1,3 +0,0 @@ -# Extending Smarty - -@TODO diff --git a/docs/programmers/resources.md b/docs/programmers/resources.md deleted file mode 100644 index 23969006..00000000 --- a/docs/programmers/resources.md +++ /dev/null @@ -1,19 +0,0 @@ -Resources -========= - -The templates may come from a variety of sources. When you -[`display()`](./api-functions/api-display.md) or [`fetch()`](./api-functions/api-fetch.md) a template, or -when you include a template from within another template, you supply a -resource type, followed by the appropriate path and template name. If a -resource is not explicitly given, the value of -[`$default_resource_type`](./api-variables/variable-default-resource-type.md) (default: -\"file\") is assumed. - -## Table of contents - -- [File Template Resources](./resources/resources-file.md) -- [String Template Resources](./resources/resources-string.md) -- [Stream Template Resources](./resources/resources-streams.md) -- [Extends Template Resources](./resources/resources-extends.md) -- [Custom Template Resources](./resources/resources-custom.md) - diff --git a/docs/programmers/resources/resources-custom.md b/docs/programmers/resources/resources-custom.md deleted file mode 100644 index 1c41de1c..00000000 --- a/docs/programmers/resources/resources-custom.md +++ /dev/null @@ -1,113 +0,0 @@ -Custom Template Resources {#resources.custom} -========================= - -You can retrieve templates using whatever possible source you can access -with PHP: databases, sockets, files, etc. You do this by writing -resource plugin functions and registering them with Smarty. - -See [resource plugins](#plugins.resources) section for more information -on the functions you are supposed to provide. - -> **Note** -> -> Note that you cannot override the built-in `file:` resource, but you -> can provide a resource that fetches templates from the file system in -> some other way by registering under another resource name. - - - CREATE TABLE IF NOT EXISTS `templates` ( - * `name` varchar(100) NOT NULL, - * `modified` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, - * `source` text, - * PRIMARY KEY (`name`) - * ) ENGINE=InnoDB DEFAULT CHARSET=utf8; - * - * Demo data: - * 
INSERT INTO `templates` (`name`, `modified`, `source`) VALUES ('test.tpl', "2010-12-25 22:00:00", '{$x="hello world"}{$x}');
- * - - * @author Rodney Rehm - */ - class My_Resource_Mysql extends \Smarty\Resource\Custom { - // PDO instance - protected $db; - // prepared fetch() statement - protected $fetch; - // prepared fetchTimestamp() statement - protected $mtime; - - public function __construct() { - try { - $this->db = new PDO("mysql:dbname=test;host=127.0.0.1", "smarty", "smarty"); - } catch (PDOException $e) { - throw new \Smarty\Exception('Mysql Resource failed: ' . $e->getMessage()); - } - $this->fetch = $this->db->prepare('SELECT modified, source FROM templates WHERE name = :name'); - $this->mtime = $this->db->prepare('SELECT modified FROM templates WHERE name = :name'); - } - - /** - * Fetch a template and its modification time from database - * - * @param string $name template name - * @param string $source template source - * @param integer $mtime template modification timestamp (epoch) - * @return void - */ - protected function fetch($name, &$source, &$mtime) - { - $this->fetch->execute(array('name' => $name)); - $row = $this->fetch->fetch(); - $this->fetch->closeCursor(); - if ($row) { - $source = $row['source']; - $mtime = strtotime($row['modified']); - } else { - $source = null; - $mtime = null; - } - } - - /** - * Fetch a template's modification time from database - * - * @note implementing this method is optional. Only implement it if modification times can be accessed faster than loading the comple template source. - * @param string $name template name - * @return integer timestamp (epoch) the template was modified - */ - protected function fetchTimestamp($name) { - $this->mtime->execute(array('name' => $name)); - $mtime = $this->mtime->fetchColumn(); - $this->mtime->closeCursor(); - return strtotime($mtime); - } - } - - - - $smarty = new Smarty(); - $smarty->registerResource('mysql', new My_Resource_Mysql()); - - // using resource from php script - $smarty->display("mysql:index.tpl"); - ?> - - - -And from within Smarty template: - - - {include file='mysql:extras/navigation.tpl'} - - diff --git a/docs/programmers/resources/resources-extends.md b/docs/programmers/resources/resources-extends.md deleted file mode 100644 index d7213d89..00000000 --- a/docs/programmers/resources/resources-extends.md +++ /dev/null @@ -1,36 +0,0 @@ -Extends Template Resources {#resources.extends} -========================== - -The `extends:` resource is used to define child/parent relationships for -template inheritance from the PHP script. For details see section of -[Template Inheritance](#advanced.features.template.inheritance). - -As of Smarty 3.1 the `extends:` resource may use any available [template -resource](#resources), including `string:` and `eval:`. When [templates -from strings](#resources.string) are used, make sure they are properly -(url or base64) encoded. Is an `eval:` resource found within an -inheritance chain, its \"don\'t save a compile file\" property is -superseded by the `extends:` resource. The templates within an -inheritance chain are not compiled separately, though. Only a single -compiled template will be generated. - -> **Note** -> -> Use this when inheritance is required programmatically. When inheriting -> within PHP, it is not obvious from the child template what inheritance -> took place. If you have a choice, it is normally more flexible and -> intuitive to handle inheritance chains from within the templates. - - - display('extends:parent.tpl|child.tpl|grandchild.tpl'); - - // inheritance from multiple template sources - $smarty->display('extends:db:parent.tpl|file:child.tpl|grandchild.tpl|eval:{block name="fooBazVar_"}hello world{/block}'); - ?> - - - -See also [Template Inheritance](#advanced.features.template.inheritance) -[`{block}`](#language.function.block) and -[`{extends}`](#language.function.extends). diff --git a/docs/programmers/resources/resources-file.md b/docs/programmers/resources/resources-file.md deleted file mode 100644 index 1e58ba2c..00000000 --- a/docs/programmers/resources/resources-file.md +++ /dev/null @@ -1,154 +0,0 @@ -File Template Resources {#resources.file} -======================= - -Smarty ships with a built-in template resource for the filesystem. The -`file:` is the default resource. The resource key `file:` must only be -specified, if the -[`$default_resource_type`](#variable.default.resource.type) has been -changed. - -If the file resource cannot find the requested template, the -[`$default_template_handler_func`](#variable.default.template.handler.func) -is invoked. - -Templates from \$template\_dir {#templates.from.template.dir} ------------------------------- - -The file resource pulls templates source files from the directories -specified in [`$template_dir`](#variable.template.dir). The list of -directories is traversed in the order they appear in the array. The -first template found is the one to process. - - - display('index.tpl'); - $smarty->display('file:index.tpl'); // same as above - ?> - - - -From within a Smarty template - - - {include file='index.tpl'} - {include file='file:index.tpl'} {* same as above *} - - - -Templates from a specific \$template\_dir {#templates.from.specified.template.dir} ------------------------------------------ - -Smarty 3.1 introduced the bracket-syntax for specifying an element from -[`$template_dir`](#variable.template.dir). This allows websites -employing multiple sets of templates better control over which template -to access. - -The bracket-syntax can be used from anywhere you can specify the `file:` -resource type. - - - setTemplateDir(array( - './templates', // element: 0, index: 0 - './templates_2', // element: 1, index: 1 - '10' => 'templates_10', // element: 2, index: '10' - 'foo' => 'templates_foo', // element: 3, index: 'foo' - )); - - /* - assume the template structure - ./templates/foo.tpl - ./templates_2/foo.tpl - ./templates_2/bar.tpl - ./templates_10/foo.tpl - ./templates_10/bar.tpl - ./templates_foo/foo.tpl - */ - - // regular access - $smarty->display('file:foo.tpl'); - // will load ./templates/foo.tpl - - // using numeric index - $smarty->display('file:[1]foo.tpl'); - // will load ./templates_2/foo.tpl - - // using numeric string index - $smarty->display('file:[10]foo.tpl'); - // will load ./templates_10/foo.tpl - - // using string index - $smarty->display('file:[foo]foo.tpl'); - // will load ./templates_foo/foo.tpl - - // using "unknown" numeric index (using element number) - $smarty->display('file:[2]foo.tpl'); - // will load ./templates_10/foo.tpl - - ?> - - - -From within a Smarty template - - - {include file="file:foo.tpl"} - {* will load ./templates/foo.tpl *} - - {include file="file:[1]foo.tpl"} - {* will load ./templates_2/foo.tpl *} - - {include file="file:[foo]foo.tpl"} - {* will load ./templates_foo/foo.tpl *} - - - -Templates from any directory {#templates.from.any.dir} ----------------------------- - -Templates outside of the [`$template_dir`](#variable.template.dir) -require the `file:` template resource type, followed by the absolute -path to the template (with leading slash.) - -> **Note** -> -> With [`Security`](#advanced.features.security) enabled, access to -> templates outside of the [`$template_dir`](#variable.template.dir) is -> not allowed unless you list those directories in `$secure_dir`. - - - display('file:/export/templates/index.tpl'); - $smarty->display('file:/path/to/my/templates/menu.tpl'); - ?> - - - -And from within a Smarty template: - - - {include file='file:/usr/local/share/templates/navigation.tpl'} - - - -Windows Filepaths {#templates.windows.filepath} ------------------ - -If you are using a Windows machine, filepaths usually include a drive -letter (C:) at the beginning of the pathname. Be sure to use `file:` in -the path to avoid namespace conflicts and get the desired results. - - - display('file:C:/export/templates/index.tpl'); - $smarty->display('file:F:/path/to/my/templates/menu.tpl'); - ?> - - - -And from within Smarty template: - - - {include file='file:D:/usr/local/share/templates/navigation.tpl'} diff --git a/docs/programmers/resources/resources-streams.md b/docs/programmers/resources/resources-streams.md deleted file mode 100644 index e0596f59..00000000 --- a/docs/programmers/resources/resources-streams.md +++ /dev/null @@ -1,27 +0,0 @@ -Stream Template Resources {#resources.streams} -========================= - -Streams allow you to use PHP streams as a template resource. The syntax -is much the same a traditional template resource names. - -Smarty will first look for a registered template resource. If nothing is -found, it will check if a PHP stream is available. If a stream is -available, Smarty will use it to fetch the template. - -> **Note** -> -> You can further define allowed streams with security enabled. - -Using a PHP stream for a template resource from the display() function. - - - $smarty->display('foo:bar.tpl'); - - - -Using a PHP stream for a template resource from within a template. - - - {include file="foo:bar.tpl"} - - diff --git a/docs/programmers/resources/resources-string.md b/docs/programmers/resources/resources-string.md deleted file mode 100644 index d3f6d415..00000000 --- a/docs/programmers/resources/resources-string.md +++ /dev/null @@ -1,73 +0,0 @@ -String Template Resources {#resources.string} -========================= - -Smarty can render templates from a string by using the `string:` or -`eval:` resource. - -- The `string:` resource behaves much the same as a template file. The - template source is compiled from a string and stores the compiled - template code for later reuse. Each unique template string will - create a new compiled template file. If your template strings are - accessed frequently, this is a good choice. If you have frequently - changing template strings (or strings with low reuse value), the - `eval:` resource may be a better choice, as it doesn\'t save - compiled templates to disk. - -- The `eval:` resource evaluates the template source every time a page - is rendered. This is a good choice for strings with low reuse value. - If the same string is accessed frequently, the `string:` resource - may be a better choice. - -> **Note** -> -> With a `string:` resource type, each unique string generates a -> compiled file. Smarty cannot detect a string that has changed, and -> therefore will generate a new compiled file for each unique string. It -> is important to choose the correct resource so that you do not fill -> your disk space with wasted compiled strings. - - - assign('foo','value'); - $template_string = 'display {$foo} here'; - $smarty->display('string:'.$template_string); // compiles for later reuse - $smarty->display('eval:'.$template_string); // compiles every time - ?> - - - -From within a Smarty template - - - {include file="string:$template_string"} {* compiles for later reuse *} - {include file="eval:$template_string"} {* compiles every time *} - - - - -Both `string:` and `eval:` resources may be encoded with -[`urlencode()`](https://www.php.net/urlencode) or -[`base64_encode()`](https://www.php.net/urlencode). This is not necessary -for the usual use of `string:` and `eval:`, but is required when using -either of them in conjunction with -[`Extends Template Resource`](#resources.extends) - - - assign('foo','value'); - $template_string_urlencode = urlencode('display {$foo} here'); - $template_string_base64 = base64_encode('display {$foo} here'); - $smarty->display('eval:urlencode:'.$template_string_urlencode); // will decode string using urldecode() - $smarty->display('eval:base64:'.$template_string_base64); // will decode string using base64_decode() - ?> - - - -From within a Smarty template - - - {include file="string:urlencode:$template_string_urlencode"} {* will decode string using urldecode() *} - {include file="eval:base64:$template_string_base64"} {* will decode string using base64_decode() *} - - - diff --git a/docs/programmers/resources/template-resources.md b/docs/programmers/resources/template-resources.md deleted file mode 100644 index 15662493..00000000 --- a/docs/programmers/resources/template-resources.md +++ /dev/null @@ -1,132 +0,0 @@ -Resources {#resasdources} -========= - -The templates may come from a variety of sources. When you -[`display()`](#api.display) or [`fetch()`](#api.fetch) a template, or -when you include a template from within another template, you supply a -resource type, followed by the appropriate path and template name. If a -resource is not explicitly given, the value of -[`$default_resource_type`](#variable.default.resource.type) is assumed. - -Templates from other sources {#templates.from.elsewhere} ----------------------------- - -You can retrieve templates using whatever possible source you can access -with PHP: databases, sockets, files, etc. You do this by writing -resource plugin functions and registering them with Smarty. - -See [resource plugins](#plugins.resources) section for more information -on the functions you are supposed to provide. - -> **Note** -> -> Note that you cannot override the built-in `file:` resource, but you -> can provide a resource that fetches templates from the file system in -> some other way by registering under another resource name. - - - CREATE TABLE IF NOT EXISTS `templates` ( - * `name` varchar(100) NOT NULL, - * `modified` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, - * `source` text, - * PRIMARY KEY (`name`) - * ) ENGINE=InnoDB DEFAULT CHARSET=utf8; - * - * Demo data: - * 
INSERT INTO `templates` (`name`, `modified`, `source`) VALUES ('test.tpl', "2010-12-25 22:00:00", '{$x="hello world"}{$x}');
- * - - * @author Rodney Rehm - */ - class My_Resource_Mysql extends \Smarty\Resource\Custom { - // PDO instance - protected $db; - // prepared fetch() statement - protected $fetch; - // prepared fetchTimestamp() statement - protected $mtime; - - public function __construct() { - try { - $this->db = new PDO("mysql:dbname=test;host=127.0.0.1", "smarty", "smarty"); - } catch (PDOException $e) { - throw new \Smarty\Exception('Mysql Resource failed: ' . $e->getMessage()); - } - $this->fetch = $this->db->prepare('SELECT modified, source FROM templates WHERE name = :name'); - $this->mtime = $this->db->prepare('SELECT modified FROM templates WHERE name = :name'); - } - - /** - * Fetch a template and its modification time from database - * - * @param string $name template name - * @param string $source template source - * @param integer $mtime template modification timestamp (epoch) - * @return void - */ - protected function fetch($name, &$source, &$mtime) - { - $this->fetch->execute(array('name' => $name)); - $row = $this->fetch->fetch(); - $this->fetch->closeCursor(); - if ($row) { - $source = $row['source']; - $mtime = strtotime($row['modified']); - } else { - $source = null; - $mtime = null; - } - } - - /** - * Fetch a template's modification time from database - * - * @note implementing this method is optional. Only implement it if modification times can be accessed faster than loading the comple template source. - * @param string $name template name - * @return integer timestamp (epoch) the template was modified - */ - protected function fetchTimestamp($name) { - $this->mtime->execute(array('name' => $name)); - $mtime = $this->mtime->fetchColumn(); - $this->mtime->closeCursor(); - return strtotime($mtime); - } - } - - - - $smarty = new Smarty(); - $smarty->registerResource('mysql', new My_Resource_Mysql()); - - // using resource from php script - $smarty->display("mysql:index.tpl"); - ?> - - - -And from within Smarty template: - - - {include file='mysql:extras/navigation.tpl'} - - - -Default template handler function {#default.template.handler.function} ---------------------------------- - -You can specify a function that is used to retrieve template contents in -the event the template cannot be retrieved from its resource. One use of -this is to create templates that do not exist on-the-fly. - -See also [`Streams`](#advanced.features.streams) diff --git a/mkdocs.yml b/mkdocs.yml index d66ccf01..239bd360 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -123,19 +123,20 @@ nav: - 'Objects': 'api/variables/objects.md' - 'Static class methods': 'api/variables/static-class-methods.md' - 'Template inheritance': 'api/inheritance.md' + - 'Filters': + - 'Output filters': 'api/filters/output-filters.md' + - 'Prefilters': 'api/filters/prefilters.md' + - 'Postfilters': 'api/filters/postfilters.md' + - 'Template resources': 'api/resources.md' - 'Caching': - 'Basics': 'api/caching/basics.md' - 'Multiple caches per page': 'api/caching/multiple-caches-per-pages.md' - 'Custom cache storage layers': 'api/caching/custom-storage-layers.md' - - 'Security': 'api/security.md' - 'Extending Smarty': - 'Introduction': 'api/extending/introduction.md' - 'Creating an Extension': 'api/extending/extensions.md' - 'Custom tags': 'api/extending/tags.md' - 'Custom block tags': 'api/extending/block-tags.md' - 'Custom modifiers': 'api/extending/modifiers.md' - - 'Filters': - - 'Prefilters': 'api/filters/prefilters.md' - - 'Postfilters': 'api/filters/postfilters.md' - - 'Output filters': 'api/filters/output-filters.md' - - 'Loading templates from resources': 'api/resources.md' + - 'Security': 'api/security.md' +