文档中心

搜索热词: 下载安装 支付插件 模板 增删改查

挂件规范
本章节主要是介绍,ShopWind系统挂件的开发规范,通过本节的内容,可以自己修改和制作一个新挂件。
一、术语解读
所谓挂件就是实现一个功能的代码块,一般用于首页布局,有了挂件,就能通过可视化编辑模板的方式(所见即所得),配置挂件参数,以达到显示不同内容的目的, 而不是每次都要去修改代码。这样极大便利了不懂代码的使用者的操作体验。另外,挂件也可以起到复用的效果,减少多余的代码。
二、文件部署
前台(frontend)和H5/WAP(mobile)应用的首页部分,都采用了挂件布局的模式。挂件代码都是部署在应用(站点)根目录的widgets目录下。即:

前台(fronted):@shopwind/frontend/widgets

H5/WAP(mobile):@shopwind/mobile/widgets

该目录下的每一个文件夹则代表一个挂件,目前每一个挂件文件夹都以前缀df_开头,这个主要是出于方便区别考虑,并无其他含义。 代表default默认的意思,也可以使用其他前缀,或者不使用前缀。一个完整的挂件会包含以下四个文件:
./config.html

挂件配置文件,主要是负责设置交互参数,比如一个商品挂件,设置一个分类参数,指定显示某个分类下的商品,或者设置一个数量参数,指定显示多少条记录。

./main.widet.php

挂件主程序文件,主要是负责获取数据,并传递给视图显示,比如从数据库获取前十条商品信息。也负责接收从配置文件config.html设置的交互参数,并使用到业务逻辑中。

./widget.html

挂件视图文件,负责渲染页面,输出HTML代码。从main.widet.php传递过来的数据,在视图中使用$widget_data来接收。

./widget.info.php

挂件描述文件,定义挂件的名称、挂件用途、开发者信息、版本号等。注意挂件名name参数必须与挂件文件夹名保持一致,configurable参数代表是否使用配置,如果为false,则不需要编写config.html文件。

三、代码解读
我们先来看一下挂件主程序文件main.widget.php,以下就是一个例子,假设我们的挂件为@shopwind/frontend/widgets/article
namespace frontend\widgets\article;
use common\widgets\BaseWidget;

class ArticleWidget extends BaseWidget
{
    public function getData()
    {
    }
    public function getConfigDatasrc()
    {
    }
    public function parseConfig($input)
    {
    }
}
挂件实例名必须以挂件名(首字母大写)+ Widget拼接而成,并继承父类BaseWidget,一个挂件实例需要实现三个操作方法:

getData()负责处理业务逻辑,获取 数据并传递给视图,视图中使用$widget_data可以获取到数据。

getConfigDatasrc()负责获取配置文件config.html需要的数据,比如配置文件需要文章分类数据,则可以在该方法中获取。

parseConfig()负责格式化配置文件的交互参数数据,但不是必须的。

如下代码实现了获取前十条文章并传递到视图的例子:
main.widget.php
public function getData()
{
    $result  = \common\models\ArticleModel::find()->limit(10)->asArray()->all();
    return $result;
}
config.html
<div> {foreach from=$widget_data item=article} <p>{$article.title}</p> {/foreach} </div>
当我们需要获取指定文章分类下的前N条文章的时候,如以下代码:
main.widget.php
public function getData()
{
    $num = $this->options['num'];
    $cateId = $this->options['cate_id'];
    $data  = \common\models\ArticleModel::find()->where(['cate_id' => $cate_id])
                ->limit($num)->asArray()->all();
    return $data;
}
public function getConfigDatasrc()
{
    $model = \common\models\AcategoryModel();
    $result = $model->find()->where(['parent_id' => 0])->asArray()->all();
    $this->params['acategories'] = $result; 
}
config.html
<div> 显示数量: <p><input name="num" value="{$options.num}" ></p> 选择分类: <select name="cate_id"> {foreach from=$acategories item=category} <option value="{$category.cate_id}">{$category.cate_name}</option> {/foreach} </select> </div>
在挂件主程序的getData()方法中,我们使用$this->options变量来获取配置文件config.html的交互参数,而需要传递到配置文件config.html 的数据,我们使用$this->params来赋值,父类BaseWidget已经为我们做好了这些衔接工作。
在配置文件config.html中,$options保存了我们的交互参数的设置值,该数据是通过parseConfig()方法传递给配置文件的。
四、如何使用
当我们开发好一个挂件之后,就可以在后台-> 布局 -> 模板编辑 -> 电脑端/手机端 -> (选择页面)可视化,就会在打开的页面中,页头位置的挂件列表中看到我们开发的挂件。我们只要点击下挂件,就可以把该挂件模块拖放到页面中,当我们把鼠标移到挂件上面,鼠标指针成十字架形状时,按住鼠标不放可以把挂件移动合适的位置上。
当挂件描述文件的configurable参数为true时,会看到在挂件的有上角有一个扳手图标的编辑按钮, 点击该按钮就会弹窗一个由config.html渲染的页面,如上个例子中,我们修改页面上的显示数量选择分类,就可以改变当前挂件加载的数据, 当一个页面有多个相同的挂件的时候,每个配置文件只对当前挂件有效,不会造成数据污染,从而实现了挂件复用的效果。
关于挂件的拖放操作,有些新手觉得不好操作,其实只要多操作,熟悉了其实并不难。挂件位置拖放好,或者修改了挂件参数之后,一定要记得点击左上角的保存修改配置才会生效。
通过本节的学习,大家应该能掌握了挂件的基本规范和用法,如果对此还有疑问,可以进入我们官方的 开发者社区反馈,我们会有官方技术人员在线解答。