菩提猫笔记：XOOPS源码分析之--表单组件浅析(一)

    表单是几乎所有WEB开发中都会用到的，生成表单的方法有很多，我先后用过的方法就很杂，有直接echo表单的html代码，pear库的quickform类，还有在模板中使用smarty的html_radios等内置函数，而在开始接触XOOPS的源代码后你会发现，XOOPS居然有一套非常完善的form类，相比较而言XOOPS的表单类更容易使用，完全是面向对象的模式，而且代码更为简洁，控制更为灵活。


    这些表单类都保存在XOOPS_ROOT/class/xoopsform目录下，有时间大家可以好好研习一下。

    从我目前理解的状况来说，其中有2个是基类，一个是XoopsForm，一个是XoopsElement，其他都是对这2个基类的继承和扩展。下面我们开始简单的剖析其中几个比较常用的类：


[一]表单的form类--form.php>


文件定义了XoopsForm基类，XoopsSimpleForm、XoopsTableForm、XoopsThemeForm都是对这个对象的扩展。


1、XoopsForm对象的私有变量

• $_action ：对应form中的action，即处理表单提交的操作；


• $_method ：对应form中的method，即POST或是GET；


• $_name ：对应form中name，即表单名；


• $_title ：表单的标题；


• $_elements ：表单成员数组，即form所包含的checkbox，text等元素；


• $_extra ：这个变量会保存一些额外的信息，如class＝“formclass”；


• $_required ：这是个数组变量，保存着form中有哪些成员是必添项，结合Xoops自带的脚本可以方便地在提交前实现必添字段的检查

2、XoopsForm对象的成员函数

• function XoopsForm($title, $name, $action, $method="post", $addtoken=false)

XoopsForm对象的构造函数，前4个参数对照私有变量的命名很容易理解，其中默认的提交方法是"post"，$addtoken这个布尔参数，控制是否要添加一个加密的令牌到form中，我理解是类似于给form增加一个sessionID，防止来自网站之外的恶意提交,默认情况是不添加这个令牌的。

• function getTitle() | function setTitle()


• function getName() | function setName()


• function getAction()| function setAction()


• function getMethod()| function setMethod()

这四组函数很容易理解，分别完成对title，Name，Action，Method的读取(get)和设置(set).

• function addElement(&$formElement, $required=false)

这个函数是比较重要的，它完成form中元素的添加，$formElement是元素对象，$required设置是否这个元素为必添字段，即是否加入校验队列。

• function &getElements($recurse = false)

这个函数返回form中元素数组，$recurse根据源码注释是控制是否采取递归循环方式生成元素数组，因为这个函数一般比较少用，我没仔细去理解它的源码，不知道解释得对不对。

• function getElementNames()

函数返回所有元素的名称，返回值为数组

• function &getElementByName($name)

根据名称返回相应的元素对象，找不到则返回false；我个人认为这个函数是非常有意义的，可以在已经添加元素后，对它进行修改，当然修改还要用到Element对象的函数。

• function setElementValue($name, $value)

此函数可以设置form名为$name元素的值，没有返回值

• function setElementValues($values)

此函数实际上是上一函数的批处理，一次对form多个元素进行赋值，$values是$name/$value对的数组

• function &getElementValue($name)

获得名为$name的form元素值，如果没有设置则返回NULL。

• function &getElementValues()

是上一函数的批处理，返回$name/$value对数组。

• function setExtra($extra, $replace = false)

这个函数也是比较有用的，用于设置form中除name，method，action之外其他的标记，$replace控制是否覆盖原有$_extra,默认为将$extra添加到原有$_extra后面，返回新的$_extra内容

• function &getExtra()

此函数读取form的$_Extra内容。

• function setRequired(&$formElement)

此函数将&$formElement指向的元素添加到form对象的必添数组$_required中.

• function &getRequired()

此函数返回form对象的必添元素数组$_required

• function insertBreak($extra = null)

这是个抽象函数，需要在子类定义中覆盖

• function display()

此函数用于表单最后的渲染输出。

• function renderValidationJS( $withtags = true )

此函数用于Xoops表单内置校验脚本的输出，基本上不会用到。

• function assign(&$tpl)

此函数让表单使用$tpl指向的smarty模板对象，来替代直接显示输出，或者说把现有的form对象传递到smarty模板中，由smarty完成最好的显示输出。

    OK，到这儿，基本上XoopsForm对象基本上就描述完了。


    下面我们举个简单的例子来看看XoopsForm的基本使用流程

//第一步：包含XoopsForm的调用文件

include_once XOOPS_ROOT_PATH."/class/xoopsformloader.php";

//第二步：添加一个表单实例，这里用的是比较常用的XoopsThemeForm，它采用一个table来安排表单布局，如果我没记错，这个table的class＝outer，也就是说你可以在css中更改outer的定义，美好表单的显示。

$form = new XoopsThemeForm('标题', '名称', 'action.php');

//第三步：加入文本元素，注意最后的true表示提交时检查是否填写了内容

$form->addElement(new XoopsFormText("姓名", 'name', 30, 70, $xoopsUser->name()), true);

//第四步：加入表单的提交按鈕

$form->addElement(new XoopsFormButton('', 'submit', "提交", 'submit'),0);

//第五步：加入验证表单用的JavaScript脚本

$form->renderValidationJS();

//第六步：输出表单

$form->display();

    好啦，XoopsForm基本上就是这样了，希望可以对用xoops开发的朋友有所帮助，有时间我会陆续把其他form元素的分析笔记整理发上来，如果有错误的地方，还请大家不吝赐教。


    BTW：xoops的开发资料实在是少得可怜 了！

非常好~！很详细。

建议文档组的成员把相关内容添加到wiki内。

建议放到wiki里

菩提猫 与你讨论一下：
在你的帖子里，你说曾经用过PEAR::QuickForm库，那QuickForm和XOOPS的Form类有哪些区别呢？

我也用过QuickForm，也在开发XOOPS模块的时候引用QuickForm而不用XoopsForm。但在后来的一些开发里面也用上了XoopsForm。想了解一下你对两者有什么看法？

确切的讲，我不是个职业的程序员，编程的水平也就是入门，只是在跟程序员沟通不太好的时候，才会自己边学边练地修改程序，呵呵，所以我写得只是个人感受，连建议都算不上。
前些时候自己尝试写一个应用程序的时候，使用到了pear::quickform ，时间也不长，因为文档不是很详细，每个form组件我用的时候都得试验半天，感觉自己可控性不是很好，当时进度比较紧，没有去读quickform的源码，所以应该说只学了一个皮毛，后来因为页面用的是smarty模板，感觉如果用2套方式，还不如直接smarty的form函数更直接些。现在则是在把以前写的那个应用移植到xoops平台下，刚开始这个模块搞了个大杂烩，pear的数据库连接，smarty模板，部分quickform，马马虎虎也算运转起来了。后来得看了很多坛子上的帖子，又读了几个xoops的源码，觉得确实写的很出色（虽然写程序不怎么专业，但代码写得好坏还是能看得出来得，呵呵),参考了一下DJ兄的article，觉得直接用xoopsform其实是最简单的，毕竟引入的东西多了以后，时间一长看着都晕。
我看了xoopsform的源码以后，感觉其实自由度还是比较大，能想到的基本上都可以实现了（当然还有好多源码没看完，不过越看越喜欢），也许pear::quickform也很强大，不过我现在也懒得回去再看他的源码了，反正喜欢那个，熟那个就用那个，个人趋向而已。


另外：mediawiki试了一下，没找到怎么添加页面进去，有点晕，不像dokuwiki简明。看哪位老兄指教一下。

引文：

PEAR::QuickForm 和 XoopsForm在表单元素的构建方法都是大同小异，不过QuickForm有一个“验证”功能。在表单生成的同时可以建立每个表单元素的验证规则，当用户提交的时候QuickForm会自动地按照规则去验证表单元素的内容是否符合，不符合的话就会返回并提示出错的信息。在使用Xoops之前，我是用Quickform + adodb进行程序开发，当转移到XOOPS的时候，觉得XoopsForm很容易上手（因为和Quickform构建表单的方式很像），但又觉得用起来不方便，主要就是得自己去建立验证和出错返回这一个步骤。

我也曾经试过大杂烩的方式去做模块~，虽然写的时候很快就出来了，但是到后来再去维护和扩展就发现问题了，主要是程序结构没有设计好。不过，现在有些时候我还是会把QuickForm融合进来，因为有些地方XoopsForm实现不了，比如向Template以数组形式输出，XoopsForm虽然也有这一个功能，但不太好使。曾经向D.J.介绍过QuickForm，也希望XoopsForm可以在未来的版本中融合一些QuickForm的功能。

xoops提供的xoopsForm的确比较灵活强大， 自己在具体开发时候
其实也可以继承xoopsForm来开发自己的Form类.不过大部分都已经
有了，基本就是拿来就用了，超方便！

引文：

说到PEAR::QuickForm的验证功能，我也是比较欣赏的，当时开始用它也就是因为它这个验证功能，不过使用过程中发现，如果设为客户端验证，好象有时管用有时不管用，不知道跟我用的myIE设置是否有关。看了scottlai的帖，现在回想起来，平心而论，PEAR::QuickForm的验证功能更强一些，而XoopsForm更容易上手，记得pear的文档中讲过，QuickForm也只是给新手用的，如果要更强大的form组件，则可转向HTML_QuickForm_Controller，当然文档也是少的可怜。
不过我现在还是更倾向于xoopsform，以后有机会也会去看看HTML_QuickForm_Controller的实现，或许对xoopsform进行扩充也是个不错的想法。

菩提猫笔记：XOOPS源码分析之--表单组件浅析(二)
    上章我把XoopsForm的类定义和成员函数整理了出来，这只是第一步，希望没有读过源码的朋友也会开始喜欢XoopsForm了。本章我会把第2个基础类，也就是XoopsFormElement进行简单分析，form中的checkbox，radio，等等组件都是对这个类的延展，所以弄清XoopsFormElement是如何定义的，将是又一个良好的开端。


【二】表单元素的基类：XoopsFormElement(XOOPS_ROOT/class/xoopsform目录下formelement.php)

1、XoopsElement对象的私有变量

• $_name：元素名称；
• $_id  ：ID号；
• $_caption：显示标题；
• $_accesskey：访问此元素的快捷键；
• $_class ：元素的样式 classl；
• $_hidden：布尔值，定义是否为隐藏字段，默认为false；
• $_extra ：元素额外的定义；
• $_required ：布尔值，定义是否为必添字段，默认为false ；
• $_description ：元素描述。

2、XoopsFormElement对象的成员函数

• function XoopsFormElement()

XoopsFormElemen对象的构造函数，其实什么都没定义，每种元素都有各自的定义。

• function getCaption() | function setCaption()
• function getName() | function setName()
• function getID()| function setID()
• function getAccessKey()| function setAccessKey()
• function getDescription() | function setDescription()
• function isHidden | function setHidden()
• function getExtra() | function setExtra()
• function getClass() | function setClass()

这八组函数很容易理解，分别完成对caption，Name，id，AccessKey，Description等属性的读取(get)和设置(set).

• function isContainer()

这个函数非常简单，就是返回false，告诉你这个元素不是一个容器。

• function getAccessString( $str )

这个函数是会在$str字符串中寻找你定义的AccessKey，如果找到，就会将第一个找到的AccessKey字符底下画线，说起来比较乱，大家打开软件的文件菜单，你可以看到'新建（N）',对，就是这个意思。假定你设‘N’是你的AccessKey，$str为'新建(N)',这个函数就负责返回给你'新建（N）'，不知道我讲明白了没，呵呵。

• function render()

这个函数这里讲没什么意义，因为一行代码都没写，

    到这儿，XoopsFormElement对象讲解就结束了，你肯定觉得这什么都没说啊，没错，我前面讲了，这是个基类，也就搭个架子，具体的元素有各自的定义，基本上也就是在construct函数以及render函数上做文章，但也都是大同小异。

用法：（假定$form = new XoopsThemeForm('标题', '名称', 'action.php');）

1. 直接引用form对象添加：
   $form->addElement(new 元素的构造函数, true/false);
2. 先定义元素，后添加到form对象中
   $element=new 元素的构造函数;
   .
   -添加其他定义
   .
   .
   $form->addElement($element, true/false);

  下面我们来看几个常用的form元素的构造函数：

• 单行文本字段： function XoopsFormText($caption, $name, $size, $maxlength, $value="", $id = "")

参数含义依次为：标题，form中名称，显示宽度（单位为字符数），最大字符数，文本值，ID号。

• 多行文本字段： function XoopsFormTextArea($caption, $name, $value="", $rows=5, $cols=50, $id = "")

参数含义依次为：标题，form中名称，文本值，显示行数，显示列数，ID号。

• 文本标签：function XoopsFormLabel($caption="", $value="")

参数含义依次为：标题，值。

• 选择列表：function XoopsFormSelect($caption, $name, $value=null, $size=1, $multiple=false, $id="")

参数含义依次为：标题，名称，默认被选择的值，显示大小（如果为1，则显示为下拉框，其他为N行的列表框），是否为多选，ID；
XoopsFormSelect对象还有几个非常重要的私有属性，$_options和$_disabled(xoops2.2开始变为数组）,其中$_options是选项value->name对值数组，而$_disabled则定义有哪些不可以选，就是value数组，XoopsFormSelect对象可以参照用法2，使用函数addOptionArray($options, $disabled = array())来添加选项数组和非可选数组的2个定义。

• 多选框：function XoopsFormCheckBox($caption, $name, $value = null, $id = "")

参数含义依次为：标题，名称，默认被选中的值数组，ID；
同样XoopsFormCheckBox也有$_options 属性，为value->name 数组，也需要用addOptionArray($options）函数添加选项数组或是addOption($value, $name="")来添加一个选项。

• 单选框：function XoopsFormRadio($caption, $name, $value = null, $id = "")

XoopsFormRadio与XoopsFormCheckBox极为相似，所不同的是XoopsFormCheckBox的$value是数组，而XoopsFormRadio的则是一个值，添加选项的函数是完全一样的。

• 隐藏字段：function XoopsFormHidden($name, $value, $id="")

参数含义依次为：名称，默认值，ID，比较简单

• 密码字段：function XoopsFormPassword($caption, $name, $size, $maxlength, $value="")

参数含义依次为：标题，form中名称，显示宽度（单位为字符数），最大字符数，文本值；与单行文本字段在操作上没有任何区别；

• 安全令牌： function XoopsFormHiddenToken($name = 'XOOPS_TOKEN_REQUEST', $timeout = 0)

这个字段应该不需要用到，如果你在创建form对象时，定义$addtoken=true,form对象会自己调用这个函数添加一个$name = 'XOOPS_TOKEN_REQUEST'的隐含字段。

• 按钮：function XoopsFormButton($caption, $name, $value="", $type="button", $id="")

构造按钮的5个参数含义依次是：显示文字，form中的名字，按钮的值，按钮类型（buttion/submit/reset 3个值，默认为button），ID号；默认情况下按钮的css 设定为“formButton”。

    OK，到这儿，XoopsForm对象的常用元素就描述完了。

    下面我们举个简单的例子来看看XoopsForm的这些元素如何使用，我们还是利用上一章的例子

//第一步：包含XoopsForm的调用文件
include_once XOOPS_ROOT_PATH."/class/xoopsformloader.php";

//第二步：添加一个表单实例，这里用的是比较常用的XoopsThemeForm，它采用一个table来安排表单布局，如果我没记错，这个table的class＝outer，也就是说你可以在css中更改outer的定义，美好表单的显示。
$form = new XoopsThemeForm('更改用户资料', 'changeUserInfo', 'action.php');

//3.1 加入标签元素
$form->addElement(new XoopsFormLable("ID", "1033"), false);

//3.2 加入文本元素，注意最后的true表示提交时检查是否填写了内容
$form->addElement(new XoopsFormText("用户名", 'username', 30, 70, $xoopsUser->name()), true);

//3.3 加入密码元素，注意最后的true表示提交时检查是否填写了内容
$form->addElement(new XoopsFormText("更改密码", 'newpassword', 30, 70, ""), true);

//3.4 加入多行文本元素，注意最后的true表示提交时检查是否填写了内容
$form->addElement(new XoopsFormTextArea("签名", 'name', 30, 70, ""), true);

//3.5 加入多选字段元素，注意最后的true表示提交时检查是否填写了内容
$checkbox=new XoopsFormCheckBox("兴趣", "intresting", null, $id = "");
$checkbox->addOption('0','读书');
$checkbox->addOptions(array('1'->'绘画','2'->'书法','3'->'音乐');
$checkbox->setValue(array('1','2')); //set 默认选中选项
$form->addElement($checkbox, true);

//3.6 加入单选字段元素，注意最后的true表示提交时检查是否填写了内容
$radio=new XoopsFormRadio("是否愿意接收网站邮件", "receiveMail", 'y', $id = "");
$radio->addOptions(array('y'->'是','n'->'否');
$form->addElement($checkbox, true);

//3.7 加入select元素，注意最后的true表示提交时检查是否填写了内容
$countryOptions=array('0'->'请选择您的国家','1'->'china','2'->'USA','3'->'France',4->'Other');
$disabled=array(1->'0');
$defaultCounty='';
$countrySelect= new XoopsFormSelect('国家', 'CountryID',$defaultCounty, $size=1, $multiple=false);
$countrySelect->addOptionArray($countryOptions,$disabled);
$form->addElement($countrySelect, true);

//3.8 加入隐含字段
$form->addElement(new XoopsFormHidden("action", "modify"),false);

//第四步：加入表单的提交按鈕
$form->addElement(new XoopsFormButton('', 'submit', "提交", 'submit'),false);

//第五步：加入验证表单用的JavaScript脚本
$form->renderValidationJS();

//第六步：输出表单
$form->display();

    OK,是不是很简单，只要用几遍，大家都会很喜欢的，呵呵。 XoopsForm常用的元素操作我都列了一下，今天时间比较紧张，不知道有没有错误，谨供大家参考。
    有时间我再把其他我的一些使用心得整理一下。

支持，继续撰写~我把你写好的文章整理好用PDF发布，作为开发说明书

我用QuickForm的验证都是用服务器端的验证，如果用客户端验证的话安全性不太高。不过用服务器端的验证则需要用户提交之后才能进行。现在有了AJAX，可以考虑一下使用AJAX的方式进行交互验证，效果应该不错的。

QuickForm_Controller功能很强大，但是用起来也很复杂，我曾经尝试使用，但不太成功，也因为缺乏文档，没有去研究它的源码。