iCMS 自定义模板方法开发指南

在 iCMS 中，开发者可以通过在 app/func/template 目录下创建自定义的模板方法文件来扩展模板功能。自定义模板方法分为三类：块处理器、函数处理器 和 调节器。以下是详细的开发说明和示例。

1. 文件命名规则

2. 开发说明

2.1 块处理器 (tpl.block 开头)

块处理器用于处理模板中的块内容，形式为 <!--{block}-->内容<!--{/block}-->。

开发步骤：

1. 在 app/func/template 目录下创建文件，如 tpl.block.cache.php。
2. 定义函数 tpl_block_自定义名称，函数接收三个参数：
   • $params: 块处理器的参数（数组）。
   • $content: 块内容。
   • $tpl: 模板对象。
3. 在函数中处理块内容，并返回处理后的结果。

示例代码：

<?php
/**
 * 缓存块内容
 */
function tpl_block_cache($params, &$content, &$tpl)
{
    $id = $params['id'] ?? 'default';
    $time = $params['time'] ?? 3600;
    $cache_name = "block_cache/{$id}";

    // 从缓存中获取内容
    $cached_content = Cache::get($cache_name);
    if ($cached_content === false) {
        // 缓存不存在，保存内容
        Cache::set($cache_name, $content, $time);
    } else {
        // 使用缓存内容
        $content = $cached_content;
    }

    return true; // 返回 true 表示继续渲染块内容
}

使用示例：

<!--{cache id="block1" time="3600"}-->
<div>缓存内容</div>
<!--{/cache}-->

2.2 函数处理器 (tpl.function 开头)

函数处理器用于在模板中调用函数，形式为 <!--{function 参数}-->。

开发步骤：

1. 在 app/func/template 目录下创建文件，如 tpl.function.array.php。
2. 定义函数 tpl_function_自定义名称，函数接收两个参数：
   • $params: 函数的参数（数组）。
   • $tpl: 模板对象。
3. 在函数中处理逻辑，并返回结果。

示例代码：

<?php
/**
 * 创建数组
 */
function tpl_function_array($params, &$tpl)
{
    $key = $params['as'] ?? 'array';
    $array = [];

    // 将参数转换为数组
    foreach ($params as $k => $v) {
        if ($k !== 'as') {
            $array[$k] = $v;
        }
    }

    // 将数组赋值给模板变量
    $tpl->assign($key, $array);
}

使用示例：

<!--{array as="myArray" key1="value1" key2="value2"}-->
{$myArray.key1} <!-- 输出: value1 -->

2.3 调节器 (tpl.modifier 开头)

调节器用于对模板变量进行处理，形式为 {$变量|调节器}。

开发步骤：

1. 在 app/func/template 目录下创建文件，如 tpl.modifier.upper.php。
2. 定义函数 tpl_modifier_自定义名称，函数接收一个或多个参数：
   • 第一个参数为待处理的变量。
   • 后续参数为调节器的参数。
3. 在函数中处理变量，并返回结果。

示例代码：

<?php
/**
 * 将字符串转换为大写
 */
function tpl_modifier_upper($string)
{
    return strtoupper($string);
}

使用示例：

{$str|upper} <!-- 将 $str 转换为大写 -->

3. 综合示例

3.1 块处理器示例：tpl.block.capture.php

<?php
/**
 * 捕获块内容并存储到变量中
 */
function tpl_block_capture($params, &$content, &$tpl)
{
    $assign = $params['assign'] ?? null;
    $name = $params['name'] ?? 'default';

    if ($assign) {
        // 将内容赋值给指定变量
        $tpl->assign($assign, $content);
    } else {
        // 将内容存储到默认变量中
        $tpl->_vars['capture'][$name] = $content;
    }

    return false; // 返回 false 表示不渲染块内容
}

使用示例：

<!--{capture assign="myContent"}-->
<div>捕获的内容</div>
<!--{/capture}-->
{$myContent} <!-- 输出捕获的内容 -->

3.2 函数处理器示例：tpl.function.math.php

<?php
/**
 * 执行数学运算
 */
function tpl_function_math($params, &$tpl)
{
    $equation = $params['equation'] ?? '';
    $assign = $params['assign'] ?? null;

    if (empty($equation)) {
        return;
    }

    // 解析变量
    foreach ($params as $key => $value) {
        if ($key !== 'equation' && $key !== 'assign') {
            $equation = str_replace($key, $value, $equation);
        }
    }

    // 执行运算
    eval("\$result = $equation;");

    if ($assign) {
        // 将结果赋值给模板变量
        $tpl->assign($assign, $result);
    } else {
        // 直接返回结果
        return $result;
    }
}

使用示例：

<!--{math equation="x + y" x=1 y=2 assign="sum"}-->
{$sum} <!-- 输出: 3 -->

3.3 调节器示例：tpl.modifier.cut.php

<?php
/**
 * 截取字符串
 */
function tpl_modifier_cut($string, $length = 80, $end = '...')
{
    if (strlen($string) > $length) {
        return substr($string, 0, $length) . $end;
    }
    return $string;
}

使用示例：

{$str|cut:50:'...'} <!-- 截取 $str 的前 50 个字符 -->

4. 最佳实践

1. 命名规范：

   • 文件名和函数名应保持一致，且使用小写字母和下划线。
   • 函数名应清晰表达其功能。

2. 参数处理：

   • 块处理器和函数处理器的参数应通过 $params 数组获取。
   • 调节器的参数应通过函数参数传递。

3. 返回值：

   • 块处理器返回 true 表示继续渲染块内容，返回 false 表示不渲染。
   • 函数处理器和调节器应返回处理后的结果。

4. 调试与测试：

   • 使用 var_dump 或日志记录调试信息。
   • 在模板中测试自定义方法的正确性。

通过自定义模板方法，开发者可以灵活扩展 iCMS 的模板功能，满足各种业务需求。