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

Improved docs on compile checking and inheritance

Browse Source
This commit is contained in:
Simon Wisselink
2023-05-03 23:34:44 +02:00
parent 41962d5790
commit 4550bd8dfd
4 changed files with 147 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/api/configuring.md
View File

@@ -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
<?php
$smarty->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)

130
docs/api/inheritance.md
View File

@@ -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
<html>
<head>
<title>{block name=title}Default Page Title{/block}</title>
{block name=head}{/block}
</head>
<body>
{block name=body}{/block}
</body>
</html>
```
myproject.tpl (child)
```smarty
{extends file='layout.tpl'}
{block name=head}
<link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
<script src="/js/mypage.js"></script>
{/block}
```
mypage.tpl (grandchild)
```smarty
{extends file='myproject.tpl'}
{block name=title}My Page Title{/block}
{block name=head}
<link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
<script src="/js/mypage.js"></script>
{/block}
{block name=body}My HTML Page Body goes here{/block}
```
To render the above, you would use:
```php
<?php
$smarty->display('mypage.tpl');
```
The resulting output is:
```html
<html>
<head>
<title>My Page Title</title>
<link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
<script src="/js/mypage.js"></script>
</head>
<body>
My HTML Page Body goes here
</body>
</html>
```
> **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
<?php
$smarty->display('extends:layout.tpl|myproject.tpl|mypage.tpl');
```

128
docs/programmers/advanced-features/advanced-features-template-inheritance.md
View File

@@ -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
<html>
<head>
<title>{block name=title}Default Page Title{/block}</title>
{block name=head}{/block}
</head>
<body>
{block name=body}{/block}
</body>
</html>
```
myproject.tpl (child)
```smarty
{extends file='layout.tpl'}
{block name=head}
<link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
<script src="/js/mypage.js"></script>
{/block}
```
mypage.tpl (grandchild)
```smarty
{extends file='myproject.tpl'}
{block name=title}My Page Title{/block}
{block name=head}
<link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
<script src="/js/mypage.js"></script>
{/block}
{block name=body}My HTML Page Body goes here{/block}
```
To render the above use
```php
<?php
$smarty->display('mypage.tpl');
```
The resulting output is
```smarty
<html>
<head>
<title>My Page Title</title>
<link href="/css/mypage.css" rel="stylesheet" type="text/css"/>
<script src="/js/mypage.js"></script>
</head>
<body>
My HTML Page Body goes here
</body>
</html>
```
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
<?php
$smarty->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)

27
docs/programmers/api-variables/variable-compile-check.md
View File

@@ -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).