diff options
Diffstat (limited to 'vendor/smarty/smarty/docs/programmers/plugins')
11 files changed, 759 insertions, 0 deletions
diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-block-functions.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-block-functions.md new file mode 100644 index 000000000..47281fef5 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-block-functions.md @@ -0,0 +1,95 @@ +Block Functions {#plugins.block.functions} +=============== + +void + +smarty\_block\_ + +name + +array + +\$params + +mixed + +\$content + +object + +\$template + +boolean + +&\$repeat + +Block functions are functions of the form: `{func} .. {/func}`. In other +words, they enclose a template block and operate on the contents of this +block. Block functions take precedence over [custom +functions](#language.custom.functions) of the same name, that is, you +cannot have both custom function `{func}` and block function +`{func}..{/func}`. + +- By default your function implementation is called twice by Smarty: + once for the opening tag, and once for the closing tag. (See + `$repeat` below on how to change this.) + +- Starting with Smarty 3.1 the returned value of the opening tag call + is displayed as well. + +- Only the opening tag of the block function may have + [attributes](#language.syntax.attributes). All attributes passed to + template functions from the template are contained in the `$params` + variable as an associative array. The opening tag attributes are + also accessible to your function when processing the closing tag. + +- The value of the `$content` variable depends on whether your + function is called for the opening or closing tag. In case of the + opening tag, it will be NULL, and in case of the closing tag it will + be the contents of the template block. Note that the template block + will have already been processed by Smarty, so all you will receive + is the template output, not the template source. + +- The parameter `$repeat` is passed by reference to the function + implementation and provides a possibility for it to control how many + times the block is displayed. By default `$repeat` is TRUE at the + first call of the block-function (the opening tag) and FALSE on all + subsequent calls to the block function (the block\'s closing tag). + Each time the function implementation returns with `$repeat` being + TRUE, the contents between `{func}...{/func}` are evaluated and the + function implementation is called again with the new block contents + in the parameter `$content`. + +If you have nested block functions, it\'s possible to find out what the +parent block function is by accessing `$smarty->_tag_stack` variable. +Just do a [`var_dump()`](&url.php-manual;var_dump) on it and the +structure should be apparent. + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: block.translate.php + * Type: block + * Name: translate + * Purpose: translate a block of text + * ------------------------------------------------------------- + */ + function smarty_block_translate($params, $content, Smarty_Internal_Template $template, &$repeat) + { + // only output on the closing tag + if(!$repeat){ + if (isset($content)) { + $lang = $params['lang']; + // do some intelligent translation thing here with $content + return $translation; + } + } + } + ?> + + + +See also: [`registerPlugin()`](#api.register.plugin), +[`unregisterPlugin()`](#api.unregister.plugin). diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-compiler-functions.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-compiler-functions.md new file mode 100644 index 000000000..ef2454e8a --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-compiler-functions.md @@ -0,0 +1,66 @@ +Compiler Functions {#plugins.compiler.functions} +================== + +Compiler functions are called only during compilation of the template. +They are useful for injecting PHP code or time-sensitive static content +into the template. If there is both a compiler function and a [custom +function](#language.custom.functions) registered under the same name, +the compiler function has precedence. + +mixed + +smarty\_compiler\_ + +name + +array + +\$params + +object + +\$smarty + +The compiler function is passed two parameters: the params array which +contains precompiled strings for the attribute values and the Smarty +object. It\'s supposed to return the code to be injected into the +compiled template including the surrounding PHP tags. + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: compiler.tplheader.php + * Type: compiler + * Name: tplheader + * Purpose: Output header containing the source file name and + * the time it was compiled. + * ------------------------------------------------------------- + */ + function smarty_compiler_tplheader($params, Smarty $smarty) + { + return "<?php\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';\n?>"; + } + ?> + +This function can be called from the template as: + + + {* this function gets executed at compile time only *} + {tplheader} + + + +The resulting PHP code in the compiled template would be something like +this: + + + <?php + echo 'index.tpl compiled at 2002-02-20 20:02'; + ?> + + + +See also [`registerPlugin()`](#api.register.plugin), +[`unregisterPlugin()`](#api.unregister.plugin). diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-functions.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-functions.md new file mode 100644 index 000000000..067b93826 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-functions.md @@ -0,0 +1,94 @@ +Template Functions {#plugins.functions} +================== + +void + +smarty\_function\_ + +name + +array + +\$params + +object + +\$template + +All [attributes](#language.syntax.attributes) passed to template +functions from the template are contained in the `$params` as an +associative array. + +The output (return value) of the function will be substituted in place +of the function tag in the template, eg the +[`{fetch}`](#language.function.fetch) function. Alternatively, the +function can simply perform some other task without any output, eg the +[`{assign}`](#language.function.assign) function. + +If the function needs to assign some variables to the template or use +some other Smarty-provided functionality, it can use the supplied +`$template` object to do so eg `$template->foo()`. + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: function.eightball.php + * Type: function + * Name: eightball + * Purpose: outputs a random magic answer + * ------------------------------------------------------------- + */ + function smarty_function_eightball($params, Smarty_Internal_Template $template) + { + $answers = array('Yes', + 'No', + 'No way', + 'Outlook not so good', + 'Ask again soon', + 'Maybe in your reality'); + + $result = array_rand($answers); + return $answers[$result]; + } + ?> + +which can be used in the template as: + + Question: Will we ever have time travel? + Answer: {eightball}. + + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: function.assign.php + * Type: function + * Name: assign + * Purpose: assign a value to a template variable + * ------------------------------------------------------------- + */ + function smarty_function_assign($params, Smarty_Internal_Template $template) + { + if (empty($params['var'])) { + trigger_error("assign: missing 'var' parameter"); + return; + } + + if (!in_array('value', array_keys($params))) { + trigger_error("assign: missing 'value' parameter"); + return; + } + + $template->assign($params['var'], $params['value']); + + } + ?> + + + +See also: [`registerPlugin()`](#api.register.plugin), +[`unregisterPlugin()`](#api.unregister.plugin). diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-howto.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-howto.md new file mode 100644 index 000000000..5738c3fcb --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-howto.md @@ -0,0 +1,18 @@ +How Plugins Work {#plugins.howto} +================ + +Plugins are always loaded on demand. Only the specific modifiers, +functions, resources, etc invoked in the templates scripts will be +loaded. Moreover, each plugin is loaded only once, even if you have +several different instances of Smarty running within the same request. + +Pre/postfilters and output filters are a bit of a special case. Since +they are not mentioned in the templates, they must be registered or +loaded explicitly via API functions before the template is processed. +The order in which multiple filters of the same type are executed +depends on the order in which they are registered or loaded. + +The [plugins directory](#variable.plugins.dir) can be a string +containing a path or an array containing multiple paths. To install a +plugin, simply place it in one of the directories and Smarty will use it +automatically. diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-inserts.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-inserts.md new file mode 100644 index 000000000..370a97bd0 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-inserts.md @@ -0,0 +1,48 @@ +Inserts {#plugins.inserts} +======= + +Insert plugins are used to implement functions that are invoked by +[`{insert}`](#language.function.insert) tags in the template. + +string + +smarty\_insert\_ + +name + +array + +\$params + +object + +\$template + +The first parameter to the function is an associative array of +attributes passed to the insert. + +The insert function is supposed to return the result which will be +substituted in place of the `{insert}` tag in the template. + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: insert.time.php + * Type: time + * Name: time + * Purpose: Inserts current date/time according to format + * ------------------------------------------------------------- + */ + function smarty_insert_time($params, Smarty_Internal_Template $template) + { + if (empty($params['format'])) { + trigger_error("insert time: missing 'format' parameter"); + return; + } + return strftime($params['format']); + } + ?> + + diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-modifiers.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-modifiers.md new file mode 100644 index 000000000..b089821a6 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-modifiers.md @@ -0,0 +1,86 @@ +Modifiers {#plugins.modifiers} +========= + +[Modifiers](#language.modifiers) are little functions that are applied +to a variable in the template before it is displayed or used in some +other context. Modifiers can be chained together. + +mixed + +smarty\_modifier\_ + +name + +mixed + +\$value + +\[mixed + +\$param1 + +, \...\] + +The first parameter to the modifier plugin is the value on which the +modifier is to operate. The rest of the parameters are optional, +depending on what kind of operation is to be performed. + +The modifier has to [return](&url.php-manual;return) the result of its +processing. + +This plugin basically aliases one of the built-in PHP functions. It does +not have any additional parameters. + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: modifier.capitalize.php + * Type: modifier + * Name: capitalize + * Purpose: capitalize words in the string + * ------------------------------------------------------------- + */ + function smarty_modifier_capitalize($string) + { + return ucwords($string); + } + ?> + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: modifier.truncate.php + * Type: modifier + * Name: truncate + * Purpose: Truncate a string to a certain length if necessary, + * optionally splitting in the middle of a word, and + * appending the $etc string. + * ------------------------------------------------------------- + */ + function smarty_modifier_truncate($string, $length = 80, $etc = '...', + $break_words = false) + { + if ($length == 0) + return ''; + + if (strlen($string) > $length) { + $length -= strlen($etc); + $fragment = substr($string, 0, $length+1); + if ($break_words) + $fragment = substr($fragment, 0, -1); + else + $fragment = preg_replace('/\s+(\S+)?$/', '', $fragment); + return $fragment.$etc; + } else + return $string; + } + ?> + + + +See also [`registerPlugin()`](#api.register.plugin), +[`unregisterPlugin()`](#api.unregister.plugin). diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-naming-conventions.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-naming-conventions.md new file mode 100644 index 000000000..28bbcfde8 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-naming-conventions.md @@ -0,0 +1,51 @@ +Naming Conventions {#plugins.naming.conventions} +================== + +Plugin files and functions must follow a very specific naming convention +in order to be located by Smarty. + +**plugin files** must be named as follows: + +> ` +> type.name.php +> ` + +- Where `type` is one of these plugin types: + + - function + + - modifier + + - block + + - compiler + + - prefilter + + - postfilter + + - outputfilter + + - resource + + - insert + +- And `name` should be a valid identifier; letters, numbers, and + underscores only, see [php + variables](&url.php-manual;language.variables). + +- Some examples: `function.html_select_date.php`, `resource.db.php`, + `modifier.spacify.php`. + +**plugin functions** inside the PHP files must be named as follows: + +> `smarty_type_name` + +- The meanings of `type` and `name` are the same as above. + +- An example modifier name `foo` would be + `function smarty_modifier_foo()`. + +Smarty will output appropriate error messages if the plugin file it +needs is not found, or if the file or the plugin function are named +improperly. diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-outputfilters.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-outputfilters.md new file mode 100644 index 000000000..4e34ab7eb --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-outputfilters.md @@ -0,0 +1,48 @@ +Output Filters {#plugins.outputfilters} +============== + +Output filter plugins operate on a template\'s output, after the +template is loaded and executed, but before the output is displayed. + +string + +smarty\_outputfilter\_ + +name + +string + +\$template\_output + +object + +\$template + +The first parameter to the output filter function is the template output +that needs to be processed, and the second parameter is the instance of +Smarty invoking the plugin. The plugin is supposed to do the processing +and return the results. + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: outputfilter.protect_email.php + * Type: outputfilter + * Name: protect_email + * Purpose: Converts @ sign in email addresses to %40 as + * a simple protection against spambots + * ------------------------------------------------------------- + */ + function smarty_outputfilter_protect_email($output, Smarty_Internal_Template $template) + { + return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!', + '$1%40$2', $output); + } + ?> + + + +See also [`registerFilter()`](#api.register.filter), +[`unregisterFilter()`](#api.unregister.filter). diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-prefilters-postfilters.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-prefilters-postfilters.md new file mode 100644 index 000000000..39467cbcb --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-prefilters-postfilters.md @@ -0,0 +1,89 @@ +Prefilters/Postfilters {#plugins.prefilters.postfilters} +====================== + +Prefilter and postfilter plugins are very similar in concept; where they +differ is in the execution \-- more precisely the time of their +execution. + +string + +smarty\_prefilter\_ + +name + +string + +\$source + +object + +\$template + +Prefilters are used to process the source of the template immediately +before compilation. The first parameter to the prefilter function is the +template source, possibly modified by some other prefilters. The plugin +is supposed to return the modified source. Note that this source is not +saved anywhere, it is only used for compilation. + +string + +smarty\_postfilter\_ + +name + +string + +\$compiled + +object + +\$template + +Postfilters are used to process the compiled output of the template (the +PHP code) immediately after the compilation is done but before the +compiled template is saved to the filesystem. The first parameter to the +postfilter function is the compiled template code, possibly modified by +other postfilters. The plugin is supposed to return the modified version +of this code. + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: prefilter.pre01.php + * Type: prefilter + * Name: pre01 + * Purpose: Convert html tags to be lowercase. + * ------------------------------------------------------------- + */ + function smarty_prefilter_pre01($source, Smarty_Internal_Template $template) + { + return preg_replace('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source); + } + ?> + + + + + <?php + /* + * Smarty plugin + * ------------------------------------------------------------- + * File: postfilter.post01.php + * Type: postfilter + * Name: post01 + * Purpose: Output code that lists all current template vars. + * ------------------------------------------------------------- + */ + function smarty_postfilter_post01($compiled, Smarty_Internal_Template $template) + { + $compiled = "<pre>\n<?php print_r(\$template->getTemplateVars()); ?>\n</pre>" . $compiled; + return $compiled; + } + ?> + + + +See also [`registerFilter()`](#api.register.filter) and +[`unregisterFilter()`](#api.unregister.filter). diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-resources.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-resources.md new file mode 100644 index 000000000..1b1fdf0ab --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-resources.md @@ -0,0 +1,128 @@ +Resources {#plugins.resources} +========= + +Resource plugins are meant as a generic way of providing template +sources or PHP script components to Smarty. Some examples of resources: +databases, LDAP, shared memory, sockets, and so on. + +Custom Resources may be put in a file `resource.foobarxyz.php` within +your [`$plugins_dir`](#variable.plugins.dir), or registered on runtime +with [`registerResource()`](#api.register.resource). In either case you +will be able to access that resource by prepending its name to the +template you\'re addressing: `foobarxyz:yourtemplate.tpl`. + +If a Resource\'s templates should not be run through the Smarty +compiler, the Custom Resource may extend `Smarty_Resource_Uncompiled`. +The Resource Handler must then implement the function +`renderUncompiled(Smarty_Internal_Template $_template)`. `$_template` is +a reference to the current template and contains all assigned variables +which the implementor can access via +`$_template->smarty->getTemplateVars()`. These Resources simply echo +their rendered content to the output stream. The rendered output will be +output-cached if the Smarty instance was configured accordingly. See +`libs/sysplugins/smarty_internal_resource_php.php` for an example. + +If the Resource\'s compiled templates should not be cached on disk, the +Custom Resource may extend `Smarty_Resource_Recompiled`. These Resources +are compiled every time they are accessed. This may be an expensive +overhead. See `libs/sysplugins/smarty_internal_resource_eval.php` for an +example. + + + <?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'} + + + +See also [`registerResource()`](#api.register.resource), +[`unregisterResource()`](#api.unregister.resource). diff --git a/vendor/smarty/smarty/docs/programmers/plugins/plugins-writing.md b/vendor/smarty/smarty/docs/programmers/plugins/plugins-writing.md new file mode 100644 index 000000000..972911d97 --- /dev/null +++ b/vendor/smarty/smarty/docs/programmers/plugins/plugins-writing.md @@ -0,0 +1,36 @@ +Writing Plugins {#plugins.writing} +=============== + +Plugins can be either loaded by Smarty automatically from the filesystem +or they can be registered at runtime via one of the register\_\* API +functions. They can also be unregistered by using unregister\_\* API +functions. + +For the plugins that are registered at runtime, the name of the plugin +function(s) does not have to follow the naming convention. + +If a plugin depends on some functionality provided by another plugin (as +is the case with some plugins bundled with Smarty), then the proper way +to load the needed plugin is this: + + + <?php + function smarty_function_yourPlugin(array $params, Smarty_Internal_Template $template) + { + // load plugin depended upon + $template->smarty->loadPlugin('smarty_shared_make_timestamp'); + // plugin code + } + ?> + + + +As a general rule, the currently evaluated template\'s +Smarty\_Internal\_Template object is always passed to the plugins as the +last parameter with two exceptions: + +- modifiers do not get passed the Smarty\_Internal\_Template object at + all + +- blocks get passed `$repeat` after the Smarty\_Internal\_Template + object to keep backwards compatibility to older versions of Smarty. |