diff options
Diffstat (limited to 'vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-include.md')
| -rw-r--r-- | vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-include.md | 207 |
1 files changed, 101 insertions, 106 deletions
diff --git a/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-include.md b/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-include.md index bda2d802f..d12a817e0 100644 --- a/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-include.md +++ b/vendor/smarty/smarty/docs/designers/language-builtin-functions/language-function-include.md @@ -1,19 +1,31 @@ -{include} {#language.function.include} -========= +# {include} `{include}` tags are used for including other templates in the current template. Any variables available in the current template are also available within the included template. +## Attributes + +| Attribute Name | Required | Description | +|----------------|----------|--------------------------------------------------------------------------------------------| +| file | Yes | The name of the template file to include | +| assign | No | The name of the variable that the output of include will be assigned to | +| cache_lifetime | No | Enable caching of this subtemplate with an individual cache lifetime | +| compile_id | No | Compile this subtemplate with an individual compile_id | +| cache_id | No | Enable caching of this subtemplate with an individual cache_id | +| scope | No | Define the scope of all in the subtemplate assigned variables: 'parent','root' or 'global' | +| \[var \...\] | No | variable to pass local to template | + + - The `{include}` tag must have the `file` attribute which contains the template resource path. - Setting the optional `assign` attribute specifies the template variable that the output of `{include}` is assigned to, instead of - being displayed. Similar to [`{assign}`](#language.function.assign). + being displayed. Similar to [`{assign}`](./language-function-assign.md). - Variables can be passed to included templates as - [attributes](#language.syntax.attributes). Any variables explicitly + [attributes](../language-basic-syntax/language-syntax-attributes.md). Any variables explicitly passed to an included template are only available within the scope of the included file. Attribute variables override current template variables, in the case when they are named the same. @@ -25,36 +37,25 @@ available within the included template. default behaviour can be changed for all variables assigned in the included template by using the scope attribute at the `{include}` statement or for individual variables by using the scope attribute - at the [`{assign}`](#language.function.assign) statement. The later + at the [`{assign}`](./language-function-assign.md) statement. The later is useful to return values from the included template to the including template. -- Use the syntax for [template resources](#resources) to `{include}` - files outside of the [`$template_dir`](#variable.template.dir) +- Use the syntax for [template resources](../../programmers/resources.md) to `{include}` + files outside of the [`$template_dir`](../../programmers/api-variables/variable-template-dir.md) directory. -**Attributes:** - - Attribute Name Type Required Default Description - ----------------- ---------------- ---------- --------- -------------------------------------------------------------------------------------------------- - file string Yes *n/a* The name of the template file to include - assign string No *n/a* The name of the variable that the output of include will be assigned to - cache\_lifetime integer No *n/a* Enable caching of this subtemplate with an individual cache lifetime - compile\_id string/integer No *n/a* Compile this subtemplate with an individual compile\_id - cache\_id string/integer No *n/a* Enable caching of this subtemplate with an individual cache\_id - scope string No *n/a* Define the scope of all in the subtemplate assigned variables: \'parent\',\'root\' or \'global\' - \[var \...\] \[var type\] No *n/a* variable to pass local to template - -**Option Flags:** +## Option Flags - Name Description - --------- ------------------------------------------------------------------------------------- - nocache Disables caching of this subtemplate - caching Enable caching of this subtemplate - inline If set merge the compile code of the subtemplate into the compiled calling template +| Name | Description | +|---------|--------------------------------------------------------------------------------------| +| nocache | Disables caching of this subtemplate | +| caching | Enable caching of this subtemplate | +| inline | If set, merge the compile-code of the subtemplate into the compiled calling template | - - <html> +## Examples +```smarty +<html> <head> <title>{$title}</title> </head> @@ -69,124 +70,118 @@ available within the included template. {* using shortform file attribute *} {include 'page_footer.tpl'} </body> - </html> - - +</html> +``` +```smarty - {include 'links.tpl' title='Newest links' links=$link_array} - {* body of template goes here *} - {include 'footer.tpl' foo='bar'} +{include 'links.tpl' title='Newest links' links=$link_array} +{* body of template goes here *} +{include 'footer.tpl' foo='bar'} - +``` The template above includes the example `links.tpl` below - - <div id="box"> +```smarty +<div id="box"> <h3>{$title}{/h3> <ul> - {foreach from=$links item=l} - .. do stuff ... - </foreach} + {foreach from=$links item=l} + .. do stuff ... + </foreach} </ul> - </div> - +</div> +``` Variables assigned in the included template will be seen in the including template. - - {include 'sub_template.tpl' scope=parent} - ... - {* display variables assigned in sub_template *} - {$foo}<br> - {$bar}<br> - ... - +```smarty +{include 'sub_template.tpl' scope=parent} +... +{* display variables assigned in sub_template *} +{$foo}<br> +{$bar}<br> +... +``` - The template above includes the example `sub_template.tpl` below - - ... - {assign var=foo value='something'} - {assign var=bar value='value'} - ... +```smarty +... +{assign var=foo value='something'} +{assign var=bar value='value'} +... +``` The included template will not be cached. - - {include 'sub_template.tpl' nocache} - ... - +```smarty +{include 'sub_template.tpl' nocache} +... +``` - In this example included template will be cached with an individual cache lifetime of 500 seconds. - - {include 'sub_template.tpl' cache_lifetime=500} - ... - +```smarty +{include 'sub_template.tpl' cache_lifetime=500} +... +``` - In this example included template will be cached independent of the global caching setting. - - {include 'sub_template.tpl' caching} - ... - +```smarty +{include 'sub_template.tpl' caching} +... +``` - This example assigns the contents of `nav.tpl` to the `$navbar` variable, which is then output at both the top and bottom of the page. - - <body> - {include 'nav.tpl' assign=navbar} - {include 'header.tpl' title='Smarty is cool'} - {$navbar} - {* body of template goes here *} - {$navbar} - {include 'footer.tpl'} - </body> - +```smarty +<body> + {include 'nav.tpl' assign=navbar} + {include 'header.tpl' title='Smarty is cool'} + {$navbar} + {* body of template goes here *} + {$navbar} + {include 'footer.tpl'} +</body> +``` - This example includes another template relative to the directory of the current template. - - {include 'template-in-a-template_dir-directory.tpl'} - {include './template-in-same-directory.tpl'} - {include '../template-in-parent-directory.tpl'} - +```smarty +{include 'template-in-a-template_dir-directory.tpl'} +{include './template-in-same-directory.tpl'} +{include '../template-in-parent-directory.tpl'} +``` +```smarty +{* absolute filepath *} +{include file='/usr/local/include/templates/header.tpl'} +{* absolute filepath (same thing) *} +{include file='file:/usr/local/include/templates/header.tpl'} - {* absolute filepath *} - {include file='/usr/local/include/templates/header.tpl'} +{* windows absolute filepath (MUST use "file:" prefix) *} +{include file='file:C:/www/pub/templates/header.tpl'} - {* absolute filepath (same thing) *} - {include file='file:/usr/local/include/templates/header.tpl'} +{* include from template resource named "db" *} +{include file='db:header.tpl'} - {* windows absolute filepath (MUST use "file:" prefix) *} - {include file='file:C:/www/pub/templates/header.tpl'} +{* include a $variable template - eg $module = 'contacts' *} +{include file="$module.tpl"} - {* include from template resource named "db" *} - {include file='db:header.tpl'} - - {* include a $variable template - eg $module = 'contacts' *} - {include file="$module.tpl"} - - {* wont work as its single quotes ie no variable substitution *} - {include file='$module.tpl'} - - {* include a multi $variable template - eg amber/links.view.tpl *} - {include file="$style_dir/$module.$view.tpl"} +{* wont work as its single quotes ie no variable substitution *} +{include file='$module.tpl'} +{* include a multi $variable template - eg amber/links.view.tpl *} +{include file="$style_dir/$module.$view.tpl"} +``` - -See also [`{insert}`](#language.function.insert), [template resources](#resources) and -[componentized templates](#tips.componentized.templates). +See also [`{insert}`](./language-function-insert.md), [template resources](../../programmers/resources.md) and +[componentized templates](../../appendixes/tips.md#componentized-templates). |