Block Functions块函数

void smarty_block_name(array $params, mixed $content, object &$smarty)

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}.
块函数的形式是这样的:{func} .. {/func}。换句话说,他们用标记圈起一个块,然后对这个块的内容进行操作。块函数优先于同名的传统函数,即你不能同时有通明的传统函数{func}和块函数{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 how to change this).
默认地你的函数执行被Smarty调用两次:一次是在开始标记,另一次是在结束标记(参考下面的&$repeat怎样改变这种情况)

Only the opening tag of the block function may have attributes. All attributes passed to template functions from the template are contained in the $params as an associative array. You can either access those values directly, e.g. $params['start'] or use extract($params) to import them into the symbol table. The opening tag attributes are also accessible to your function when processing the closing tag.
块函数仅开始标记可以有属性。所有从模板传替给模板函数的属性被囊括与一个集合数组参数中。你可以直接获取其值,例如:$params['start']或者是用extract($params)将它们导入符号表中。当处理结束标记时,开始标记的属性对你的函数也是可用的。

The value of $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.
变量$content的值取决于是否因开始标记或结束标记调用你的函数。假如是开始标记,它会是空的,如果是结束标记,它会是模板块的内容。请注意模板块已经被Smarty处理,所以你接收到的结果是输出后的模板而不是原样模板。

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 block 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.
参数&$repeat通过参考引用传递给函数执行过程并为其提供一个可能值来控制显示块多少遍。默认情况下在首次调用块函数(块开始标记)时变量$repeat是真,在随后的所有块函数调用中其始终是假。每当函数执行返回的&$repeat是真时,在{func} .. {/func}之间的内容再次求值,函数执行接收一个新块参数$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() on it and the structure should be apparent.
如果你嵌套了块函数,通过访问变量$smarty->_tag_stack 找出父块函数是可能的。仅仅对块函数运行一下var_dump(),函数结构就会一目了然了。

See also: register_block(), unregister_block().

Example 16-5. block function

<?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;
    }
}