设计师模块开发手册

变更版本号日期变更类型 修改人摘要备注1.02013-11-25新增赵宏波概述1模块管理在sdk首页菜单中点击”我的模块”菜单项，进入模块列表页面，该页面中显示了设计师开发的所有模块列表，并分页显示，每页显示10个模块，在该页面中，可以创建新的模块，或打开模块回收站显示已经被删除的模块。1.1创建模块点击”创建新模块”按钮，将打开创建模块页面，如图所示：输入以下信息：输入项名称作用填写规范模块标识为模块的英文名称，用于生成存储模块基本信息的文件夹以大小写英文字母开头，可以包含：数字、减号和下划线，标识不能重复，最多输入20个字符，建议输入有意义的标识名称，如：ImgBanner模块名称模块的中文名称，用于模块列表在SDK和Jshop平台的显示最多20个字，输入类型不限，建议输入简单明了的名称，如：图片轮播模块缩略图用于模块列表在SDK和Jshop平台的显示支持png、jpg、jpeg、gif格式，尺寸为宽度80px，高度80px，图片不大于300K模块备注用于对模块的简要描述最多200个字符，输入类型不限模块详情用于在Jshop中显示模块详细信息，最好包括模块配置的详细说明信息最多输入32K信息，输入类型不限最后，点击保存按钮，即创建了一个新的模块。 1.2修改模块在”我的模块”列表中，将鼠标悬停至任意模块的图标上，将弹出工具栏，如图所示：点击工具栏上的”编辑”按钮，打开模块编辑页面，在该页面中可以编辑模块的基本信息，模块标识则不能被修改。1.3删除模块在”我的模块”列表中，将鼠标悬停至任意模块的图标上，将弹出工具栏，如图所示：点击工具栏上的”删除”按钮删除该模块，注意：被删除的模块并未真正被删除，可以点击”回收站”找回被删除的模块。2模块开发2.1模块目录结构说明当创建一个模块后，系统会自动生成一系列文件夹，模块的基本信息会按规则保存在通过模块标识指定文件夹下，一个模块对应一个唯一的文件夹。该文件夹结构如下：文件夹说明：Jshop-NewBanner，为当前模块的根文件夹，NewBanner为模块的标识images，用于存放当前模块和模块模板的缩略图themes，用于存放模板的样式，默认样式文件为default.cssview，用于存放模块的数据展示模板，默认模板名称为default.vm生成的默认文件的名称和扩展名均不能手动修改。2.2模块配置描述文件在模块根文件夹下存在一个：module.xml文件，该文件用于描述当前模块的参数配置信息，是模块配置页面生成的重要依据，文件示例内容如下： NewBanner_Fsli 图片轮播 XML节点说明如下：节点名称作用属性列表module根节点，无需编辑无flag模块参数唯一标识，无需编辑无name用于显示模块名称，无需编辑无parameters用于描述模块配置参数，无需编辑无group描述参数分组，可以增加或减少，至少一个grouptitle,loop,listparam描述参数项，可以增加或减少，至少一个paramname,label,ptype,formType,descriptiongroup节点属性说明：名称作用规则title设置分组标题必填 list设置循环变量的名称非必填param节点属性说明：名称作用规则name参数名称必填，只能以英文开头，不能包含空格，可以有数字或下划线，满足变量命名要求label表单项前面的文字说明必填ptype描述输入数据的类型必填formType表单项的类型必填description表单项后面的文字说明非必填value表单项的默认值非必填，设置了value将在该模块的配置页面的表单项中显示value指定的值ptype属性取值说明名称说明text文本数据，最多256个字符number数值类型，可以是整性、浮点型image图片域类型，输入项可以双击弹出图片选择框url链接类型formType属性取值说明名称说明text描述生成textarea描述生成select描述生成可以直接通过Dreamweaver、Notepad+、EditPlus等文本编辑工具对其进行编辑，您可以通过添加一个group来增加一个参数分组，也可以添加一个param节点来增加一个参数，如下： 首页服装城超市 另外一种情况是，针对某些特殊模块，设计师需要提供一组可供用户动态添加或删除的参数组，如：开发友情链接模块，该个模块的输入项有：链接地址、链接标题和链接打开方式，为满足不同的用户可以设置个数不定的友情连接项，需要对参数的group组进行特殊标识。以下描述一组动态的输入项：当前窗口新窗口该配置将生成以下模块配置页面，如图：设置list属性表示模块展示页面用于遍历列表的velocity变量名称，同是表示当前group可以动态添加或者删除如：#foreach($nav in $navList) $!nav.title#end让我们通过一张图片来描述module.xml和模板二者的关系，如下：当前窗口新窗口模板内容：#foreach($nav in $navList) $!nav.title#end相同颜色字体的一一对应。module.xml文件编写注意事项：1、XML节点或属性是大小写敏感的，编写时需要注意大小写2、每个节点必须要有结束符，如或3、属性值中不能包含空格4、XML节点或属性的值，尽量不要包括：&”之类的特殊字符，只能使用其对应的转义出字符。如下表格：原字符转义字符>&“"'2.3模块开发流程及示例模块开发流程如下：2.4模块页面开发一套模块板，由数据展示页面和样式文件组成，当创建一个模块后，系统会自动创建一套默认的模板，包括：default.vm 模块数据展示页面，通过文本编辑器打开编辑。default.css 数据展示页面样式文件。default.jpg 模板缩略图文件。三个文件，分别位于：/模块根目录/view/模块根目录/themes/模块根目录/images/2.5模块页面编写规范模块模板的编写需要遵循velocity规范，什么velocity?，以下是velocity简单入门。变量变量的简略标记是有一个前导$字符后跟一个标识符（Identifier.）组成。变量必须以一个字母开始(a . z或 A . Z)。剩下的字符将由以下类型的字符组成：变量字母 (a . z, A . Z)数字 (0 . 9)下划线 (_)必须以一个字母开始(a . z或 A . Z)。剩下的字符将由以下类型的字符组成下面是一些正确的变量引用：$foo$mudSlinger$mud-slinger$mud_slinger$mudSlinger1$foo$mudslinger$mud-slinger$mud_slinger$mudSlinger1指令velocity指令以#开头#set指令用来为引用设置相应的值。值可以被值派给变量引用或者是属性引用，而且赋值要在括号里括起来。#set($string = “Hello world”)#set($string1 = $string)#set($string2 = $string + $string1)#set($num = 1)#set($total = $num * 2)#set($array = “Hello”, “world”)#if/else/elseif/end指令，条件指令，必须以#end指令结束#if( $foo 10 ) Go North#elseif( $foo = 10 ) Go East#elseif( $bar = 6 ) Go South#else Go West#end#set($name = “Mr right”)#if($name = “Mr right”)Hello $Mr rightHello $!Mr rightHello $Mr rightHello $!Mr right#end判断是否有这个变量（或变量是否为null）#if($foo)$foo#elsenothing#end#foreach() #end循环指令，用于遍历一个数组，Map或列表循环输出一个数组#set($array = “1”, “2”, “3”)#foreach($a in $array)$a#end循环输出列表#set($skus = $skuIdList)#set($productList = $productManager.getProductList($skus)#foreach($product in $ productList)$product.warename#end循环输出Map#foreach( $key in $allProducts.keySet() ) Key: $key - value: $allProducts.get($key)#end计算1到100的和#set($total = 0)#foreach($i in 1.100)#set($total = $total + $i)#endtotal:$total连接字符串#set($result = “”)#set($array = “Hello”, “Good bye”, “Thank you”)#foreach($str in $array)#set($result = $result + “,” + $str)#end$result获取对象属性velocity属性引用，注意，属性具体固定的格式，它也是以$开头，并且是合法的变量标识符，随后是变量属性”变量名称.变量属性”，如下格式：$product.warename$product.getWarename()#set( $test = name:car, color:red)#foreach($member in $test.entrySet()$member.key - $member.value#end#foreach($member in $test.keySet()$member - $test.get($member)#end安静引用符当velocity 遇到一个位定义的引用时，其通常行为是输出这个引用的映像。比如，假设下面的引用出现在模板中的一部分：当表单初次装入时，变量引用$email无值，你宁愿是一个空白域而不是具有值$email。使用安静引用符可以绕过velocity的常规行为，在velocity中不用$email而是用$!email 符号。所以，上面的例子将会看起来像下面的样子：现在，当表单初次装入时， $email 仍然没有值，但是将输出空字符串而不是$email。形式和安静引用符可以一起使用，如下所示：2.6常见问题1、置入模块时报以下错误？A：该问题原因为：模板vm、css未按规定编写，或者module.xml文件格式有误导致，请先在模块列表中点击”校验”按钮，待校验通过以后再置入，另请参照模块模板编写规范2、创建了一个新的模板后，在装修页面中点击设置按钮，点击模板标签无法看到最新添加的模板？A：在装修页面中，把这个模块重新置入一次即可。3、一套店铺模板中最多可以添加几个设计师模块？A：最多3个，否则，在店铺模板打包时无法通过打包。4、通过编辑模块页面，修改了模块的缩略图，返回模块列表页面后图片为什么没改变？A：实际上图片已改变，需要按ctrl + f5强制刷新页面才能生效。3开放服务接口在编写模块页面时，可以使用以下默认vm变量：变量名称说明$!cms_app_id应用ID$!domainKey店铺域名$!shopId店铺ID$!venderId商家ID为避免与这些内容变量发生冲突，建议在编写module.xml文件时，param节点的name属性尽量加上前缀，如：dmTitle3.1商品分类服务服务说明服务方法：$categoryService.getAllCategory()说明：获取商家店铺的所有分类信息列表参数：无服务方法：$categoryService.getParentCategoryList()说明：获取商家店铺的所有一级分类信息列表参数：无服务方法：$categoryService.getSubCategoryList(parentId)说明：根据商家店铺一级分类ID获取子分类信息列表参数：parentId，父分类ID参数类型：整型3.1.2属性说明分类属性名称说明id分类IDshopId所属店铺IDparentId父分类IDtitle分类名称imgUrl分类ICON图片地址childs子分类列表3.1.3使用详解获取商家店铺的所有一级分类信息列表#set($parentCagegoryList = $categoryService.getParentCategoryList ()一级分类#foreach($category in $parentCagegoryList)$!category.title#end获取商家店铺的所有分类信息列表#set($shopCagegoryList = $categoryService.getAllCategory() #foreach($categoryItem in $shopCagegoryList) $!categoryItem.title #if($categoryItem.childs & $categoryItem.childs.size() 0) #foreach($childItem in $categoryItem.childs) $!childItem.title #end #end #end3.2商品服务服务说明服务方法：$productService.getProductBySkuId(skuId)说明：根据skuId获取商品信息参数：skuId，商品编号参数类型：字符串服务方法：$productService.getProductListBySkuIds(skuIds)说明：根据skuId串获取商品列表，多个sku使用半角逗号分隔参数：skuIds，商品编号串参数类型：字符串服务方法：$productService.getProductListByCateId(cateId)说明：根据skuId串获取商品列表，多个sku使用半角逗号分隔参数：cateId参数类型：整型服务方法：$productService.getProductList(cateId,orderBy,directon,pageNo,pageSize)说明：分页获取商品列表信息参数说明：cateId，整形，分类id，分类id为0时，表示查询店铺内所有商品orderBy，整型，排序字段，1表示上架时间，2表示评论数，3表示好评度，4表示价格，5表示销量directon，整型，排序方向，0表示升序，1表示降序pageNo，当前页码pageSize，每页显示条数调用示例：$productService.getProductList(0,1,0,1,24)3.2.2属性说明商品属性名称说明waridSKUIDimageurl商品图片地址warename商品名称cid1name一级分类名称cid2name二级分类名称catname三级分类名称wfacturer品牌名称commentcount评论数good好评数winsdate上架时间sale商品7日销量stock1：有货，0：无货3.2.3使用详解根据sku id串获取商品列表信息，多个sku之间使用半角的逗号分隔#set($p = $productService.getProductBySkuId(100012)$p.warename根据sku id获取单个商品信息#set($productList = $productService.getProductListBySkuIds(100012,100935)#foreach($p in $productList)$p.warename#end根据店铺分类ID获取商品列表信息#set($productList = $productService.getProductListByCateId(110)#foreach($p in $productList)$p.warename#end分页获取店铺商品信息#set($productResult = $productService.getProductList(0,1,0,$pageNo,10)分页获取商品#foreach($p in $productResult.getList()$p.warename #end $!popProduct.getPageBar($!cms_app_id, 0, 1, 1, $!pageNo, $productResult.pageSize, $productResult.totalCount, $productResult.pageCount,$!domainKey)