第三方DIY模块拓展类的开发
出自Discuz! 技术文库
目录 |
内置PHP类扩展方式
脚本目录
- source/class/block/[模块大分类目录] ，此目录需要自行创建
必需的脚本
- source/class/block/[模块大分类目录]/blockclass.php, 此文件为该目录中必需存在的文件,其内容为：
<?php $blockclass = array( 'name' => '模块大分类名', //为此目录定义一个名字 ); ?>
- source/class/block/[模块大分类目录]/block_name.php
- 注意：脚本文件名必需以 block_ 开头，且类名必需和文件名一样。
语言包位置（非必需）
- source/language/block/lang_name.php
内容示例
- source/class/block/[模块大分类目录]/block_name.php内容示例：
<?php
class block_name {
/**
* 必须！
* 返回本数据调用类的显示名称（显示在创建模块时选择“模块数据”的下拉列表里）
* @return <type>
*/
function name() {
return '示例数据类';
}
/**
* 必须！
* 返回一个数组： 第一个值为本数据类所在的模块分类；第二个值为模块分类显示的名称（显示在 DIY 模块面板）
* @return <type>
*/
function blockclass() {
return array('sample', '示例分类');
}
/**
* 必须！
* 返回数据类中可供“模块样式”使用的字段。
* 格式见示例：
* name 为该字段的显示名称
* formtype 决定编辑单条数据时该字段的显示方式： 类型有： text, textarea, date, title, summary, pic； 详见 portalcp_block.htm 模板（搜 $field[formtype] ）
* datatype 决定该字段的数据展示，类型有： string, int, date, title, summary, pic； 详见 function_block.php 中 block_template 函数
* @return <type>
*/
function fields() {
return array(
'field1' => array('name' => '示例字段1', 'formtype' => 'text', 'datatype' => 'string'),
'field2' => array('name' => '示例字段2', 'formtype' => 'title', 'datatype' => 'title'),
);
}
/**
* 必须！
* 返回使用本数据类调用数据时的设置项
* 格式见示例：
* title 为显示的名称
* type 为表单类型， 有： text, password, number, textarea, radio, select, mselect, mradio, mcheckbox, calendar； 详见 function_block.php 中 block_makeform() 函数
* @return <type>
*/
function getsetting() {
return array(
'param1' => array(
'title' => '数据调用参数1',
'type' => 'text',
'default' => ''
),
'param2' => array(
'title' => '数据调用参数2',
'type' => 'mcheckbox',
'value' => array(
array('1', '选项1'),
array('2', '选项2'),
),
'default' => '1'
),
);
}
/**
* 必须！
* 处理设置参数，返回数据
* 返回数据有两种：
* 一种是返回 html，放到模块 summary 字段，直接显示； 返回格式为： array('html'=>'返回内容', 'data'=>null)
* 一种是返回 data，通过模块样式渲染后展示，返回的数据应该包含 fields() 函数中指定的所有字段； 返回格式为： array('html'=>'', 'data'=>array(array('title'=>'value1'), array('title'=>'value2')))
* 特别的：
* parameter 参数包含 getsetting() 提交后的内容； 并附加了字段：
* items ，为用户指定显示的模块数据条数；
* bannedids ，为用户选择屏蔽某数据时记录在模块中的该数据 id。 应该在获取数据时屏蔽该数据；
*
* 如果返回的数据给 data， 那么应该包含 fields() 函数指定的所有字段。并附加以下字段：
* id 标志该数据的 id，如果用户屏蔽某数据时，会将该数据的 id 添加到 parameter[bannedids] 里
* idtype 标志该数据的 idtype
*
* @param <type> $style 模块样式（见 common_block_style 表）。 可以根据模块样式中用到的字段来选择性的获取/不获取某些数据
* @param <type> $parameter 用户对 getsetting() 给出的表单提交后的内容。
* @return <type>
*/
function getdata($style, $parameter) {
// 返回summary
return array('html' => '<p>这是一个演示模块数据类</p>', 'data' => null);
// 返回数据
// 需要注意： 除 id，idtype， title， url， pic， picflag， summary 几个字段外，其它字段需要放到 fields 数组里。 可以参考系统内置模块类 source/class/block/block_thread.php
return array('html'=>'', 'data' => array(
array(
'id' => '1',
'idtype' => 'sampleid',
'title' => 'title1',
'url' => '#',
'pic' => 'nophoto.gif',
'picflag' => '1',
'summary' => '',
'fields' => array(
'field1' => 'value1'
)
)
));
}
}
?>
第三方 C/S 扩展方式
- 此扩展方式需要第三方提供一个服务端应用程序接口，为使用该服务的客户端提供数据。
- 服务端提供的数据必需为 XML 格式的数据，具体的 XML 规范请参考下面的详细说明。
XML 规范
配置规范
- 请示方式
- 客户端以 GET 的方式向服务器端提交以下参数请求此 XML 文档
op=getconfig，此参数表示客户端要请求配置文档； clientid，客户端ID（服务器分配给客户端的ID）； charset，客户端的数据编码 sign=签名，如果服务器端没有设置通信密钥则此值为空，如果服务器端不使用签名则此值为通信密钥；签名机制
- 规范内容包括Title和Data部分
- Title部分
- 此部分是固定的代码且区分大小写
<item id="Title"><![CDATA[Discuz! Block]]></item>
- Data部分
- 主要包括5个属性
version 版本号（必需） name 模块名（必需） fields 可显示的字段,在模块样式中使用（必需）包括以下内容 name 为该字段的显示名称 formtype 决定编辑单条数据时该字段的显示方式： 类型有： text, textarea, date, title, summary, pic； datatype 决定该字段的数据展示，类型有： string, int, date, title, summary, pic； getsetting 可设置和接收的参数（必需）,包括以下内容 title 为显示的名称 type 为表单类型， 有： text, password, number, textarea, radio, select, mselect, mradio, mcheckbox, calendar； style 内置的显示样式（非必需）
- 配置规范 XML 文档示例如下
<?xml version="1.0" encoding="ISO-8859-1"?>
<root>
<item id="Title"><![CDATA[Discuz! Block]]></item>
<item id="Data">
<item id="version"><![CDATA[X1.5]]></item>
<item id="name"><![CDATA[C/S 数据类]]></item>
<item id="fields">
<item id="url">
<item id="name"><![CDATA[链接地址]]></item>
<item id="formtype"><![CDATA[text]]></item>
<item id="datatype"><![CDATA[string]]></item>
</item>
<item id="title">
<item id="name"><![CDATA[标题]]></item>
<item id="formtype"><![CDATA[title]]></item>
<item id="datatype"><![CDATA[title]]></item>
</item>
<item id="pic">
<item id="name"><![CDATA[图片]]></item>
<item id="formtype"><![CDATA[pic]]></item>
<item id="datatype"><![CDATA[pic]]></item>
</item>
<item id="summary">
<item id="name"><![CDATA[简介]]></item>
<item id="formtype"><![CDATA[summary]]></item>
<item id="datatype"><![CDATA[summary]]></item>
</item>
<item id="author">
<item id="name"><![CDATA[作者]]></item>
<item id="formtype"><![CDATA[text]]></item>
<item id="datatype"><![CDATA[text]]></item>
</item>
<item id="authorid">
<item id="name"><![CDATA[作者ID]]></item>
<item id="formtype"><![CDATA[text]]></item>
<item id="datatype"><![CDATA[int]]></item>
</item>
<item id="field1">
<item id="name"><![CDATA[字段1]]></item>
<item id="formtype"><![CDATA[text]]></item>
<item id="datatype"><![CDATA[string]]></item>
</item>
<item id="field2">
<item id="name"><![CDATA[字段2]]></item>
<item id="formtype"><![CDATA[text]]></item>
<item id="datatype"><![CDATA[string]]></item>
</item>
</item>
<item id="getsetting">
<item id="param1">
<item id="title"><![CDATA[数据调用参数1]]></item>
<item id="type"><![CDATA[text]]></item>
<item id="default"><![CDATA[]]></item>
</item>
<item id="param2">
<item id="title"><![CDATA[数据调用参数2]]></item>
<item id="type"><![CDATA[mcheckbox]]></item>
<item id="value">
<item id="0">
<item id="0"><![CDATA[1]]></item>
<item id="1"><![CDATA[选项1]]></item>
</item>
<item id="1">
<item id="0"><![CDATA[2]]></item>
<item id="1"><![CDATA[选项2]]></item>
</item>
</item>
<item id="default"><![CDATA[1]]></item>
</item>
<item id="titlelength">
<item id="title"><![CDATA[标题长度]]></item>
<item id="type"><![CDATA[text]]></item>
<item id="default"><![CDATA[40]]></item>
</item>
<item id="summarylength">
<item id="title"><![CDATA[简介长度]]></item>
<item id="type"><![CDATA[text]]></item>
<item id="default"><![CDATA[80]]></item>
</item>
<item id="start">
<item id="title"><![CDATA[起始数据行数]]></item>
<item id="type"><![CDATA[text]]></item>
<item id="default"><![CDATA[0]]></item>
</item>
</item>
<item id="style">
<item id="0">
<item id="name"><![CDATA[模板名称]]></item>
<item id="template"><![CDATA[<div class="module cl xl xl1"><ul>[loop]<li><em><a href="home.php?uid={authorid}"><FONT COLOR="RED">{author}</FONT></a></em><a href="{url}">{title}</a></li>[/loop]</ul></div>]]></item>
</item>
<item id="1">
<item id="name"><![CDATA[模板名称红色]]></item>
<item id="template"><![CDATA[<div class="module cl xl xl1"><ul>[loop]<li><em><font color="red"><a href="home.php?uid={authorid}">{author}</a></font></em><a href="{url}">{title}</a></li>[/loop]</ul></div>]]></item>
</item>
</item>
</item>
</root>
数据规范
数据规范分为数据列表和HTML代码
- 数据列表格式
- 客户端在请求数据时以 POST 的方式提交客户端设置的参数值，参数值包括在配置规范中可设置和接收的参数 getsetting 指定的所有字段,除了设置的参数外，系统会以 POST 的方式追加以下参数：
* op=getdata ，此参数表示客户端要请求数据； * clientid ，客户端ID（服务器分配给客户端的ID）； * op=getdata ，此参数表示客户端要请求数据； * items ，为用户指定显示的模块数据条数； * bannedids ，为用户选择屏蔽某数据时记录在模块中的该数据 id，多个 id 以半角分号(,)分隔。 应该在获取数据时屏蔽该数据； * charset，客户端的数据编码 * sign ，数据签名，如果服务器端没有设置通信密钥则此值为空，如果服务器端不使用签名则此值为通信密钥；签名机制 服务器端返回数据的 data 中应该包含 配置规范中可显示的字段 fields 指定的所有字段。并附加以下字段： * id 标志该数据的 id，如果用户屏蔽某数据时，会将该数据的 id 以 POST 的方式变量名为 bannedids，多个id以半角逗号(,)分隔提交到服务器端 * picflag 如果有图片，则该值标志图片的类型，0 为 url、1 为本地、2 为 ftp 远程；如果图片是 Discuz! X 系统中的图片可以情况设置为 1 或 2，其它情况为 0 需要注意： 除 id，title， url， pic， picflag， summary 几个字段外，其它字段需要放到 fields 数组里。
- 数据列表格式示例
<?xml version="1.0" encoding="ISO-8859-1"?> <root> <item id="html"><![CDATA[]]></item> <item id="data"> <item id="0"> <item id="id"><![CDATA[14]]></item> <item id="title"><![CDATA[xml_block_title14]]></item> <item id="url"><![CDATA[xml_server.php]]></item> <item id="pic"><![CDATA[nophoto.gif]]></item> <item id="picflag"><![CDATA[1]]></item> <item id="summary"><![CDATA[]]></item> <item id="fields"> <item id="author"><![CDATA[xml_user14]]></item> <item id="authorid"><![CDATA[14]]></item> <item id="field1"><![CDATA[field1value14]]></item> <item id="field2"><![CDATA[field2value14]]></item> </item> </item> <item id="1"> <item id="id"><![CDATA[15]]></item> <item id="title"><![CDATA[xml_block_title15]]></item> <item id="url"><![CDATA[xml_server.php]]></item> <item id="pic"><![CDATA[nophoto.gif]]></item> <item id="picflag"><![CDATA[1]]></item> <item id="summary"><![CDATA[]]></item> <item id="fields"> <item id="author"><![CDATA[xml_user15]]></item> <item id="authorid"><![CDATA[15]]></item> <item id="field1"><![CDATA[field1value15]]></item> <item id="field2"><![CDATA[field2value15]]></item> </item> </item> </item> </root>
- HTML 代码格式
- 例示
<?xml version="1.0" encoding="ISO-8859-1"?> <root> <item id="html"><![CDATA[<div style="border:1px solid red;width:100px; height: 100px;">HTML CODE</div>]]></item> <item id="data"><![CDATA[]]></item> </root>
服务端应用程序接口示例
- 以下提供一个 PHP 版本的程序示例：
<?php
define('CHARSET', 'GBK'); //服务器端数据编码
require './source/class/class_xml.php'; //XML格式的文档和array的相互转换的类
error_reporting(7);
$charset = $_GET['charset'] ? $_GET['charset'] : $_POST['charset']; //客户端数据编码
//数据转码
if(strtoupper($charset) != CHARSET) {
foreach($POST as $key => $value) {
$POST[$key] = iconv($charset, CHARSET, $value);
}
foreach($GET as $key => $value) {
$GET[$key] = iconv($charset, CHARSET, $value);
}
}
$data = array('html'=>'', 'data'=>''); //初始化要返回数据
$sign = $_GET['sign'] ? $_GET['sign'] : $_POST['sign']; //获取客户端请求数据的签名
$clientid = $_GET['clientid'] ? $_GET['clientid'] : $_POST['clientid']; //客户端ID
$client = get_client_by_clientid($clientid); //得到客户端的相关信息
if(empty($client)) { //客户端不存在
exit('CLIENT_NOT_EXISTS'); //直接返回失败
}
$datasign = ''; //数据签名
if(!empty($_POST)) {
unset($_POST['sign']); //删除签名参数，此参数不参加签名计算
$datasign = get_sign($_POST, $client['key']); //计算数据的签名
} else {
unset($_GET['sign']); //删除签名参数，此参数不参加签名计算
$datasign = get_sign($_GET, $client['key']); //计算数据的签名
}
if($datasign != $sign) { //签名不正确
exit('SIGN_ERROR'); //输入签名错误
}
if($_POST['op'] == 'getdata') { //判断是否为请求数据列表
$datalist = $data = array();//数据列表
$wherearr = array(); //SQL 条件数组
//获取客户端POST参数
$start = intval($_POST['start']); //起始数据行数
$limit = intval($_POST['items']); //要显示多少条数
$bannedids = addslashes($_POST['bannedids']); //客户端屏蔽的IDS
$param1 = addslashes($_POST['param1']); //数据调用参数1,假设此值要求为string型
$param2 = intval($_POST['param2']); //数据调用参数2,假设此值要求为int型
//处理参数1
if(!empty($param1)){
$wherearr[] = "fieldsparam1='$param1'";
}
//处理参数2
if(!empty($param2)) {
$wherearr[] = "fieldsparam2='$param2'";
}
//处理客户端屏蔽的IDS
if(!empty($bannedids)) {
$banids = explode(',', $bannedids);
$wherearr[] = "csid NOT IN (".implode("','", $banids)."')";
}
$where = !empty($wherearr) ? 'WHERE '.implode(' AND ', $wherearr) : ''; //构造条件
/*数据库相关处理
$query = DB::query('SELECT * FROM '.DB::table('tablename')." $where LIMIT $start, $limit"); //SQL查询
while($value = DB::fetch($query)) {
//此处为数据处理逻辑代码
$data[] = $value;
}
*/
//以下为临时测试数据，正式环境请根据自己的业务做相关调整
$url = 'http://www.xxx.com/';
$data = range($start, $start + $limit);//构造临时的假数据
foreach($data as $value) {
//需要注意： 除 id， title， url， pic， picflag， summary 几个字段外，其它字段需要放到 fields 数组里。
$datalist[] = array(
'id' => $value,
'title' => 'xml_block_title'.$value, //标题
'url' => $url.'xml_server.php?csid='.$value, //链接地址
'pic' => $url.'/data/attachment/photo.gif', //图片地址
'picflag' => '0', //0为url 1为本地 2 为ftp远程；如果图片是DX系统中的图片可以情况设置为1或2，其它情况为0
'summary' => '', //简介
'fields' => array( //配置规范中fields中指定的字段
'author' => 'xml_user'.$value,
'authorid' => $value,
'field1' => 'field1value'.$value,
'field2' => 'field2value'.$value
)
);
}
$data['data'] = $datalist;
//如果要返回HTML代码，可直接使用以下代码
//$data['html'] = 'HTML CODE';
$xml = array2xml($data); //转换为XML文档
} else if($_GET['op'] == 'getconfig') {
$xml = file_get_contents('block_xml_sample.xml');//block_xml_sample.xml文件中的内容为 配置规范XML文档示例 的内容
} else {
$xml = 'NO_OPERATION';
}
ob_end_clean();
@header("Expires: -1");
@header("Cache-Control: no-store, private, post-check=0, pre-check=0, max-age=0", FALSE);
@header("Pragma: no-cache");
header("Content-type: text/xml");
echo $xml;
exit();
/**
* 获得客户端信息
* @param $clientid
* @return array 客户端信息数组
*/
function get_client_by_clientid($clientid){
$client = array();
$clientid = intval($clientid);
if($clientid) {
/*数据库相关处理
$client = DB::fetch_first('SELECT * FROM '.DB::table('clienttable')." clientid='$clientid'"); //SQL查询
*/
//以下为临时测试数据，正式环境请根据自己的业务做相关调整
//模拟数据库
$CLIENTSDB = array(
'100000' => array(
'clientid' => '100000',
'key' => '*654%#(asd94',
),
'200000' => array(
'clientid' => '200000',
'key' => '1#9!(@@34#94',
),
'300000' => array(
'clientid' => '300000',
'key' => '7$@^8^$7as89',
),
'400000' => array(
'clientid' => '400000',
'key' => '23@#86^%4&32',
),
);
$client = isset($CLIENTSDB[$clientid]) ? $CLIENTSDB[$clientid] : array();
}
return $client;
}
/**
* 生成签名
* @param array $para 参数数组
* @param string $key 加密密钥
* @return string 签名
*/
function get_sign($para, $key = ''){
ksort($para);
$signarr = array();
foreach($para as $k => $v) {
$signarr[] = $k.'='.$v;
}
$sign = implode('&', $signarr);
$sign = md5($sign.$key);
return $sign;
}
?>
签名机制
- 计算方法
- 待签名数据 + 通信密钥（服务器端提供给客户端的通信密钥）的MD5值作为签名。
- 所有HTTP请求中传递的参数(除sign外)按照参数名称字符升序的顺序串联起来（例如：k1=v1&k2=v2&k3=v3），构成待签名数据。
- 例如：请求配置文档需要以下参数：
op=getconfig clientid=10000 charset=utf-8 那么待签名数据就是：clientid=10000&op=getconfig&charset=utf-8。
- 签名注意事项：
- 无论参数是否有值，只要在请示中传递即包含到待签名数据中。
- 根据 HTTP 协议要求，传递参数的值中如果存在特殊字符（如：&、@等），那么该值需要做 URL Encoding，这样请求接受方才能接受到正确的参数值。这种情况下，做签名时使用的应该是原生值而不是 encoding 之后的值。
