淘宝模板开发系列之模块编写规范

模块编写规范

模块描述符文件详解

模板页面中会包含模块，每一个模块都有一个名称为”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. 添加模块

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

点击“创建新模块”按钮，进入创建模块页面：

模块描述文件表单，其中带*号的不能留空的。填写如下信息:
模块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来配置，比如写入如下配置：

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