smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-07-29 15:37:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Feature/add docs (#689)

Browse Source 
* Add converted docs repo

* Set theme jekyll-theme-minimal

* Removed BC docs, added TOC

* Added TOCs, rewrote most important links in documentation. Linked README to new Github Pages site

* some link fixes
This commit is contained in:
Simon Wisselink
2021-12-03 11:59:22 +01:00
committed by GitHub
parent baebd59bb4
commit 428a701b18
226 changed files with 13978 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/programmers/resources/resources-custom.md Normal file
View File

@ -0,0 +1,111 @@
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.
<?php
/**
* MySQL Resource
*
* Resource Implementation based on the Custom API to use
* MySQL as the storage resource for Smarty's templates and configs.
*
* Table definition:
* <pre>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;</pre>
*
* Demo data:
* <pre>INSERT INTO `templates` (`name`, `modified`, `source`) VALUES ('test.tpl', "2010-12-25 22:00:00", '{$x="hello world"}{$x}');</pre>
*
* @package Resource-examples
* @author Rodney Rehm
*/
class Smarty_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 SmartyException('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);
}
}
require_once 'libs/Smarty.class.php';
$smarty = new Smarty();
$smarty->registerResource('mysql', new Smarty_Resource_Mysql());
// using resource from php script
$smarty->display("mysql:index.tpl");
?>
And from within Smarty template:
{include file='mysql:extras/navigation.tpl'}

36
docs/programmers/resources/resources-extends.md Normal file
View File

@ -0,0 +1,36 @@
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 Interitance](#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
superseeded 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 programatically. 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.
<?php
$smarty->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).

160
docs/programmers/resources/resources-file.md Normal file
View File

@ -0,0 +1,160 @@
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.
> **Note**
>
> As of Smarty 3.1 the file resource no longer walks through the
> [include\_path](&url.php-manual;ini.core.php#ini.include-path) unless
> [`$use_include_path` is activated](#variable.use.include.path)
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.
<?php
$smarty->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 acces.
The bracket-syntax can be used from anywhere you can specify the `file:`
resource type.
<?php
// setup template directories
$smarty->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`.
<?php
$smarty->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.
<?php
$smarty->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'}

27
docs/programmers/resources/resources-streams.md Normal file
View File

@ -0,0 +1,27 @@
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"}

73
docs/programmers/resources/resources-string.md Normal file
View File

@ -0,0 +1,73 @@
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.
<?php
$smarty->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()`](&url.php-manual;urlencode) or
[`base64_encode()`](&url.php-manual;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)
<?php
$smarty->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() *}

130
docs/programmers/resources/template-resources.md Normal file
View File

@ -0,0 +1,130 @@
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.
<?php
/**
* MySQL Resource
*
* Resource Implementation based on the Custom API to use
* MySQL as the storage resource for Smarty's templates and configs.
*
* Table definition:
* <pre>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;</pre>
*
* Demo data:
* <pre>INSERT INTO `templates` (`name`, `modified`, `source`) VALUES ('test.tpl', "2010-12-25 22:00:00", '{$x="hello world"}{$x}');</pre>
*
* @package Resource-examples
* @author Rodney Rehm
*/
class Smarty_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 SmartyException('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);
}
}
require_once 'libs/Smarty.class.php';
$smarty = new Smarty();
$smarty->registerResource('mysql', new Smarty_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)