本文档介绍了模块的编写规范，包括模块描述符文件的详细说明、系统模块列表、如何创建及管理模块，以及模块配置文件的各个参数的具体含义。
模块编写规范
目录[隐藏] |
模块描述符文件详解
模板页面中会包含模块，每一个模块都有一个名称为”module.xml”的描述符文件，包含以下信息：
1． 基本信息：名称、版本号、change log，描述、示意图等
2． moudle配置信息：module的元素类型采用html 5中的数据类型，如url, email，number，text,textArea, htmlArea等，这些类型同时包含基本的校验信息
3． 其他等
此处发生细微修改，请设计师认真阅读：
添加了themes、theme标签,详情如下：
<?xml version="1.0" encoding="GBK"?>
<module>
<!—模块ID-->
<id>textbox</id>
<!—模块名称-->
<name>文本块</name>
<!—模块文件-->
<file>textbox.php</file>
<!—模块缩略图-->
<thumbnail>assets/images/textbox.png</thumbnail>
<!—模块描述-->
<description xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">模块简短描述文字</description>
<!—是否开启缓存-->
<requiredCache>true</requiredCache>
<!—坑-->
<supportedWidth>950</supportedWidth>
<!-- 用于标示模块的皮肤 -->
<themes default="default">
<!-- 以当前模板作为根目录的地址 -->
<theme name="default">
<css>assets/stylesheets/default.css</css>
</theme>
<theme name="red">
<css>assets/stylesheets/red.css</css>
</theme>
</themes>
<parameters>
<param name="pic_1" label="轮播①图片地址" ptype="text" formType="text" description="图片尺寸748*298" >../tshop-um-p-950-036/assets/images/image_picture1.jpg</param>
<param name="url_1" label="链接地址" ptype="text" formType="text" description="." >#</param>
</parameters>
<!—模块参数-->
<parameters>
<param name="title" description="标题" type="text">标题-1</param>
<param name="content" description="内容" type="text">内容-1</param>
</parameters>
</module>
模块编写
系统模块
下表为淘宝提供的系统模块，您可以自由在模板中添加。
| 排序标识 | 说明 | 是否默认显示 |
|---|---|---|
| 店铺招牌 | shop.pageBanner | 1.0-common |
| 自定义内容区 | shop.selfDefining | 1.0-common |
| 宝贝推广区（自动） | shop.autoSpread | 1.0-wangpu |
| 宝贝分类 | shop.itemCategory | 1.0-common |
| 搜索店内宝贝 | shop.searchInShop | 1.0-common |
| 搜索店内宝贝头部版 | shop.searchInShopHead | 1.0-common |
| 交流区 | shop.forumShow | 1.0-common |
| 装修模板区 | shop.flashBanner | 1.0-common |
| 掌柜推荐宝贝 | shop.itemRecommend | 1.0-wangpu |
| 友情链接 | shop.friendLink | 1.0-common |
| 搜索列表 | shop.searchList | 1.0-wangpu |
| 宝贝推广区（手动） | shop.manualSpread | 1.0-wangpu |
| 宝贝排行榜 | shop.topList | 1.0-common |
| 图片轮播 | shop.picRound | 1.0-common |
| 文章目录 | shop.fileDir | 1.0-common |
| 文章搜索 | shop.fileSearch | 1.0-common |
| 文章列表 | shop.fileList | 1.0-common |
| 文章列表默认 | shop.fileListDefault | 1.0-common |
| 默认文章目录 | shop.fileDirDefault | 1.0-common |
| 文章详情 | shop.fileDetail | 1.0-common |
创建模块
SDK控制台提供了图形化界面来模块管理功能，方便设计师管理模块信息。功能包括添加模块、删除模块、修改模块。
1. 添加模块
点击“创建新模块”按钮，进入创建模块页面：
模块描述文件表单，其中带*号的不能留空的。填写如下信息:
模块ID：如“my_module”；
模块名称：如“我的模块”；
模块缩略图：填写模块的相对地址，如“assets/images/frontpage.png”；
描述信息：模块的描述信息。
模块类型：选择该模块的类型，默认是系统模块，如上图所示。当选择设计师模块时，显示下图：
模块ID：如“testmb”；
模块名称：如“测试模块”；
模块布局:(当模块类型为设计师模块时才显示)；
模块缩略图：填写模块的相对地址，如“assets/images/frontpage.png”；
模块描述：模块的描述信息。
非法操作的限制如下：
模块名称限制：不能为空，最多8个中文字符。
模块ID限制：不能为空，最长20个英文。
模块缩略图：可以为空。如果不为空的话，文件必须存在，并且不能使用绝对路径（比如D:\ DC_SDK\htdocs\template1\assets\images\my_module.png），并且文件必须为png，jpg或gif图片。
点击“保存”保存模块。保存之后，系统提示创建成功，并为设计师提供了编写规范，如下图：。
点击 返回所有模块，可以看见我们刚新建的模块。如下图：
回顾目录结构，模块文件放置X:\DC_SDK\htdocs\test1234\modules（X表示SDK安装的硬盘盘符，默认是D盘）,如下图所示:
红框箭头指向的地方，在modules目录下建立了一个名为my_module的目录。在SDK后台创建模块时，SDK会根据用户输入模块的ID和系统自带的前缀“Tshop-um-”自动生成模块目录名称。新版SDK，创建模块，设计师模块目录名都会自动生成前缀。请注意，用户如果需要修改模块的ID时，模块目录名称不会随之变化。也就是说，模块的目录名称在创建时就确定了。
打开Tshop-um-testmb目录，会发现两个文件：模块配置文件（module.xml），模块页面文件（module.php)。其中模块页面文件默认是PHP文件（SDK目前只支持PHP页面）,文件名为用户输入模块的ID。
SDK创建模块时，其中，模块描述文件（module.xml）会自动添加XML Schema验证文件，如图中红色框内容。通用的XML编辑器都带有Schema验证，设计师可以更好利用他们来修改模块文件，当然也可以通过GUI修改。
2. 删除模块
此处有细微改变，请设计师认真阅读：
新版SDK，删除模块不会自动备份。（请各位设计师删除的时候小心操作）。
SDK也提供删除模块的功能，被删除的模块不会再在模块信息页面显示。例如，我们想要删除掉新建的模块：我的模块。
在“模块信息页面”的模块管理中，在“我的模块”管理块中，点击“删除”。
点击之后，会有一个弹出框来确认删除。点击“确定”，SDK执行删除模块命令，重新导航到模板信息页面，同时，有红色的删除提示信息：“模块成功地删除，并且备份到了modules_backup目录。”如下图所示：
接下来，看一下模块目录下面的变化。回到modules目录，观察变化：
图中显示，“我的模块”并不在modules目录中了。但它们没有真的删除。SDK提供了一种人性化的模块管理，并不会真正地删除物理文件，而是备份到了改模板的modules_backup目录。
如果设计师需要恢复这个模块的话，可以把它复制（移动）到modules目录。这里，我们把“my_module”（我的模块）在移动到modules目录上面。然后重新查看“模板信息页面”，“我的模块”又会回到模块管理中。如下图所示：
3. 修改模块
此处有细微改变，请设计师认真阅读：
模块ID在新建好了以后是不能通过SDK编辑的，只能通过修改xml文件修改。当然，我们不建议XML编程经验尚浅的设计师手动修改模块的描述文件。
当设计需要调整模块信息时，可以通过“模块管理”中点击相应的模块管理块的“编辑”按钮。以“我的模块”为例，修改模块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中，当参数值number时，返回的仍是字符串，所以各位设计师在做运算的时候不要先用intval进行转换一下。
ptype是参数类型的配置，此参数的目的主要是用于对卖家后台录入参数的校验，目前系统支持的ptype参数类型如下：
• text：文本类型参数，此参数系统默认最多256个字符
• textarea：文本域类型参数，此参数系统默认最多4000个字符
• htmlarea：代表一段html代码，此参数系统默认最多32KB
• url：url类型参数，系统默认最大长度256个字符
• date：此类型代表日期类型，后台会根据制定的日期格式进行校验
• email：此类型代表电子邮件，后台会校验是否是合法的邮件地址
• number：此类型是数值类型，后台会判断是否是合法的数值.
formType：
此处有细微改变，请设计师认真阅读：
当formType为checkbox（多选）时，返回多选的值是以英文逗号的形式分割的。
formType用来配置参数html类型，类型与html类型对应，用于在编辑模块的时候展示界面的DOM结构。目前系统主要支持如下几个类型：
• text: 类似于html的input type=”text”,用于卖家输入文本字段
• textarea:类似于html的textarea标签，用于卖家输入一段文本
• select: 类似于html的select标签，此参数的配置需要通过option来配置，比如写入如下配置：
它的展示效果如下图所示：
扫一扫
1万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
