smarty/docs/en/programmers/plugins/plugins-block-functions.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
   <sect1 id="plugins.block.functions"><title>Block Functions</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>smarty_block_<replaceable>name</replaceable></function></funcdef>
      <paramdef>array <parameter>$params</parameter></paramdef>
      <paramdef>mixed <parameter>$content</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
      <paramdef>boolean <parameter>&amp;$repeat</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     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 of
     the same name, that is, you cannot have both custom function {func} and
     block function {func} .. {/func}.
    </para>
    <para>
     By default your function implementation is called twice by
     Smarty: once for the opening tag, and once for the closing tag
     (see <literal>&amp;$repeat</literal> below how to change this).
    </para>
    <para>
     Only the opening tag of the block function may have attributes. All
     attributes passed to template functions from the template are contained
     in the <parameter>$params</parameter> as an associative array. You can
     access those values as e.g. <varname>$params['start']</varname>.
     The opening tag attributes are also accessible to your function
     when processing the closing tag.
    </para>
    <para>
     The value of <parameter>$content</parameter> variable depends on
     whether your function is called for the opening or closing tag. In case
     of the opening tag, it will be <literal>null</literal>, 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.
    </para>

    <para>
     The parameter <parameter>&amp;$repeat</parameter> 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 <parameter>$repeat</parameter> is
     <literal>true</literal> at the first call of the block-function
     (the block opening tag) and <literal>false</literal> on all
     subsequent calls to the block function (the block's closing tag).
     Each time the function implementation returns with
     <parameter>&amp;$repeat</parameter> being true, the contents between
     {func} .. {/func} are evaluated and the function implementation
     is called again with the new block contents in the parameter
     <parameter>$content</parameter>.

	</para>

    <para>
     If you have nested block functions, it's possible to find out what the
     parent block function is by accessing
     <varname>$smarty->_tag_stack</varname> variable. Just do a var_dump()
     on it and the structure should be apparent.
    </para>
    <para>
     See also:
     <link linkend="api.register.block">register_block()</link>,
     <link linkend="api.unregister.block">unregister_block()</link>.
    </para>
    <example>
     <title>block function</title>
     <programlisting role="php">
<![CDATA[
<?php
/*
 * Smarty plugin
 * -------------------------------------------------------------
 * File:     block.translate.php
 * Type:     block
 * Name:     translate
 * Purpose:  translate a block of text
 * -------------------------------------------------------------
 */
function smarty_block_translate($params, $content, &$smarty, &$repeat)
{
    if (isset($content)) {
        $lang = $params['lang'];
        // do some intelligent translation thing here with $content
        return $translation;
    }
}
?>
]]>
     </programlisting>
    </example>
   </sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->