設(shè)計(jì)師模塊開發(fā)手冊(cè)

1、變更版本號(hào)日期變更類型 修改人摘要備注1.02013-11-25新增趙宏波概述1模塊管理在sdk首頁菜單中點(diǎn)擊”我的模塊”菜單項(xiàng)，進(jìn)入模塊列表頁面，該頁面中顯示了設(shè)計(jì)師開發(fā)的所有模塊列表，并分頁顯示，每頁顯示10個(gè)模塊，在該頁面中，可以創(chuàng)建新的模塊，或打開模塊回收站顯示已經(jīng)被刪除的模塊。1.1創(chuàng)建模塊點(diǎn)擊”創(chuàng)建新模塊”按鈕，將打開創(chuàng)建模塊頁面，如圖所示：輸入以下信息：輸入項(xiàng)名稱作用填寫規(guī)范模塊標(biāo)識(shí)為模塊的英文名稱，用于生成存儲(chǔ)模塊基本信息的文件夾以大小寫英文字母開頭，可以包含：數(shù)字、減號(hào)和下劃線，標(biāo)識(shí)不能重復(fù)，最多輸入20個(gè)字符，建議輸入有意義的標(biāo)識(shí)名稱，如：ImgBanner模塊名稱模塊的中

2、文名稱，用于模塊列表在SDK和Jshop平臺(tái)的顯示最多20個(gè)字，輸入類型不限，建議輸入簡單明了的名稱，如：圖片輪播模塊縮略圖用于模塊列表在SDK和Jshop平臺(tái)的顯示支持png、jpg、jpeg、gif格式，尺寸為寬度80px，高度80px，圖片不大于300K模塊備注用于對(duì)模塊的簡要描述最多200個(gè)字符，輸入類型不限模塊詳情用于在Jshop中顯示模塊詳細(xì)信息，最好包括模塊配置的詳細(xì)說明信息最多輸入32K信息，輸入類型不限最后，點(diǎn)擊保存按鈕，即創(chuàng)建了一個(gè)新的模塊。 1.2修改模塊在”我的模塊”列表中，將鼠標(biāo)懸停至任意模塊的圖標(biāo)上，將彈出工具欄，如圖所示：點(diǎn)擊工具欄上的”編輯”按鈕，打開模塊編輯頁

3、面，在該頁面中可以編輯模塊的基本信息，模塊標(biāo)識(shí)則不能被修改。1.3刪除模塊在”我的模塊”列表中，將鼠標(biāo)懸停至任意模塊的圖標(biāo)上，將彈出工具欄，如圖所示：點(diǎn)擊工具欄上的”刪除”按鈕刪除該模塊，注意：被刪除的模塊并未真正被刪除，可以點(diǎn)擊”回收站”找回被刪除的模塊。2模塊開發(fā)2.1模塊目錄結(jié)構(gòu)說明當(dāng)創(chuàng)建一個(gè)模塊后，系統(tǒng)會(huì)自動(dòng)生成一系列文件夾，模塊的基本信息會(huì)按規(guī)則保存在通過模塊標(biāo)識(shí)指定文件夾下，一個(gè)模塊對(duì)應(yīng)一個(gè)唯一的文件夾。該文件夾結(jié)構(gòu)如下：文件夾說明：Jshop-NewBanner，為當(dāng)前模塊的根文件夾，NewBanner為模塊的標(biāo)識(shí)images，用于存放當(dāng)前模塊和模塊模板的縮略圖themes，用于

4、存放模板的樣式，默認(rèn)樣式文件為default.cssview，用于存放模塊的數(shù)據(jù)展示模板，默認(rèn)模板名稱為default.vm生成的默認(rèn)文件的名稱和擴(kuò)展名均不能手動(dòng)修改。2.2模塊配置描述文件在模塊根文件夾下存在一個(gè)：module.xml文件，該文件用于描述當(dāng)前模塊的參數(shù)配置信息，是模塊配置頁面生成的重要依據(jù)，文件示例內(nèi)容如下： NewBanner_Fsli 圖片輪播 XML節(jié)點(diǎn)說明如下：節(jié)點(diǎn)名稱作用屬性列表module根節(jié)點(diǎn)，無需編輯無flag模塊參數(shù)唯一標(biāo)識(shí)，無需編輯無name用于顯示模塊名稱，無需編輯無parameters用于描述模塊配置參數(shù)，無需編輯無group描述參數(shù)分組，可以增加或減

5、少，至少一個(gè)grouptitle,loop,listparam描述參數(shù)項(xiàng)，可以增加或減少，至少一個(gè)paramname,label,ptype,formType,descriptiongroup節(jié)點(diǎn)屬性說明：名稱作用規(guī)則title設(shè)置分組標(biāo)題必填 list設(shè)置循環(huán)變量的名稱非必填param節(jié)點(diǎn)屬性說明：名稱作用規(guī)則name參數(shù)名稱必填，只能以英文開頭，不能包含空格，可以有數(shù)字或下劃線，滿足變量命名要求label表單項(xiàng)前面的文字說明必填ptype描述輸入數(shù)據(jù)的類型必填formType表單項(xiàng)的類型必填description表單項(xiàng)后面的文字說明非必填value表單項(xiàng)的默認(rèn)值非必填，設(shè)置了value將在

6、該模塊的配置頁面的表單項(xiàng)中顯示value指定的值ptype屬性取值說明名稱說明text文本數(shù)據(jù)，最多256個(gè)字符number數(shù)值類型，可以是整性、浮點(diǎn)型image圖片域類型，輸入項(xiàng)可以雙擊彈出圖片選擇框url鏈接類型formType屬性取值說明名稱說明text描述生成textarea描述生成select描述生成可以直接通過Dreamweaver、Notepad+、EditPlus等文本編輯工具對(duì)其進(jìn)行編輯，您可以通過添加一個(gè)group來增加一個(gè)參數(shù)分組，也可以添加一個(gè)param節(jié)點(diǎn)來增加一個(gè)參數(shù)，如下： 首頁服裝城超市 另外一種情況是，針對(duì)某些特殊模塊，設(shè)計(jì)師需要提供一組可供用戶動(dòng)態(tài)添加或刪除

7、的參數(shù)組，如：開發(fā)友情鏈接模塊，該個(gè)模塊的輸入項(xiàng)有：鏈接地址、鏈接標(biāo)題和鏈接打開方式，為滿足不同的用戶可以設(shè)置個(gè)數(shù)不定的友情連接項(xiàng)，需要對(duì)參數(shù)的group組進(jìn)行特殊標(biāo)識(shí)。以下描述一組動(dòng)態(tài)的輸入項(xiàng)：當(dāng)前窗口新窗口該配置將生成以下模塊配置頁面，如圖：設(shè)置list屬性表示模塊展示頁面用于遍歷列表的velocity變量名稱，同是表示當(dāng)前group可以動(dòng)態(tài)添加或者刪除如：#foreach($nav in $navList) $!nav.title#end讓我們通過一張圖片來描述module.xml和模板二者的關(guān)系，如下：當(dāng)前窗口新窗口模板內(nèi)容：#foreach($nav in $navList) $!n

8、av.title#end相同顏色字體的一一對(duì)應(yīng)。module.xml文件編寫注意事項(xiàng)：1、XML節(jié)點(diǎn)或?qū)傩允谴笮懨舾械?，編寫時(shí)需要注意大小寫2、每個(gè)節(jié)點(diǎn)必須要有結(jié)束符，如或3、屬性值中不能包含空格4、XML節(jié)點(diǎn)或?qū)傩缘闹?，盡量不要包括：&”之類的特殊字符，只能使用其對(duì)應(yīng)的轉(zhuǎn)義出字符。如下表格：原字符轉(zhuǎn)義字符>&“"'2.3模塊開發(fā)流程及示例模塊開發(fā)流程如下：2.4模塊頁面開發(fā)一套模塊板，由數(shù)據(jù)展示頁面和樣式文件組成，當(dāng)創(chuàng)建一個(gè)模塊后，系統(tǒng)會(huì)自動(dòng)創(chuàng)建一套默認(rèn)的模板，包括：default.vm 模塊數(shù)據(jù)展示頁面，通過文本編輯器打開編輯。default.css 數(shù)

9、據(jù)展示頁面樣式文件。default.jpg 模板縮略圖文件。三個(gè)文件，分別位于：/模塊根目錄/view/模塊根目錄/themes/模塊根目錄/images/2.5模塊頁面編寫規(guī)范模塊模板的編寫需要遵循velocity規(guī)范，什么velocity?，以下是velocity簡單入門。2.5.1變量變量的簡略標(biāo)記是有一個(gè)前導(dǎo)$字符后跟一個(gè)標(biāo)識(shí)符（Identifier.）組成。變量必須以一個(gè)字母開始(a . z或 A . Z)。剩下的字符將由以下類型的字符組成：變量字母 (a . z, A . Z)數(shù)字 (0 . 9)下劃線 (_)必須以一個(gè)字母開始(a . z或 A . Z)。剩下的字符將由以下類型的

10、字符組成下面是一些正確的變量引用：$foo$mudSlinger$mud-slinger$mud_slinger$mudSlinger1$foo$mudslinger$mud-slinger$mud_slinger$mudSlinger12.5.2指令velocity指令以#開頭#set指令用來為引用設(shè)置相應(yīng)的值。值可以被值派給變量引用或者是屬性引用，而且賦值要在括號(hào)里括起來。#set($string = “Hello world”)#set($string1 = $string)#set($string2 = $string + $string1)#set($num = 1)#set($to

11、tal = $num * 2)#set($array = “Hello”, “world”)#if/else/elseif/end指令，條件指令，必須以#end指令結(jié)束#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判斷是否有這個(gè)

12、變量（或變量是否為null）#if($foo)$foo#elsenothing#end#foreach() #end循環(huán)指令，用于遍歷一個(gè)數(shù)組，Map或列表循環(huán)輸出一個(gè)數(shù)組#set($array = “1”, “2”, “3”)#foreach($a in $array)$a#end循環(huán)輸出列表#set($skus = $skuIdList)#set($productList = $productManager.getProductList($skus)#foreach($product in $ productList)$product.warename#end循環(huán)輸出Map#foreach

13、( $key in $allProducts.keySet() ) Key: $key - value: $allProducts.get($key)#end計(jì)算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)#en

14、d$result2.5.3獲取對(duì)象屬性velocity屬性引用，注意，屬性具體固定的格式，它也是以$開頭，并且是合法的變量標(biāo)識(shí)符，隨后是變量屬性”變量名稱.變量屬性”，如下格式：$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)#end2.5.4

15、安靜引用符當(dāng)velocity 遇到一個(gè)位定義的引用時(shí)，其通常行為是輸出這個(gè)引用的映像。比如，假設(shè)下面的引用出現(xiàn)在模板中的一部分：當(dāng)表單初次裝入時(shí)，變量引用$email無值，你寧愿是一個(gè)空白域而不是具有值$email。使用安靜引用符可以繞過velocity的常規(guī)行為，在velocity中不用$email而是用$!email 符號(hào)。所以，上面的例子將會(huì)看起來像下面的樣子：現(xiàn)在，當(dāng)表單初次裝入時(shí)， $email 仍然沒有值，但是將輸出空字符串而不是$email。形式和安靜引用符可以一起使用，如下所示：2.6常見問題1、置入模塊時(shí)報(bào)以下錯(cuò)誤？A：該問題原因?yàn)椋耗０鍁m、css未按規(guī)定編寫，或者modu

16、le.xml文件格式有誤導(dǎo)致，請(qǐng)先在模塊列表中點(diǎn)擊”校驗(yàn)”按鈕，待校驗(yàn)通過以后再置入，另請(qǐng)參照模塊模板編寫規(guī)范2、創(chuàng)建了一個(gè)新的模板后，在裝修頁面中點(diǎn)擊設(shè)置按鈕，點(diǎn)擊模板標(biāo)簽無法看到最新添加的模板？A：在裝修頁面中，把這個(gè)模塊重新置入一次即可。3、一套店鋪模板中最多可以添加幾個(gè)設(shè)計(jì)師模塊？A：最多3個(gè)，否則，在店鋪模板打包時(shí)無法通過打包。4、通過編輯模塊頁面，修改了模塊的縮略圖，返回模塊列表頁面后圖片為什么沒改變？A：實(shí)際上圖片已改變，需要按ctrl + f5強(qiáng)制刷新頁面才能生效。3開放服務(wù)接口在編寫模塊頁面時(shí)，可以使用以下默認(rèn)vm變量：變量名稱說明$!cms_app_id應(yīng)用ID$!doma

17、inKey店鋪域名$!shopId店鋪ID$!venderId商家ID為避免與這些內(nèi)容變量發(fā)生沖突，建議在編寫module.xml文件時(shí)，param節(jié)點(diǎn)的name屬性盡量加上前綴，如：dmTitle3.1商品分類服務(wù)3.1.1服務(wù)說明服務(wù)方法：$categoryService.getAllCategory()說明：獲取商家店鋪的所有分類信息列表參數(shù)：無服務(wù)方法：$categoryService.getParentCategoryList()說明：獲取商家店鋪的所有一級(jí)分類信息列表參數(shù)：無服務(wù)方法：$categoryService.getSubCategoryList(parentId)說明：根

18、據(jù)商家店鋪一級(jí)分類ID獲取子分類信息列表參數(shù)：parentId，父分類ID參數(shù)類型：整型3.1.2屬性說明分類屬性名稱說明id分類IDshopId所屬店鋪IDparentId父分類IDtitle分類名稱imgUrl分類ICON圖片地址childs子分類列表3.1.3使用詳解獲取商家店鋪的所有一級(jí)分類信息列表#set($parentCagegoryList = $categoryService.getParentCategoryList ()一級(jí)分類#foreach($category in $parentCagegoryList)$!category.title#end獲取商家店鋪的所有分類信

19、息列表#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商品服務(wù)3.2.1服務(wù)說明服務(wù)方法：$productService.

20、getProductBySkuId(skuId)說明：根據(jù)skuId獲取商品信息參數(shù)：skuId，商品編號(hào)參數(shù)類型：字符串服務(wù)方法：$productService.getProductListBySkuIds(skuIds)說明：根據(jù)skuId串獲取商品列表，多個(gè)sku使用半角逗號(hào)分隔參數(shù)：skuIds，商品編號(hào)串參數(shù)類型：字符串服務(wù)方法：$productService.getProductListByCateId(cateId)說明：根據(jù)skuId串獲取商品列表，多個(gè)sku使用半角逗號(hào)分隔參數(shù)：cateId參數(shù)類型：整型服務(wù)方法：$productService.getProductList(

21、cateId,orderBy,directon,pageNo,pageSize)說明：分頁獲取商品列表信息參數(shù)說明：cateId，整形，分類id，分類id為0時(shí)，表示查詢店鋪內(nèi)所有商品orderBy，整型，排序字段，1表示上架時(shí)間，2表示評(píng)論數(shù)，3表示好評(píng)度，4表示價(jià)格，5表示銷量directon，整型，排序方向，0表示升序，1表示降序pageNo，當(dāng)前頁碼pageSize，每頁顯示條數(shù)調(diào)用示例：$productService.getProductList(0,1,0,1,24)3.2.2屬性說明商品屬性名稱說明waridSKUIDimageurl商品圖片地址warename商品名稱cid1name一級(jí)分類名稱cid2name二級(jí)分類名稱catname三級(jí)分