banana split

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

@@ -0,0 +1,115 @@
+<?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>
+     </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)
+{
+    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
+-->