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

# iCMS 自定义模板方法开发指南 在 iCMS 中，开发者可以通过在 `app/func/template` 目录下创建自定义的模板方法文件来扩展模板功能。自定义模板方法分为三类：**块处理器**、**函数处理器** 和 **调节器**。以下是详细的开发说明和示例。 --- ## 1. **文件命名规则** | 类型 | 文件命名规则 | 示例文件名 | | -------------- | ----------------------------- | ------------------------ | | **块处理器** | `tpl.block.自定义名称.php` | `tpl.block.cache.php` | | **函数处理器** | `tpl.function.自定义名称.php` | `tpl.function.array.php` | | **调节器** | `tpl.modifier.自定义名称.php` | `tpl.modifier.upper.php` | --- ## 2. **开发说明** ### 2.1 块处理器 (`tpl.block` 开头) 块处理器用于处理模板中的块内容，形式为 `<!--{block}-->内容<!--{/block}-->`。 #### 开发步骤： 1. 在 `app/func/template` 目录下创建文件，如 `tpl.block.cache.php`。 2. 定义函数 `tpl_block_自定义名称`，函数接收三个参数： - `$params`: 块处理器的参数（数组）。 - `$content`: 块内容。 - `$tpl`: 模板对象。 3. 在函数中处理块内容，并返回处理后的结果。 #### 示例代码： ```php <?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 表示继续渲染块内容 } ``` #### 使用示例： ```html <!--{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 <?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); } ``` #### 使用示例： ```html <!--{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 <?php /** * 将字符串转换为大写 */ function tpl_modifier_upper($string) { return strtoupper($string); } ``` #### 使用示例： ```html {$str|upper} <!-- 将 $str 转换为大写 --> ``` --- ## 3. **综合示例** ### 3.1 块处理器示例：`tpl.block.capture.php` ```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 表示不渲染块内容 } ``` #### 使用示例： ```html <!--{capture assign="myContent"}--> <div>捕获的内容</div> <!--{/capture}--> {$myContent} <!-- 输出捕获的内容 --> ``` ### 3.2 函数处理器示例：`tpl.function.math.php` ```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; } } ``` #### 使用示例： ```html <!--{math equation="x + y" x=1 y=2 assign="sum"}--> {$sum} <!-- 输出: 3 --> ``` ### 3.3 调节器示例：`tpl.modifier.cut.php` ```php <?php /** * 截取字符串 */ function tpl_modifier_cut($string, $length = 80, $end = '...') { if (strlen($string) > $length) { return substr($string, 0, $length) . $end; } return $string; } ``` #### 使用示例： ```html {$str|cut:50:'...'} <!-- 截取 $str 的前 50 个字符 --> ``` --- ## 4. **最佳实践** 1. **命名规范**： - 文件名和函数名应保持一致，且使用小写字母和下划线。 - 函数名应清晰表达其功能。 2. **参数处理**： - 块处理器和函数处理器的参数应通过 `$params` 数组获取。 - 调节器的参数应通过函数参数传递。 3. **返回值**： - 块处理器返回 `true` 表示继续渲染块内容，返回 `false` 表示不渲染。 - 函数处理器和调节器应返回处理后的结果。 4. **调试与测试**： - 使用 `var_dump` 或日志记录调试信息。 - 在模板中测试自定义方法的正确性。 --- 通过自定义模板方法，开发者可以灵活扩展 iCMS 的模板功能，满足各种业务需求。