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

目录

[隐藏]

• 1 总体说明
• 2 模板目录结构
• 3 模板描述符文件详解
• 4 模板编写
  • 4.1 1. 引入模块
  • 4.2 2. 引入片区
  • 4.3 3. 模板中加入模块配置
  • 4.4 4. 宝贝详情页设计
• 5 PHP Lite引擎详解
  • 5.1 Php lite限制
  • 5.2 Php lite函数白名单

总体说明

对于一个设计师的页面来说，在淘宝上呈现的页面结构如下：

基于这样的页面结构：

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，只需要一个XML Editor就可以完成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的渲染。PHP Lite是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
    print
    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