SDK教程 模版.doc

1.4 SDK的目录结构 首先以设计师身份从淘宝店铺装修市场下载SDK安装包（Windows版或者Mac版），然后将安装包解压到任何一个本地磁盘目录：解压后的目录结构如下图所示： 各个目录的作用如下： bin目录： bin目录主要放置启动和关闭SDK Server的脚本命令 conf 目录： conf 目录主要存放SDK的配置文件以及SDK web控制台的war应用 db目录： db目录主要存放SDK本体模拟数据文件，设计师设计的模板在本地渲染的时候，数据就是从此目录的文件中读取的。 htdocs目录： htdocs目录存放设计师设计的模板文件，这个目录下可以存放多套模板文件 jre目录 jre是SDK运行的Java环境。SDK Windows版本会绑定JRE，而Mac版则没有这一目录。Mac已经提供了默认的Java运行环境 lib 目录 lib目录主要存放SDK运行所需要的jar包 logs目录 logs目录主要存放SDK运行的日志文件 temp目录 temp 目录中存放已经制作好的的SDK模板的zip包，设计师制作模板之后，通过SDK后台打包生成的zip文件就放在该目录下。 index.php：首页 articleList.php：文章列表页 article.php：文章页面 searchList.php：搜索列表页 onsale.php：促销页面 detail.php：宝贝详情页 header.php：头部 footer.php：尾部 site.xml：模板描述符文件。配置和管理模板和模块。TODO:后面的章节会详细提到。 assets目录：同时包括images和stylesheets两个子目录，静态资源引用需要以相对路径为准。例如： images目录：存放图片等静态文件。 stylesheets目录：存放页面的渲染CSS文件，默认存放着名为global.css的全局样式文件。 modules目录：管理和配置模块下来需要做的就是在php文件中编写具体的模块代码，配置模块信息，模块的参数。 4.2 编写模块代码 4.2.1 引入标识 模块代码要能够被JS识别为模块，以便进行装修操作，设计师需要引入在模块的html代码中引入模板规范约定的标识符J_TBOX, 以及输出用以在装修中操作模块编辑删除，移动的Toolbar，具体代码示例如下： div class=box J_TBox /模块内部代码 4.3 配置模块信息 写完模块的PHP代码之后，需要对模块进行进一步的配置，以方便在模板范围内使用模块。模块的配置信息都是在每个模块目录下module.xml中。 模块的基本信息配置： side_sales 左侧促销 side_sales.php /assets/images/frontpage.png 测试模块 ID:模块的标识，用以引用模块（后面章节会详细讲），通常建议该ID同模块的目录名和模块的php文件名同名。 Name：模块名称，卖家在添加模块的时候，会在模块选择区域中显示。 File：模块的php文件，相对于模块的当前目录。 Thumbnail：模块的缩略图，会在模块选择区域中显示。 Description：模块功能表述，会在模块选择区域中显示。 以上是模块的基本配置信息，保证了模块的正常运行，为了进一步扩展模块功能，可以配置模块支持的参数。示例配置如下： http:/aaa /tps/i3/T1OaRJXaJxXXXXXXXX-160-160.png http:/aaa /tps/i3/T1OaRJXaJxXXXXXXXX-160-160.png http:/aaa /tps/i3/T1OaRJXaJxXXXXXXXX-160-160.png J_TRegion 表示一个区域, 那卖家就可以在装修店铺添加模块。 J_TBox 表示一个模块. 模块内部代码开发者可以完全自定义。 下面从伪代码的方式来看看基本的DOM结构情况： 淘宝页头 /div 淘宝页尾 引入单个模块 模块不一定是放在片区中的，模块可以单个引入，片区中的模块我们认为是非常灵活的模块，可以被卖家从片区中删除，可以在片区中移动，可以从一个片区拖动到另外的片区。但是有时候，我们希望模块不能编辑和删除，但是可以进行编辑，这时候，我们就是可以使用单个方式引入模块，模块有两种，系统模块和自定义模块，分别提供了两种方式来单独引入模块。 引入系统模块： 使用系统函数include_system_module来引入模块，函数接受三个参数，分别是系统模块的缩量名，系统模块的版本号，domId。 引入设计师自定义的模块： 函数接受两个参数，自定义模块的id和domId。 需要特别说明一下domId，domId可以是一串字符串，要求当前页面以及头尾domId不重复。可能很多设计师会很纳闷为什么需要domId，同样一个模块可以多次引入，每次引用就是一份实例，为了能够区分不同的模块实例，我们引入了domId的概念。当然，如果你觉得domId使用起来太过繁琐，我们提供了兼容方法，引入模块不需要指定domId，实际上引擎会根据各个模块的引入顺序自动地计算出domId而无需设计手动指定，但是当模板升级了，不同的版本模板引入顺序不同了，就会导致数据混乱。如果设计师手动指定domId有利于模板后期升级，所以我们建议引入模块最好手动指定domId。 不适用指定domId，我们的引入方式是： 划分页面片区 除了单独引入模块而外，我们可以将页面划分成不同的片区，片区就意味着卖家可以向其中添加模块，可以是系统模块也可以是设计师编写的模块。片区中的模块允许移动，删除，编辑。设计师在页面中定义一个片区的方法很简单，需要使用class名J_TRegion来划分片区的范围，同时在J_TRegion中使用php系统函数include_modules来包含片区中的默认模块。例如示例代码： shop.picRound, version = 1.0-common, domId = index-01), array(id = floor, domId = index-200), / 自定义模块 array(shortname = shop.manualSpread, version = 1.0-wangpu, domId = index-02), array(shortname = shop.searchInShop, version = 1.0-common, domId = index-03), array(id = floor, domId = index-201), / 自定义模块 array(shortname = shop.itemRecommend, version = 1.0-wangpu, domId = index-04), array(shortname = shop.flashBanner, version = 1.0-common, domId = index-05), array(shortname = shop.forumShow, version = 1.0-common, domId = index-06), array(id = quick_join, domId = index-202) / 自定义模块 ); echo include_modules(main-modules, $main_modules); ? 在示例代码中，我们定义了区块，利用数据结构定义了需要默认引入到坑中的模块列表，这些模块包括了自己定义的模块，也包括了系统模块，并且使用include_modules函数将默认模块引入进来，制定片区的名称为main-modules。（为了进一步简化片区的定义方法，我们将在SDK中提供新的php函数，而不需要设计师手动使用J_TRegion来制定坑范围）5.2.3 配置页面信息 编写了模块，撰写的页面代码之后，我们需要配置页面进行配置，以方便渲染引擎识别页面及页面类型，方便装修系统制定规则。页面不像模块一样拥有独立的配置文件，页面的配置信息均集中在site.xml中，设计师设计的所有的页面类型都需要在site.xml中配置。 页面的基础信息配置 我们以首页为例，看看首页该如何配置 首页 index.php assets/images/index.png 首页 在site.xml的site下的pages节点内，具体配置每个页面。 Type：页面的类型，风别对应淘宝店铺页面所展现出来的页面类型，包括：首页（index），宝贝详情页面（detail），宝贝列表页面（list），文章详情页面（article），文章列表页面（articleList），自定义页面（other）。 Name：页面的名称 file：页面的php文件路径相对当前模板的根目录 thumbnail：页面的缩略图 description：页面的描述 配置片区模块规则 通常来说配置了以上信息，设计师在模板中设计的页面就可以使用了。但如果我们在页面中设置了片区，我们想要精确的控制每个片区中能够添加哪些模块，我们就需要进一步配置页面片区的具体规则，来确保指定的片区中只能添加指定的模块。下面来看具体的配置代码： 在page节点下面，我们配置以上代码，就是指定了名为sub-modules的坑中，支持添加的模块有四个。 6.1 宝贝详情页面 宝贝详情页面目前开放程度是比较低的，不能够完全由设计师来设计，在原有的宝贝详情页面的整体布局之下，开放了两个区域供设计师来设计。一个左栏区域，一个右栏区域。所以在配置上宝贝详情页面与首页有所不同。宝贝详情页面的配置如下： 宝贝详情页 detail.php assets/images/detail.png 宝贝详情页 detail_left.php detail_right.php 宝贝详情页面需要三个php文件，detail.php作为文件占位符，设计师不需要对其中的内容作设计，设计师需要做设计的是detial_left.php和detail_right.php分别对应了两个区块的东西，渲染引擎将对应的两个区域分别填充到宝贝详情页面的骨架上。 6.2 宝贝列表，文章列表页面 宝贝列表页面和文章列表页面有着共同的要求，该页面中需要引入包含宝贝搜索列表模块和文章搜索列表模块。 6.3 不可装修的页面 另外除了以上的页面规则而外，还有很多页面，评能够价页面，交流区页面，货到付款 SDK2模块描述符文件详解 模板页面中会包含模块，每一个模块都有一个名称为”module.xml”的描述符文件，包含以下信息：1 基本信息：名称、版本号、change log，描述、示意图等2 moudle配置信息：module的元素类型采用html 5中的数据类型，如url, email，number，text,textArea, htmlArea等，这些类型同时包含基本的校验信息3 其他等 textbox 文本块 textbox.php assets/images/textbox.png 标题-1 内容-1 模块编写 系统模块下表为淘宝提供的系统模块，您可以自由在模板中添加。模块名称 模块简称 模板版本号 店铺招牌 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 红框部分显示，在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修改。其中，红框部分所示的为修改后的内容变化。设计师可以修改参数来调整模块信息，也可以通过手动修改module.xml文件。请注意在手动修改时，如果设计师任意地修改它，即没有根据模块Schema文件（module.xsd）的规则的话，模块会被SDK丢弃（忽略）。打开“我的模块”的module.xml文件。修改description内容，如下：模块配置说明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: 参数名称用于在模板中通过$_MODULEname来引用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来配置，比如写入如下配置：checkbox:类似于html的checkbox。 简易模板开发流程 高级模板开发流程代码规范 模板编写规范 模块编写规范 DOM、CSS规范 HTML规范 Widget规范模板目录结构 模板目录结构是指模板各个资源目录划分，如下图：插入图片：模板详细目录结构目前主要分为已下记录类： 静态资源：都存放在assets目录，同时包括images和stylesheets两个子目录，静态资源引用需要以相对路径为准。 模板文件：也就是模板文件，后缀名为.php或者.vm，依据所选择的模板语言，模板文件包括全局头，全局尾和各个文件的主体。页面文件不能形成子目录。 模块文件：不能包含其他资源文件，如果包含其他资源文件，需要来自淘宝相册的服务，模块主要就是模块的配置文件和其模块主体文件 元信息文件：如xml文件，screenshot文件等，模板为site.xml，模块为module.xml 在SDK中，htdocs可以同时包括多个模板，以不同的目录加以区分，SDK会自动识别这些模板并进行管理，如样例中的template1是模板的名称。 在htdocs的根目录下有一个dcsdk_functions.php的文件，所有SDK提供的函数都会在这里列出；还有一个site.xsd，这个是site.xml的xml schema文件，主要是辅助进行site.xml编辑。模板描述符文件详解 模板是超级旺铺的基础，主要是模板、模板版本、配置和资源这四项，每一个模板都有一个名称为site.xml的描述文件，包含一下信息： 基本信息：如模板语言、名称、描述、作品截图、作者、支持的网站、服务方式等 模板全局信息：如全局css，全局的页面header和footer等 风格信息：模板所包含的风格，都要在元素下进行声明 页面信息：一个模板包含多个页面，每一个页面的具体功能要说明清楚，如店铺的模板页面，那个是首页，那个是详情页等，都需要进行描述 模块信息：该模板所包含的模块以及各个模块的详细信息 参数信息：如果模板、页面和模块需要参数，这个参数是什么类型的，form该如何交互，这些也需要明确 2cd2659796794dbab1e4115dac7facf3 模板-1 Jacky assets/images/frontpage.png php 2010050901 change log description here header.php footer.php assets/stylesheets/global.css green assets/images/green.jpg /assets/stylesheets/green.css demo green 首页 index.php untitled 宝贝详情页 detail.php 文章页面 article.php 促销页面 onsale.php 出于XML编写的方便，SDK为site.xml提供了XSD，只需要一个XML Editor就可以完成XML校验和相关的代码提示。模板编写 在模板中的模块都是集中在模板标准目录的modules目录中，可先参看模块编写规范 1. 引入模块模块有两种类型，分别是系统模块和设计师自定义模块，下面分别说明如何引入系统模块和设计师自定义模块： 引入系统模块 其中include_system_module需要三个参数，第一个为“系统模块简称”，第二个为“系统模块版本”，第三个为domId,这里需要注意的是domId需要在页面内唯一。 引入自定义模块 其中include_local_module有两个参数，第一个”textbox”为模块的名称，第二个为domId,这里需要注意的是domId需要在页面内唯一。2. 引入片区片区是设计师在页面预留的一块区域，卖家可以在坑里添加模块，具体引入坑的语法如下： shop.topList,version=1.0-common,domId=001); $selfModule=array(id=selfModule,domId=001); $modules=array($topList, $selfModule); echo include_modules(testModules, $modules) echo include_system_module(shop.searchInShop,1.0-common,002) ?其中include_modules包含两个参数，第一个参数是片区对应的名称,第二个参数是片区里面引入的默认模块列表。引入片区需要注意以下几点：1. 片区需要通过“J_TRegion”这个class来标识.2. 片区里面也可以引入系统模块和引入自定义模块 “J_TRegion”外模块引用规范高级模板支持“J_TRegion（坑，片区）”外的模块，但线上目前会存在“片区”外模块丢失的问题；此问题预计在4月中旬修复。片区外的模块的支持，只限于支持单个引用,即只能使用include_system_module, include_local_module进行单个模块引入。使用include_modules 引入的模块在编辑的时候将被丢失。 如具体例子如下图所示： “J_Region内模块的引用支持单个模块和多个模块但目前线上使用include_local_module, include_system_module的进行单个引入的模块在编辑都会丢失。此故障预计4月中解决。同时设计师不被鼓励将include_local_module, include_system_module 与include_modules连续使用。设计师更应该遵守不连续使用include_modules的约定。所有连续使用这样的代码引入的模块都可能存在丢失或者莫名奇妙增加的问题。如下图所示3. 模板中加入模块配置设计师经常会遇到这样的问题：在模板挖了坑，但是没有办法控制坑中能够添加哪些模块。现在在SDK模板中加入了新的配置规则，允许设计师精确配置自己坑中所支持的模块。示例配置如下： 9bb679384bb64c59be4f23ca37b6bcf7 xiaohu assets/images/frontpage.png php 1.0.0 3,7 change log description demo green header.php footer.php assets/stylesheets/global.css gray /assets/images/frontpage.png assets/stylesheets/gray.css 首页 index.php assets/images/index.png sjgjweogj 在site节点下的rules中配置通用的模块和头部尾部模块，在page节点下的rules中配置具体页面下坑中支持的模块。通用模块的配置不需要指定坑的名称，头，尾，页面中的模块配置需要指定到页面中的具体的坑名。具体坑中支持哪些模块的计算方式是，通用配置集合与当前坑模块集合的并集。模块配置支持系统模块和设计师自定义的模块两种模块类类型。4. 宝贝详情页设计宝贝详情页和其他页面不同，主要是设计师不再是设计整个页面，而是设计局部页面，这个主要是出于买家的统一感受。对于宝贝详情页来说，配置信息如下：这里需要设置一个宝贝详情文件名称，目前这个文件不需要设置任何内容，留空即可，但是一定需要一个文件，主要是URL定位和以后的扩展，还有你需要设置两个section，名称分别为left和right，不