内置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[title]]></item>
- <item id="datatype"><![CDATA[title]]></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="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 之后的值。
|