SDK模板-模块编写规范

模块描述符文件详解

模板页面中会包含模块，每一个模块都有一个名称为”module.xml”的描述符文件，包含以下信息：

1． 基本信息：名称、版本号、change log，描述、示意图等

2． moudle配置信息：module的元素类型采用html 5中的数据类型，如url, email，number，text,textArea, htmlArea等，这些类型同时包含基本的校验信息

3． 其他等

<?xml version="1.0" encoding="GBK"?>

<module>

<!—模块ID-->

<id>textbox</id>

<!—模块名称-->

<name>文本块</name>

<!—模块文件-->

<file>textbox.php</file>

<!—模块缩略图-->

<thumbnail>assets/images/textbox.png</thumbnail>

<!—模块参数-->

<parameters>

<param name="title" description="标题" type="text">标题-1</param>

<param name="content" description="内容" type="text">内容-1</param>

</parameters>

</module> 模块编写

系统模块

下表为淘宝提供的系统模块，您可以自由在模板中添加。

创建模块

SDK控制台提供了图形化界面来模块管理功能，方便设计师管理模块信息。功能包括添加模块、删除模块、修改模块。

1. 添加模块

启动SDK之后，通过点击“我的模板”，选择相应的模板。以“xiaohu”的模板为例，进入模板的详细页面。在页面的下方将看到模块列表，如下图所示：

图中，红色部分是模块缩略图（大小为50x50像素），蓝色部分是模块的名称。 点击“创建新模块”按钮，进入创建模块页面：

模块描述文件表单，其中带*号的不能留空的。填写如下信息: 模块名称：如“我的模块”； 模块ID：如“my_module”；

模块缩略图：填写模块的相对地址，如“assets/images/frontpage.png”； 模块描述：模块的描述信息。

非法操作的限制如下：

模块名称限制：不能为空，最多8个中文字符。 模块ID限制：不能为空，最长20个英文。

模块缩略图：可以为空。如果不为空的话，文件必须存在，并且不能使用绝对路径（比如D:\ DC_SDK\htdocs\template1\assets\images\my_module.png），并且文件必须为png，jpg或gif图片。

点击“保存”保存模块。保存之后，页面自动导航模块详情页。

回顾目录结构，模块文件放置X:\DC_SDK\htdocs\template1\modules（X表示SDK安装的硬盘盘符，默认是D盘）,如下图所示。

红框部分显示，在modules目录下建立了一个名为my_module的目录。在SDK后台创建模块时，SDK会根据用户输入模块的ID作为新建模块目录的名称。请注意，用户如果需要修改模块的ID时，模块目录名称不会随之变化。也就是说，模块的目录名称在创建时就确定了。

打开my_module目录，会发现两个文件：模块配置文件（module.xml），模块页面文件（my_module.php)。其中模块页面文件默认是PHP文件（SDK目前只支持PHP页面），文件名为用户输入模块的ID。

SDK创建模块时，其中，模块描述文件（module.xml）会自动添加XML Schema验证文件，

如图中红色框内容。通用的XML编辑器都带有Schema验证，设计师可以更好利用他们来修改模块文件，当然也可以通过GUI修改。

2. 删除模块

SDK也提供删除模块的功能，被删除的模块不会再在模块信息页面显示。例如，我们想要删除掉新建的模块：我的模块。

在“模块信息页面”的模块管理中，在“我的模块”管理块中，点击“删除”。

点击之后，会有一个弹出框来确认删除。点击“确定”，SDK执行删除模块命令，重新导航到模板信息页面，同时，有红色的删除提示信息：“模块成功地删除，并且备份到了modules_backup目录。”如下图所示：

接下来，看一下模块目录下面的变化。回到modules目录，观察变化：

图中显示，“我的模块”并不在modules目录中了。但它们没有真的删除。SDK提供了一种人性化的模块管理，并不会真正地删除物理文件，而是备份到了改模板的modules_backup目录。

如果设计师需要恢复这个模块的话，可以把它复制（移动）到modules目录。这里，我们把“my_module”（我的模块）在移动到modules目录上面。然后重新查看“模板信息页面”，“我的模块”又会回到模块管理中。如下图所示：

3. 修改模块

当设计需要调整模块信息时，可以通过“模块管理”中点击相应的模块管理块的“编辑”按钮。以“我的模块”为例，修改模块ID为：my_module_1 和模块描述：我的模板的描述,添加描述，然后保存。

修改后，查看“我的模块”的module.xml文件。内容如下：

其中，红框部分所示的为修改后的内容变化。

设计师可以修改参数来调整模块信息，也可以通过手动修改module.xml文件。请注意在手动修改时，如果设计师任意地修改它，即没有根据模块Schema文件（module.xsd）的规则的话，模块会被SDK丢弃（忽略）。

打开“我的模块”的module.xml文件。修改description内容，如下：

保存之后，再次进入“编辑”，可发现内容已自动更新。

我们不建议XML编程经验尚浅的设计师手动修改模块的描述文件。

模块配置说明

module.xml的内容如下：

下面是对module.xml的一些介绍：

id: 模块标识，这里可以为任意字符串，但是要确保模板内的模块不要出现id相同的情况。

name：模块名称，主要是方便卖家进行模块选择

file：对应的php文件

thumbnail：模块的缩略图，64x64，方便卖家进行模块选择

description：模块描述

parameters：模块的渲染的基本流程为读取参数，调用底层服务，结合php文件输出html，所以参数是模块和卖家交互的重要部分。

不要用table来充当模块，否则效果将不明显或报错

module.xml配置文件的格式如下：

下面详细描述模块配置文件每个参数的含义：

id: id用来唯一的标识某一个模块，在引入模块的时候会通过此ID来引入模块，在同一个模板中，模块ID不能重复。

name: name代表模块的名称，此名称是为了卖家在后台添加模块的时候提示卖家对应的模块名称。 file: file用来配置模块对应的php文件，此配置必须和模块的php文件同名，此项配置需要模块的后缀名。

thumbnail: thumbnail用来配置模块缩略图，模块缩略图在卖家添加模块的时候显示。 description: description用来配置模块描述。

param:param用来配置模块参数，配置的模块参数可以用来让卖家设置，参数设置中有如下几个参数需要配置：

name: 参数名称用于在模板中通过$_MODULE[name]来引用 label: 用于在编辑模块的时候显示，方面卖家后台设置 description:用于参数描述，此参数用于以后扩展

ptype:ptype是参数类型的配置，此参数的目的主要是用于对卖家后台录入参数的校验，目前系统支持的ptype参数类型如下：

text：文本类型参数，此参数系统默认最多256个字符 textarea：文本域类型参数，此参数系统默认最多4000个字符 htmlarea：代表一段html代码，此参数系统默认最多32KB url：url类型参数，系统默认最大长度256个字符

date：此类型代表日期类型，后台会根据制定的日期格式进行校验 email：此类型代表电子邮件，后台会校验是否是合法的邮件地址 number：此类型是数值类型，后台会判断是否是合法的数值.

formType：formType用来配置参数html类型，类型与html类型对应，用于在编辑模块的时候展示界面的DOM结构。目前系统主要支持如下几个类型： text: 类似于html的input type=”text”,用于卖家输入文本字段 textarea:类似于html的textarea标签，用于卖家输入一段文本

select: 类似于html的select标签，此参数的配置需要通过option来配置，比如写入如下配置：

它的展示效果如下图所示：

本文来源：https://www.bwwdw.com/article/tcai.html