diff --git a/docs/api/configuring.md b/docs/api/configuring.md index b0f1ac65..32144b39 100644 --- a/docs/api/configuring.md +++ b/docs/api/configuring.md @@ -122,6 +122,23 @@ $smarty->setCacheDir('/data/caches'); $cacheDir = $smarty->getCacheDir(); ``` +## Disabling compile check +By default, Smarty tests to see if the +current template has changed since the last time +it was compiled. If it has changed, it recompiles that template. + +Once an application is put into production, this compile-check step +is usually no longer needed and the extra checks can significantly hurt performance. +Be sure to disable compile checking on production for maximum performance. +```php +setCompileCheck(\Smarty\Smarty::COMPILECHECK_OFF); +``` + +If [`caching`](./caching/basics.md) is enabled and compile-check is +enabled, then the cache files will get regenerated if an involved +template file or config file was updated. + ## Charset encoding There are a variety of encodings for textual data, ISO-8859-1 (Latin1) diff --git a/docs/api/inheritance.md b/docs/api/inheritance.md index e69de29b..5512f467 100644 --- a/docs/api/inheritance.md +++ b/docs/api/inheritance.md @@ -0,0 +1,130 @@ +# Template Inheritance + +Inheritance allows you to define base templates that can +be extended by child templates. Extending means that the child template +can override all or some of the named block areas in the base template. + +When you render the child template, the result will as if you rendered +the base template, with only the block(s) that you have overridden in the +child templates differing. + +- The inheritance tree can be as deep as you want, meaning you can + extend a file that extends another one that extends another one and + so on. + +- The child templates can not define any content besides what's + inside [`{block}`](../designers/language-builtin-functions/language-function-block.md) tags they override. + Anything outside of [`{block}`](../designers/language-builtin-functions/language-function-block.md) tags will + be removed. + +- Template inheritance is a compile time process which creates a + single compiled template file. Compared to corresponding solutions + based on subtemplates included with the + [`{include}`](../designers/language-builtin-functions/language-function-include.md) tag it does have much + better performance when rendering. + +## Basic inheritance + +First, create a base template with one or more [blocks](../designers/language-builtin-functions/language-function-block.md). +Then, create a child template. The child template +must have an [{extends} tag](../designers/language-builtin-functions/language-function-extends.md) on its first line. + +The child template can redefine one or more blocks defined in the base template. + +See below for a simple example. + +layout.tpl (base) + +```smarty + + + {block name=title}Default Page Title{/block} + {block name=head}{/block} + + + {block name=body}{/block} + + +``` + + +myproject.tpl (child) + +```smarty +{extends file='layout.tpl'} +{block name=head} + + +{/block} +``` + +mypage.tpl (grandchild) + +```smarty +{extends file='myproject.tpl'} +{block name=title}My Page Title{/block} +{block name=head} + + +{/block} +{block name=body}My HTML Page Body goes here{/block} +``` + + +To render the above, you would use: + +```php +display('mypage.tpl'); +``` + +The resulting output is: + +```html + + + My Page Title + + + + + My HTML Page Body goes here + + +``` + +> **Note** +> +> When [compile-check](./configuring.md#disabling-compile-check) is enabled, all files +> in the inheritance tree +> are checked for modifications upon each invocation. You may want to +> disable compile-check on production servers for this reason. + +> **Note** +> +> If you have a subtemplate which is included with +> [`{include}`](../designers/language-builtin-functions/language-function-include.md) and it contains +> [`{block}`](../designers/language-builtin-functions/language-function-block.md) areas it works only if the +> [`{include}`](../designers/language-builtin-functions/language-function-include.md) itself is called from within +> a surrounding [`{block}`](../designers/language-builtin-functions/language-function-block.md). In the final +> parent template you may need a dummy +> [`{block}`](../designers/language-builtin-functions/language-function-block.md) for it. + + +## Using append and prepend +The content of [`{block}`](../designers/language-builtin-functions/language-function-block.md) tags from child +and parent templates can be merged by the `append` or `prepend` +[`{block}`](../designers/language-builtin-functions/language-function-block.md) tag option flags and +`{$smarty.block.parent}` or `{$smarty.block.child}` placeholders. + +## 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. + +The code below will return same result as the example above. + +```php +display('extends:layout.tpl|myproject.tpl|mypage.tpl'); +``` diff --git a/docs/programmers/advanced-features/advanced-features-template-inheritance.md b/docs/programmers/advanced-features/advanced-features-template-inheritance.md deleted file mode 100644 index 8fd5fd63..00000000 --- a/docs/programmers/advanced-features/advanced-features-template-inheritance.md +++ /dev/null @@ -1,128 +0,0 @@ -# Template Inheritance - -Inheritance brings the concept of Object Oriented Programming to -templates, allowing you to define one (or more) base templates that can -be extended by child templates. Extending means that the child template -can override all or some of the parent named block areas. - -- The inheritance tree can be as deep as you want, meaning you can - extend a file that extends another one that extends another one and - so on. - -- The child templates can not define any content besides what's - inside [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags they override. - Anything outside of [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags will - be removed. - -- The content of [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tags from child - and parent templates can be merged by the `append` or `prepend` - [`{block}`](../../designers/language-builtin-functions/language-function-block.md) tag option flags and - `{$smarty.block.parent}` or `{$smarty.block.child}` placeholders. - -- Template inheritance is a compile time process which creates a - single compiled template file. Compared to corresponding solutions - based on subtemplates included with the - [`{include}`](../../designers/language-builtin-functions/language-function-include.md) tag it does have much - better performance when rendering. - -- The child template extends its parent defined with the - [`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) tag, which must be the - first line in the child template. Instead of using the - [`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) tags in the template files - you can define the whole template inheritance tree in the PHP script - when you are calling [`fetch()`](#api.fetch) or - [`display()`](#api.display) with the `extends:` template resource - type. The later provides even more flexibility. - -> **Note** -> -> When `$compile_check` is enabled, all files in the inheritance tree -> are checked for modifications upon each invocation. You may want to -> disable `$compile_check` on production servers for this reason. - -> **Note** -> -> If you have a subtemplate which is included with -> [`{include}`](../../designers/language-builtin-functions/language-function-include.md) and it contains -> [`{block}`](../../designers/language-builtin-functions/language-function-block.md) areas it works only if the -> [`{include}`](../../designers/language-builtin-functions/language-function-include.md) itself is called from within -> a surrounding [`{block}`](../../designers/language-builtin-functions/language-function-block.md). In the final -> parent template you may need a dummy -> [`{block}`](../../designers/language-builtin-functions/language-function-block.md) for it. - -layout.tpl (parent) - -```smarty - - - {block name=title}Default Page Title{/block} - {block name=head}{/block} - - - {block name=body}{/block} - - -``` - - -myproject.tpl (child) - -```smarty -{extends file='layout.tpl'} -{block name=head} - - -{/block} -``` - - - -mypage.tpl (grandchild) - -```smarty -{extends file='myproject.tpl'} -{block name=title}My Page Title{/block} -{block name=head} - - -{/block} -{block name=body}My HTML Page Body goes here{/block} -``` - - -To render the above use - -```php -display('mypage.tpl'); -``` - -The resulting output is - -```smarty - - - My Page Title - - - - - My HTML Page Body goes here - - -``` - -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. - -The code below will return same result as the example above. - -```php -display('extends:layout.tpl|myproject.tpl|mypage.tpl'); -``` - -See also [`{block}`](../../designers/language-builtin-functions/language-function-block.md), -[`{extends}`](../../designers/language-builtin-functions/language-function-extends.md) and [`extends:` -resource](../resources/resources-extends.md) diff --git a/docs/programmers/api-variables/variable-compile-check.md b/docs/programmers/api-variables/variable-compile-check.md deleted file mode 100644 index 459b5b30..00000000 --- a/docs/programmers/api-variables/variable-compile-check.md +++ /dev/null @@ -1,27 +0,0 @@ -\$compile\_check {#variable.compile.check} -================ - -Upon each invocation of the PHP application, Smarty tests to see if the -current template has changed (different timestamp) since the last time -it was compiled. If it has changed, it recompiles that template. If the -template has yet not been compiled at all, it will compile regardless of -this setting. By default this variable is set to TRUE. - -Once an application is put into production (ie the templates won\'t be -changing), the compile check step is no longer needed. Be sure to set -`$compile_check` to FALSE for maximum performance. Note that if you -change this to FALSE and a template file is changed, you will \*not\* -see the change since the template will not get recompiled. - -If [`$caching`](#variable.caching) is enabled and `$compile_check` is -enabled, then the cache files will get regenerated if an involved -template file or config file was updated. - -As of Smarty 3.1 `$compile_check` can be set to the value -`\Smarty\Smarty::COMPILECHECK_CACHEMISS`. This enables Smarty to revalidate the -compiled template, once a cache file is regenerated. So if there was a -cached template, but it\'s expired, Smarty will run a single -compile\_check before regenerating the cache. - -See [`$force_compile`](#variable.force.compile) and -[`clearCompiledTemplate()`](#api.clear.compiled.tpl).