应用开发文档

插件应用 zip 包目录结构

插件压缩包只允许 .zip 文件, 并且目录结构需要严格按照要求

插件应用目录结构

.
|-- <your_plugin>
|   |-- components
|   |   `-- <component_a>
|   |       |-- edit.css
|   |       |-- editing.js
|   |       |-- package.json
|   |       |-- portal.js
|   |       `-- style.css
|   |   `-- <component_b>
|   |       |-- edit.css
|   |       |-- editing.js
|   |       |-- package.json
|   |       |-- portal.js
|   |       `-- style.css
|   |   .
|   |   .
|   `-- package.json

插件应用由一个或多个组件构成。所有的组件在 components 文件夹下。插件应用与后端交互的配置信息，由与 components 文件夹同级的 package.json 来描述。components 文件夹下，是该插件应用的组件部分。组件由五个文件组成：package.json(必须) editing.js(必须) edit.css(必须) portal.js(必须) style.css(必须)。开发仅有后台功能的插件(不含组件)，上述五个文件内容为空。

插件应用：package.json 详解

如果插件应用不需要后台，以下各个字段为空。

{
    "entrance": "",             /*后台管理入口*/
    /*代理配置信息*/
    "proxy-prefixes": {         
        "common": "",               /*通用地址，如果下述项有未配置的，以 common 为准*/
        "backend-page": "",         /*后台页转发原始地址*/
        "backend-api": "",          /*后台接口转发原始地址*/
        "page": "",                 /*前台页转发原始地址*/
        "api": ""                   /*前台接口转发原始地址*/
    },
    "proxy-paths": {
        "common": "*"                 /*通用路径*/
    },
    "oauth-callback-url": ""    /*OAuth 回调地址，可不填*/
}

例如:

快站地址 kuaizhan.com；

某插件应用后台管理的域名为 example.com ；

某快站站点域名为 test.kuaizhan.com；

该插件应用提交的配置信息如下：

{
    "entrance": "/admin/",
    "proxy-prefixes": {
        "common": "http://example.com",
        "mobile-backend-page": "http://example.com/mobile-backend",
        "backend-page": "http://example.com/backend",
        "backend-api": "http://example.com/bcapi",
        "page": "http://example.com/front_page",
        "api": ""
    },
    "proxy-paths": {
        "common": "*"
    }
}

组件：package.json 详解

{
    "title": "sohukuzhan_example",        /*插件名称，会在编辑器页面显示*/
    "image_icon": "http://example.com/foo.png",     /*插件图标，会在编辑器页面显示*/
    "html": "`<div>{{name}} is awesome</div>`",       /*mustache templates，使用的数据在 data_config 中定义*/
 
    "data_config": {},               /*定义插件使用的数据*/
    "widgets": {                     /*UI渲染配置项，通过配置 widgets 属性，将自动创建插件编辑页面配置窗口的UI*/
        "layout": [],                /*布局选项卡，可选 UI 组件*/
        "style": [],                 /*样式选项卡，可选 UI 组件*/
        "property": []               /*内容选项卡，可选 UI 组件*/
    }
}

UI组件配置方法

UI组件监听方法

例如:

/*组件的package.json*/
{
    "title": "foo",
    "image_icon": "url",
    "html": "<p>{{words}}</p>",
    "data_config": {
        "words": {
            "type": "string",
            "required": true,
            "default": "搜狐快站"
        }
    },
    "widgets": {
        "property": [
          {
              "label": "文本内容",
              "type": "text",
              "data_name": "words"
          }
        ]
    }
}
// editing.js 
define(['configurableComponent'], function(Component) {
   'use strict';
    return Component.extend({
        html_edit: "<p>{{words}}</p>", // 插件  html 模板，在编辑页面时使用。 
        renderConfigurator: function() {
            Component.prototype.renderConfigurator.call(this);
            this.listen("words", ""); // 第一个为 data_config 中定义的数据，第二个为数据的单位，没有则填 "" 
        }
    });
 
});

假如 UI typeselect 组件关联的数据为 foo。按参考代码，可在 renderConfigurator 里添加代码监听数据的变化

Component.prototype.renderConfigurator.call(this);
this.listen("foo", "");

假如 UI slider 组件关联的数据为 foo。按参考代码，可在 renderConfigurator 里添加代码监听数据的变化

Component.prototype.renderConfigurator.call(this);
this.listen("foo", "");

假如 UI select 组件关联的数据为 foo。按参考代码，可在 renderConfigurator 里添加代码监听数据的变化

Component.prototype.renderConfigurator.call(this);
this.listen("foo", "");

假如 UI iconselect 组件关联的数据为 foo。按参考代码，可在 renderConfigurator 里添加代码监听数据的变化

Component.prototype.renderConfigurator.call(this);
this.listen("foo", "");

假如 UI text 组件关联的数据为 foo。按参考代码，可在 renderConfigurator 里添加代码监听数据的变化

Component.prototype.renderConfigurator.call(this);
this.listen("foo", "");

假如 UI colorpicker 组件关联的数据为 foo。按参考代码，可在 renderConfigurator 里添加代码监听数据的变化

Component.prototype.renderConfigurator.call(this);
this.listen("foo", "");

UI switchrow 控件会根据 opt.name 的参数不同，有不同的监听方式。 例如：

// switchrow 的 opt.name 为 chk_margin 时 
this.listenMargin();
// switchrow 的 opt.name 为 chk_size 时 
this.listenSize();
// switchrow 的 opt.name 为 chk_align 时 
this.listenAlign();

editing.js 详解

说明：editing.js为编辑器下组件的预览、配置控制类，在提交组件时，必须包括该文件

define(['configurableComponent'], function( Component) {
    'use strict';
 
    //初始化组件类，参数为组件配置，如果组件第一次创建，将传递空配置，如果组件为已经创建到视图窗口，重新加载，将传递已保存的配置 
 
    //覆盖接口函数 
    return Component.extend({
      init: function() {data}, // 初始化组件 
      renderConfigurator: function() {}, // 渲染配置窗口 
      renderView: function() {}, // 渲染预览窗口，当用户修改配置数据时，此方法会多次执行已渲染最新的预览效果 
      getDate: function() {}, // 返回需要保存的用户数据 
      isValid: function() {}, // 验证用户数据是否正确，当用户保存数据时都会调用此方法已保证每个组件自身数据正常 
      beforeInit: function() () // 在init 前执行，如果返回false，将不会创建该组件 
    });
});

portal.js 详解

说明：portal.js为发布后加载执行的JS程序，非必须。

define(['zepto'], function($) {
  return {
    //输出到发布页面，当用户正式发布后，调用此函数创建视图。 
    onAfterRender: function(el) {
      // el 为插件的 dom 
    }
  }
});

如果需要在发布后加载portal.js 还需要在组件的package.json 中的html 数据 增加 {{progdata}} 标签。例如：

"html": "<div  {{{_progdata_}}}></div>",

在页面构建时，这个标签会被替换为组件的 meta 内容

组件： style.css

说明：style.css 为组件的样式文件，在编辑器状态以及发布状态下都会加载，在编写 style.css 时，请参考如下标准：

例如：在插件应用sys-plugins 中，有组件button. 在编写html结构时，需要如下代码：

<div class="mod-sys-plugins-button"><button class="test-button">按钮</button></div>

对应的样式应该编写如下格式

.mod-sys-plugins-button{
 
}
 
.mod-sys-plugins-button .test-button{
    width:80px;
    height:30px;
}

组件： editing.css

说明： editing.css 为在编辑器中特殊的样式，在发布后页面不会加载，在编写 editing.css 时，请参考如下标准：

例如：在插件应用sys-plugins 中，有组件button. 在编写html结构时，需要如下代码：

<div class="mod-sys-plugins-button"><button class="test-button">按钮</button></div>

如果在预览框需要另外的样式显示，对应的样式应该编写如下格式

 
.phone-editing .mod-sys-plugins-button{
 
}
 
.phone-editing .mod-sys-plugins-button .test-button{
    width:80px;
    height:30px;
}