Feature/add docs (#689)

* 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

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

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

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

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.

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']);
+    }
+    ?>
+
+         

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

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.

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

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

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

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.