模板编写规范
出自淘宝网店铺开发者WIKI
目录[隐藏] |
总体说明
对于一个设计师的页面来说,在淘宝上呈现的页面结构如下:
基于这样的页面结构:
1. 淘宝要提供一个页面的框架,也就是页面的Layout,设计师设计的页面是Layout中的一部分,如在下面的位置:
<div id="content"></div>
2. 模板必需提供全局的CSS,Header和Footer,在任何一个设计的页面都会包含这三者。
3. CSS,Header和Footer还会被淘宝其他页面所使用,如评级、店铺留言等。
4. 页面包含模块,一部分模块是支持交互的,也就是卖家可以录入一些参数来改变模块的呈现
基于这个考虑,模板需要一个全局的配置文件,也就是site.xml,该文件包含了模块的详细信息,由于页面还可能涉及到模块,所以我们还要对各个模块进行定义,模块同时也是代码复用的基本单元,模块的配置文件为module.xml。
模板目录结构
模板目录结构是指模板各个资源目录划分,如下图:
目前主要分为已下记录类:
• 静态资源:都存放在assets目录,同时包括images和stylesheets两个子目录,静态资源引用需要以相对路径为准。另外本次升级新增加了extra.css文件,此文件可以设置页头和页面背景等。
• 模板文件:也就是模板文件,后缀名为.php或者.vm,依据所选择的模板语言,模板文件包括全局头,全局尾和各个文件的主体。页面文件不能形成子目录。
• 模块文件:不能包含其他资源文件,如果包含其他资源文件,需要来自淘宝相册的服务,模块主要就是模块的配置文件和其模块主体文件。所有模块都存放于modules目录下,系统模块名为taobao.module.xxx,设计师模块名由设计师随意定义,每个模块下存放对应模块的images/scripts/stylesheets。
• 元信息文件:如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等
• 风格信息:模板所包含的风格,都要在<styles>元素下进行声明
• 页面信息:一个模板包含多个页面,每一个页面的具体功能要说明清楚,如店铺的模板页面,那个是首页,那个是详情页等,都需要进行描述
• 模块信息:该模板所包含的模块以及各个模块的详细信息
• 参数信息:如果模板、页面和模块需要参数,这个参数是什么类型的,form该如何交互,这些也需要明确
此处发生细微变动,添加了themes、theme标签
<?xml version="1.0" encoding="GBK"?>
<site version="1">
<!—模板标识由系统自动生成 -->
<id> 2cd2659796794dbab1e4115dac7facf3</id>
<!—模板名称-->
<name>模板-1</name>
<!—设计师信息-->
<author wangwang="XX" url="http://www.taobao.com">Jacky</author>
<!—模板缩略图-->
<thumbnail>assets/images/frontpage.png</thumbnail>
<!—模板语言-->
<language>php</language>
<!—模板版本-->
<version>2010050901</version>
<!—修改日志-->
<change-notes>
change log
</change-notes>
<!—模板描述,不要超过100个字-->
<description>
description here
</description>
<!—模板全局信息-->
<global>
<!—模板头部-->
<header>header.php</header>
<!—模板尾部-->
<footer>footer.php</footer>
<!—模板全局CSS文件-->
<css>assets/stylesheets/global.css</css>
</global>
<!--新添加了theme标签 用于标示皮肤风格-->
<themes default="red">
<theme name="default">
<css>themes/default/extra.css</css>
<rule>themes/default/default.json</rule>
</theme>
<theme name="red">
<css>themes/red/extra.css</css>
<rule>themes/red/red.json</rule>
</theme>
</themes>
<!—模板风格-->
<styles>
<style>
<!—风格名称-->
<name>green</name>
<!—风格缩略图-->
<thumbnail>assets/images/green.jpg</thumbnail>
<!—风格CSS文件-->
<css>/assets/stylesheets/green.css</css>
</style>
</styles>
<!—模板参数信息-->
<parameters>
<param name="demo" description="只读属性-1" readonly="true">demo</param>
<param name="theme" description="主题风格">green</param>
</parameters>
<!—模板页面-->
<pages>
<page type="index">
<name>首页</name>
<file>index.php</file>
<parameters>
<param description="标题">untitled</param>
</parameters>
</page>
<page type="detail">
<name>宝贝详情页</name>
<file>detail.php</file>
</page>
<page type="article">
<name>文章页面</name>
<file>article.php</file>
</page>
<page type="other">
<name>促销页面</name>
<file>onsale.php</file>
</page>
</pages>
</site>
出于XML编写的方便,SDK为site.xml提供了XSD,只需要一个XMLEditor就可以完成XML校验和相关的代码提示。 文件说明:此次升级主要是主要是把文件配置由原先的php变成了json,配置文件的相关内容请注意,此文件在创建模板的时候会自动生成。
模板编写
在模板中的模块都是集中在模板标准目录的modules目录中,可先参看模块编写规范
此次升级的重大改变:页面文件由php变更为json。如果对json数据结果不太了解,请参考http://zh.wikipedia.org/wiki/JSON此处请注意kv对的引号,建议用sdk工具生成此文件。
首先先看页面json结构如下:
{"title":"index",
"layouts":[
{ "type": "grid-m",
"modules":
{"col-main":[
{"moduleID":"cuxiao","moduleVersion":"1.0.0"}
]}
},
{ "type": "grid-s5m0",
"modules":
{"col-sub":[
{"moduleID":"taobao.module.category","moduleVersion":"1.0-common"}
],"col-main":[
{"moduleID":"taobao.module.navigator","moduleVersion":"1.0-common"},
{"moduleID":"taobao.module.searchInShop","moduleVersion":"1.0-common"},
{"moduleID":"cuxiao","moduleVersion":"1.0.0"}
]}
}]
}
(1)index页面对象中包含两个键值对,title标示页面,layouts标示布局
(2)layouts数组中的每一个对象{}都为一种布局,type标示布局分类,具体布局分类如下
(3)type存在8种类型:
a) 通栏布局950:grid-m
b)两栏布局190-750:grid-s5m0
c) 两栏布局750-190:grid-m0s5
d)三栏布局190-190-550:grid-e5s5m0
e) 三栏布局190-550-190:grid-e5m0s5
f) 三栏布局550-190-190:grid-m0e5s5
g)头部:head
h)尾部:foot
(4)modules标示所有模块,每个模块存放在对应的坑中,例子有190-550-190布局
a) col-main 为中间550区域
b) col-sub 为左边190边栏区域
c) col-extra 为右边190边栏区域
根据需求,将模块放入不同区域内
1. 引入模块
模块有两种类型,分别是系统模块和设计师自定义模块,下面分别说明如何引入系统模块和设计师自定义模块:
• 引入系统模块
<?php
echo include_system_module("shop.picRound","1.0-common",100);
?>
其中include_system_module需要三个参数,第一个为“系统模块简称”,第二个为“系统模块版本”,第三个为domId,这里需要注意的是domId需要在页面内唯一。
• 引入自定义模块
<?php
echo include_local_module("textbox",101);
?>
其中include_local_module有两个参数,第一个”textbox”为模块的名称,第二个为domId,这里需要注意的是domId需要在页面内唯一。
2. 引入片区
片区是设计师在页面预留的一块区域,卖家可以在坑里添加模块,具体引入坑的语法如下:
<div id=" navigator" class=" J_TRegion">
<?php
$topList=array('shortname'=>'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)
?>
</div>
其中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模板中加入了新的配置规则,允许设计师精确配置自己坑中所支持的模块。
示例配置如下:
<?xml version="1.0" encoding="GBK"?>
<site version="1">
<id>9bb679384bb64c59be4f23ca37b6bcf7</id>
<name>xiaohu</name>
<author wangwang="" url="http://www.taobao.com"></author>
<thumbnail>assets/images/frontpage.png</thumbnail>
<language>php</language>
<version>1.0.0</version>
<apply-sites>3,7</apply-sites>
<change-notes>
change log
</change-notes>
<description>
description
</description>
<parameters>
<param name="demo" description="只读属性-1" readonly="true" ptype="text" formType="text" label="label">demo</param>
<param name="theme" description="主题风格" ptype="text" formType="text" label="label">green</param>
</parameters>
<global>
<header>header.php</header>
<footer>footer.php</footer>
<css>assets/stylesheets/global.css</css>
</global>
<styles default="gray">
<style>
<name>gray</name>
<thumbnail>/assets/images/frontpage.png</thumbnail>
<css>assets/stylesheets/gray.css</css>
</style>
</styles>
<rules>
<common>
<support>
<module shortname="shop.searchInShop" version="1.0-common"/>
<module shortname="shop.topList" version="1.0-common"/>
<module shortname="shop.friendLink" version="1.0-common"/>
</support>
</common>
<header>
<placeholder name="head-modules">
<support>
<module shortname="shop.itemCategory" version="1.0-common"/>
</support>
</placeholder>
</header>
<footer>
<placeholder name="foot-modules">
<support>
<module shortname="shop.fileList" version="1.0-common"/>
<module id="side_sales"/>
</support>
</placeholder>
</footer>
</rules>
<pages>
<page type="index">
<name>首页</name>
<file>index.php</file>
<thumbnail>assets/images/index.png</thumbnail>
<description>sjgjweogj</description>
<rules>
<placeholder name="sub-modules">
<support>
<module shortname="shop.itemCategory" version="1.0-common"/>
<module shortname="shop.fileList" version="1.0-common"/>
<module id="side_help"/>
<module id="side_sales"/>
</support>
</placeholder>
</rules>
</page>
</pages>
</site>
在site节点下的rules中配置通用的模块和头部尾部模块,在page节点下的rules中配置具体页面下坑中支持的模块。
通用模块的配置不需要指定坑的名称,头,尾,页面中的模块配置需要指定到页面中的具体的坑名。
具体坑中支持哪些模块的计算方式是,通用配置集合与当前坑模块集合的并集。
模块配置支持系统模块和设计师自定义的模块两种模块类类型。
4. 宝贝详情页设计
宝贝详情页和其他页面不同,主要是设计师不再是设计整个页面,而是设计局部页面,这个主要是出于买家的统一感受。对于宝贝详情页来说,配置信息如下:
这里需要设置一个宝贝详情文件名称,目前这个文件不需要设置任何内容,留空即可,但是一定需要一个文件,主要是URL定位和以后的扩展,还有你需要设置两个section,名称分别为left和right,不能更改这两个名称,然后是这两个section对应的php文件。如果你需要设计多个detail文件,需要在site.xml中声明,配置不同的信息即可。
PHP Lite引擎详解
SDK提供的PHP环境并不是原生的PHP,而是使用Java模拟PHP环境,最终是由Java来负责PHP的渲染。PHPLite是PHP的精简版,主要用于SDK上,其目的是为设计师提供PHP的设计环境,同时确保服务器端的安全。
Php lite限制
PHP-lite 对PHP的执行的一些限制:
• 循环次数限制:100次(如 foreach,for,do,while 等循环语句的循环限制,当超过100次,则立马就结束循环)
• 自定义方法嵌套调用层数限制:100次(主要是防范无限递归调用,当超过调用层数限制,直接抛出异常)
• 循环嵌套调用层数限制:4层 (无论何种循环,都不能连套超过限制数,否则直接抛出异常)
以上限制皆为默认值,可以通过taobao_quercus_config.properties来配置合适的限制值
Php lite函数白名单
PHP-lite 提供了PHP内置函数的白名单如下:
com.taobao.com.caucho.quercus.lib.ArrayModule
getLoadedExtensions
array_change_key_case
array_chunk
array_combine
array_count_values
array_pop
each
array_key_exists
key_exists
array_keys
array_fill
array_flip
array_pad
array_filter
array_product
array_push
array_rand
array_reduce
array_reverse
array_search
array_shift
array_slice
array_splice
spliceImpl
array_sum
array_unique
array_unshift
array_values
array_walk
array_walk_recursive
arsort
asort
ksort
krsort
natsort
natcasesort
in_array
rsort
usort
uasort
uksort
extract
extract
array_diff
array_fill_keys
array_diff_assoc
array_diff_key
array_diff_uassoc
array_diff_ukey
array_intersect
array_intersect_assoc
array_intersect_key
array_intersect_uassoc
array_intersect_ukey
array_map
array_merge
array_merge_recursive
array_multisort
array_udiff
array_udiff_assoc
array_udiff_uassoc
array_uintersect
array_uintersect_assoc
array_uintersect_uassoc
sizeof
count
next
key
prev
reset
shuffle
sort
pos
compact
current
end
range
com.taobao.com.caucho.quercus.lib.ClassesModule
call_user_method
call_user_method_array
class_exists
get_class
get_called_class
get_class_methods
get_class_vars
get_declared_classes
get_object_vars
get_parent_class
interface_exists
is_a
is_object
is_subclass_of
method_exists
property_exists
com.taobao.com.caucho.quercus.lib.CtypeModule
getLoadedExtensions
ctype_alnum
isalnum
ctype_alpha
isalpha
ctype_cntrl
iscntrl
ctype_digit
isdigit
ctype_graph
isgraph
ctype_lower
islower
ctype_print
isprint
ctype_punct
ispunct
ctype_space
isspace
ctype_upper
isupper
ctype_xdigit
isxdigit
com.taobao.com.caucho.quercus.lib.date.DateModule
cal_days_in_month
checkdate
idate
easter_date
easter_days
getdate
gettimeofday
gmdate
gmmktime
gmstrftime
gregoriantojd
localtime
microtime
mktime
strftime
strtotime
jdtounix
date_create
date_date_set
date_default_timezone_get
date_default_timezone_set
date_format
date_isodate_set
date_modify
date_offset_get
date_parse
date_sun_info
date_sunrise
date_sunset
date_time_set
date_timezone_get
date_timezone_set
timezone_abbreviations_list
timezone_identifiers_list
timezone_name_from_abbr
timezone_name_get
timezone_offset_get
timezone_open
time
date
com.taobao.com.caucho.quercus.lib.ErrorModule
getIniDefinitions
debug_backtrace
error_log
error_reporting
restore_error_handler
set_error_handler
set_exception_handler
restore_exception_handler
trigger_error
user_error
exit
die
com.taobao.com.caucho.quercus.lib.HtmlModule
get_html_translation_table
htmlspecialchars_decode
htmlspecialchars
htmlentities
html_entity_decode
nl2br
com.taobao.com.caucho.quercus.lib.json.JsonModule
getLoadedExtensions
json_encode
json_decode
com.taobao.com.caucho.quercus.lib.MathModule
rand
acosh
asinh
atanh
base_convert
bindec
decbin
dechex
decoct
deg2rad
fmod
hexdec
is_finite
is_infinite
is_nan
getrandmax
mt_getrandmax
mt_rand
mt_srand
lcg_value
octdec
pi
rad2deg
srand
abs
sin
cos
tan
atan2
sqrt
log
log10
pow
exp
min
max
acos
asin
atan
ceil
cosh
expm1
floor
hypot
log1p
round
sinh
tanh
com.taobao.com.caucho.quercus.lib.regexp.RegexpModule
getLoadedExtensions
ereg_replace
ereg
getRegexpCacheSize
setRegexpCacheSize
eregImpl
eregi
compileRegexp
createRegexp
createRegexp
createRegexpArray
createRegexpArray
createEreg
createEreg
createEregi
createEregi
createUnicodeEreg
createUnicodeEreg
createUnicodeEregi
createUnicodeEregi
preg_last_error
preg_match
preg_match_all
pregMatchAllPatternOrder
preg_quote
preg_replace
preg_replace
eregReplaceImpl
eregi_replace
preg_replace_callback
preg_replace_callback
preg_split
sql_regcase
spliti
preg_grep
split
com.taobao.com.caucho.quercus.lib.string.StringModule
addslashes
strlen
addcslashes
bin2hex
chop
rtrim
chr
chunk_split
convert_cyr_string
convert_uudecode
convert_uuencode
count_chars
crc32
crypt
explode
fprintf
sprintf
implode
localeconv
ltrim
md5
md5_file
metaphone
money_format
number_format
ord
parse_str
quoted_printable_decode
quotemeta
setlocale
sha1
sha1_file
soundex
sscanf
str_ireplace
str_pad
str_repeat
str_replace
str_rot13
str_shuffle
str_split
str_word_count
strcasecmp
strchr
strstr
strcmp
strcoll
strcspn
strip_tags
stripcslashes
stripos
stripslashes
stristr
strnatcasecmp
strnatcmp
strncasecmp
strncmp
strpbrk
strpos
strrchr
strrev
strripos
strrpos
strspn
strtok
strtolower
strtoupper
strtr
substr
substr_compare
substr_count
substr_replace
ucfirst
ucwords
vprintf
vsprintf
wordwrap
trim
join
printf
com.taobao.com.caucho.quercus.lib.VariableModule
isset
serialize
is_object
constant
debug_zval_dump
define
doubleval
floatval
get_defined_vars
get_resource_type
gettype
import_request_variables
intval
intval
is_array
is_bool
is_callable
is_double
is_float
is_int
is_integer
is_long
is_null
is_numeric
is_real
is_resource
is_scalar
is_string
print_r
settype
strval
var_dump
var_export
empty
defined
unserialize