第三方DIY模块拓展类的开发

出自Discuz! 技术文库

在2012年1月17日 (二) 08:52由Bilicen (讨论 | 贡献)所做的修订版本
(差异) ←上一修订 | 最新修订 (差异) | 下一修订→ (差异)
跳转到: 导航, 搜索

目录

内置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 之后的值。
个人工具