附录二 Smarty 模板组织与调用规范
本附录用于规范 WSaiOS 智能个体构建工程中 Smarty 模板的组织、数据传递、模板调用、页面生成和前后台交互方式。
Smarty 是基于 PHP 的模板引擎,在 WSaiOS 工程中主要负责智能个体前台页面的动态生成和数据呈现。PHP 程序负责读取智能结构、组织实例数据、执行业务逻辑和处理用户请求,Smarty 模板负责接收 PHP 传递的数据,并按照页面结构生成 HTML 内容。
必须明确,Smarty 展示模板与 WSaiOS 智能模板是两种不同的工程对象。WSaiOS 智能模板用于定义智能个体的结构、属性、方法、状态、关系和能力配置,是智能个体构建的依据;Smarty 模板用于定义页面布局、数据展示和用户交互界面,是智能个体前台呈现的依据。两者可以建立关联,但不能相互替代。
一、Smarty 模板在工程中的职责
WSaiOS 工程采用 PHP 面向对象程序与 Smarty 模板引擎相结合的方式,实现智能个体的数据处理和动态页面呈现。
PHP 程序负责完成数据读取、结构解析、实例查询、权限验证、业务计算和数据组织。Smarty 负责将 PHP 提供的数据按照预先定义的展示结构进行排版和输出。
在智能个体构建管理过程中,后台程序可以根据实例标识读取个体的基本信息、结构属性、运行状态、知识能力配置和管理权限,再将经过处理的数据分配给 Smarty。Smarty 根据不同页面的展示要求调用对应模板,生成智能个体的管理页面、详情页面、状态页面和交互页面。
Smarty 不负责定义智能个体的真实结构,也不负责执行智能个体的核心认知、决策和运行逻辑。需要进行结构匹配、能力判断或运行控制时,应当由 PHP 业务程序及相应的运行模块处理。
二、Smarty 模板目录组织规范
Smarty 模板应当按照页面类型和功能职责进行组织。不同页面可以共享基础布局,也可以根据具体业务需求建立独立模板。
在 WSaiOS 工程中,模板目录应当与 PHP 程序目录保持职责分离。PHP 程序负责控制流程和数据组织,Smarty 模板负责页面结构和数据呈现。
例如,可以采用以下目录组织方式:
templates/
├── layouts/
│ ├── main.tpl # 后台页面的基础布局
│ └── individual.tpl # 智能个体页面的基础布局
│
├── structure/
│ ├── structure_list.tpl # 动态结构列表页面
│ ├── structure_detail.tpl # 动态结构详情页面
│ └── structure_edit.tpl # 动态结构编辑页面
│
├── template/
│ ├── template_list.tpl # 智能模板列表页面
│ ├── template_detail.tpl # 智能模板详情页面
│ └── template_edit.tpl # 智能模板编辑页面
│
├── individual/
│ ├── individual_list.tpl # 智能个体实例列表页面
│ ├── individual_detail.tpl # 智能个体实例详情页面
│ ├── individual_state.tpl # 智能个体运行状态页面
│ └── individual_config.tpl # 智能个体配置页面
│
├── capability/
│ ├── knowledge.tpl # 个体知识配置呈现页面
│ └── capability.tpl # 个体能力配置呈现页面
│
└── components/
├── header.tpl # 页面公共头部组件
├── sidebar.tpl # 后台导航组件
├── pagination.tpl # 列表分页组件
└── message.tpl # 操作反馈信息组件
以上目录属于工程组织示例。实际项目应当根据已经存在的程序目录和页面功能进行安排,不应为了符合目录示例而重复创建已有文件。
每个模板文件应当具有明确的页面职责。页面模板负责组织具体内容,公共布局负责页面整体框架,公共组件负责可复用的局部页面结构。模板之间应当避免重复定义相同的公共页面元素。
三、Smarty 初始化与 PHP 程序调用规范
Smarty 的初始化应当集中在项目的模板配置或统一初始化程序中,不应当在每个控制器中重复创建模板引擎实例。
PHP 程序需要根据项目实际使用的 Smarty 版本配置模板目录、编译目录和缓存目录,并保证相关目录具有适当的读写权限。
以下示例用于说明 PHP 程序初始化 Smarty 的基本方式:
<?php
require_once __DIR__ . '/../vendor/autoload.php';
$smarty = new Smarty();
$smarty->setTemplateDir(
__DIR__ . '/../templates/'
);
$smarty->setCompileDir(
__DIR__ . '/../runtime/templates_c/'
);
$smarty->setCacheDir(
__DIR__ . '/../runtime/cache/'
);
上述代码以已经通过 Composer 加载 Smarty 类为前提。实际工程如果采用其他 Smarty 安装方式,应当按照项目已有的加载机制初始化,不应重复引入不同版本的 Smarty。
模板引擎初始化完成后,PHP 控制器可以通过统一的模板服务向 Smarty 传递数据并生成页面。
<?php
class IndividualController
{
private $smarty;
private $instanceManager;
public function __construct($smarty, $instanceManager)
{
$this->smarty = $smarty;
$this->instanceManager = $instanceManager;
}
/**
* 显示智能个体详情
*/
public function detail($instanceId)
{
$individual = $this->instanceManager
->getInstance($instanceId);
if (!$individual) {
throw new RuntimeException('智能个体不存在');
}
$this->smarty->assign(
'individual',
$individual
);
$this->smarty->display(
'individual/individual_detail.tpl'
);
}
}
该示例说明控制器读取实例数据后,将数据交给 Smarty 生成页面。实际工程还需要在调用前进行用户身份认证、实例访问权限验证、数据完整性检查和必要的数据格式处理。
四、PHP 数据赋值与 Smarty 变量调用规范
PHP 与 Smarty 之间通过数据赋值建立联系。PHP 使用 assign() 将数据传递给模板,Smarty 使用变量表达式读取对应的数据。
数据赋值应当遵循明确的数据命名规范。变量名称应当能够表达实际含义,避免使用大量无意义的缩写或含义重复的变量。
例如,PHP 程序可以向 Smarty 传递智能个体的基本数据:
<?php
$smarty->assign('instance_id', $instanceId);
$smarty->assign('instance_name', $instanceName);
$smarty->assign('instance_state', $instanceState);
$smarty->assign('structure_version', $structureVersion);
$smarty->assign('attributes', $attributes);
Smarty 模板中可以通过对应变量进行调用:
<div class="individual-detail">
<h2>{$instance_name|escape}</h2>
<p>实例编号:{$instance_id|escape}</p>
<p>运行状态:{$instance_state|escape}</p>
<p>结构版本:{$structure_version|escape}</p>
</div>
对于数组数据,可以使用 Smarty 的数组访问方式:
{foreach $attributes as $attribute}
<div class="attribute-item">
<span>{$attribute.name|escape}</span>
<span>{$attribute.value|escape}</span>
</div>
{/foreach}
实际数据字段必须与 PHP 传递的数据结构一致。模板不得假定一个字段一定存在,应当根据实际数据情况进行空值判断和默认显示处理。
对于来自用户输入、外部信息源或动态结构数据的内容,应当进行适当的输出转义。需要展示 HTML 内容时,也应当经过明确的安全过滤,不能直接将未经验证的外部字符串作为可信 HTML 输出。
五、动态属性数据的 Smarty 呈现规范
WSaiOS 智能个体的属性具有动态定义特点。不同类型的个体可能具有完全不同的属性名称、数据类型和属性数量。因此,Smarty 模板不能将所有智能个体的属性名称和属性字段固定写在页面代码中。
PHP 应当先根据实例所引用的动态结构定义读取属性描述,再读取实例中对应的属性值,将属性名称、属性类型、属性值和必要的展示信息组织为统一数据结构,最后传递给 Smarty。
例如,PHP 传递的数据可以组织为:
$attributes = array(
array(
'name' => '设备编号',
'type' => 'string',
'value' => 'DEV-001'
),
array(
'name' => '运行状态',
'type' => 'string',
'value' => 'running'
),
array(
'name' => '运行温度',
'type' => 'number',
'value' => 36.5
)
);
$smarty->assign('attributes', $attributes);
Smarty 根据数据内容循环生成属性页面:
<div class="attribute-list">
{foreach $attributes as $attribute}
<div class="attribute-row">
<span class="attribute-name">
{$attribute.name|escape}
</span>
<span class="attribute-value">
{$attribute.value|escape}
</span>
</div>
{/foreach}
</div>
这样,同一个展示模板就能够呈现不同结构定义下的动态属性,而不需要针对每种智能个体重新编写一套固定属性页面。
如果不同属性类型需要不同的展示形式,应当由 PHP 根据属性定义组织明确的展示类型,再由 Smarty 根据展示类型选择相应的页面组件。数据类型本身不能直接决定是否允许执行某种页面操作。
六、Smarty 模板继承与公共组件规范
Smarty 模板继承用于建立页面之间的公共布局关系。基础布局可以定义页面整体结构,具体页面通过继承基础模板填充相应内容。
例如,基础布局可以定义:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>{$page_title|escape}</title>
</head>
<body>
{include file="components/header.tpl"}
<main>
{block name="content"}{/block}
</main>
</body>
</html>
具体页面通过继承基础布局组织页面内容:
{extends file="layouts/main.tpl"}
{block name="content"}
<section class="individual-page">
<h2>{$individual.name|escape}</h2>
<p>实例编号:{$individual.id|escape}</p>
</section>
{/block}
公共组件适合用于页面头部、导航、分页、状态提示和重复出现的属性展示区域。
模板继承应当保持清晰的层次关系,避免出现多层复杂继承导致页面内容来源难以判断的情况。公共组件应当通过明确的数据变量接收必要内容,不应当直接承担业务数据查询或智能逻辑计算。
需要注意,以上代码中的 Smarty 语法应当与项目实际使用的 Smarty 版本保持一致。不同版本在部分模板功能和配置方式上可能存在差异,实际部署时应当以项目安装版本为准。
七、Smarty 模板与智能模板的数据关系
WSaiOS 工程中存在两种需要严格区分的模板体系。
智能模板是 WSaiOS 智能个体构建体系中的结构定义依据,负责描述个体需要具备的结构元素、属性、方法、状态、关系、知识和能力等内容。
Smarty 模板是前台页面生成依据,负责将 PHP 组织的数据呈现为可阅读、可操作的页面。
两者之间的数据关系可以表示为:
智能模板不会直接被 Smarty 当作页面模板执行。PHP 程序根据智能个体实例和结构定义组织数据,再将适合页面展示的数据传递给 Smarty。
例如,智能模板中定义了某个对象具有若干动态属性和方法,PHP 程序可以读取这些定义,并结合实例当前的实际属性值和方法状态,组织成页面需要的数据。
页面展示的方法名称、运行状态和操作入口,不代表用户已经具有执行相应方法的权限。实际操作必须由 PHP 后台进行权限检查和运行条件验证。
八、Smarty 动态页面生成与缓存规范
Smarty 页面生成应当由 PHP 控制器或统一页面服务调用。页面生成过程需要根据当前访问对象确定数据范围、模板文件和页面参数。
对于相同页面结构、相同数据条件的重复访问,可以根据实际需要使用 Smarty 缓存机制。但智能个体的运行状态、权限信息和实时属性具有动态变化特点,不能不加区分地使用长期缓存。
对于需要实时反映个体运行状态的页面,应当明确缓存有效期,或者根据状态更新时间和实例版本确定缓存是否有效。
缓存标识应当考虑页面类型、实例标识、数据版本和用户权限范围,避免不同实例或不同权限用户之间错误共享缓存内容。
结构定义或智能模板更新后,如果页面数据映射关系发生变化,应当及时处理相关缓存。缓存清理不能代替结构版本验证,也不能将旧模板生成的页面数据直接当作最新实例状态。
九、Smarty 表单与前后台交互规范
Smarty 可以负责生成表单、按钮、数据输入区域和交互页面,但表单提交后的业务处理应当由 PHP 后台完成。
例如,智能个体属性编辑页面可以使用 Smarty 生成:
<form method="post" action="/individual/update">
<input
type="hidden"
name="instance_id"
value="{$individual.id|escape}"
>
<label>个体名称</label>
<input
type="text"
name="name"
value="{$individual.name|escape}"
>
<button type="submit">保存</button>
</form>
PHP 接收请求后,应当重新读取实例及其结构定义,检查用户权限,验证属性是否允许修改,再执行数据更新。
不能因为页面中存在某个属性输入框,就认定该属性允许任意修改;也不能因为页面显示某个运行操作按钮,就直接执行对应方法。
对于重要的实例修改、结构调整和方法调用,应当采用适当的请求验证机制,例如 CSRF 防护、身份认证、权限验证、参数检查和操作日志记录。
页面交互结果应当以 PHP 后台的实际处理结果为准。前台显示的成功提示不能代替数据库写入和实例状态更新的实际验证。
十、Smarty 模板安全规范
Smarty 模板虽然主要负责页面呈现,但仍然属于整个工程的安全边界之一。
所有来自用户输入、外部数据源和动态结构数据的展示内容,都应当根据输出位置进行适当转义。普通文本应当采用 HTML 转义,URL 参数应当进行 URL 编码,JavaScript 数据应当采用安全的 JSON 编码方式传递。
模板中不应当直接拼接未经验证的 SQL 语句,也不应当通过模板变量执行任意 PHP 代码。
Smarty 的 PHP 相关功能应当按照项目安全策略进行限制。对于智能个体的动态方法,必须通过 PHP 业务层的受控方法注册机制执行,不能将 Smarty 标签、变量或模板字符串作为动态方法执行入口。
模板文件的修改权限也应当受到控制。普通页面编辑权限不能自动获得修改 PHP 程序、方法注册配置和运行控制逻辑的权限。
十一、Smarty 模板版本与页面维护规范
Smarty 展示模板应当纳入独立的版本管理。模板版本用于记录页面布局、数据变量、组件引用和交互方式的变化。
当页面数据结构发生变化时,应当同步检查对应 Smarty 模板是否仍然能够正确读取数据。新增属性、删除属性或修改数据层级,都可能影响原有页面的变量调用。
对于智能个体结构发生变化的情况,应当先由 PHP 程序完成结构和实例数据的处理,再根据新的实例数据生成页面。Smarty 不应当自行推断结构变化,也不应当直接修改智能个体的结构定义。
页面模板升级后,应当验证基础页面、动态属性页面、个体详情页面、运行状态页面和交互页面,确认变量引用、页面布局、数据转义和权限控制正常。
模板版本与智能模板版本应当分别管理。一个智能模板可以关联多种展示模板,同一种展示模板也可以用于呈现多个不同智能模板生成的实例,但必须保证实际传入的数据符合页面模板的变量约定。
十二、Smarty 工程验证规范
Smarty 模板验证应当与 PHP 程序验证相互配合。
PHP 程序验证重点检查数据读取、业务处理、变量赋值和权限控制;Smarty 模板验证重点检查模板加载、变量调用、模板继承、公共组件、页面生成和输出安全。
工程测试应当使用真实的结构定义和实例数据进行验证,不能仅使用固定演示数据判断动态页面功能已经完成。
对于动态属性呈现,应当使用具有不同属性名称、属性数量和数据类型的实例进行测试;对于页面继承,应当检查基础布局和子模板是否能够正确组合;对于交互页面,应当检查表单提交、后台验证、数据保存和结果反馈是否形成完整过程。
对于运行状态页面,还应当检查页面显示数据与实例真实运行状态是否一致,避免将缓存数据、默认值或模拟数据显示为实际运行结果。
附录二总结
Smarty 模板在 WSaiOS 智能个体构建工程中承担前台动态页面生成和交互呈现职责。通过合理的模板目录组织、PHP 数据赋值、动态变量调用、模板继承、公共组件和页面缓存管理,可以使不同结构、不同属性和不同运行状态的智能个体使用统一的页面呈现机制。
本附录确立的核心工程原则是:PHP 负责业务逻辑、结构数据处理和运行控制,Smarty 负责页面结构、数据呈现和交互入口;WSaiOS 智能模板负责智能个体的结构定义与构建,Smarty 展示模板负责智能个体的前台呈现。
四者之间通过明确的数据接口和调用关系连接,既保持智能个体构建体系的独立性,也保证前台页面能够随着智能个体结构和实例数据的变化进行动态呈现。
