BloggerAds

2011年4月29日 星期五

XOOPS Form 的表單設計

From: Polin Wei


XOOPS源碼分析之--表單組件淺析(一)

表單是幾乎所有WEB開發中都會用到的,生成表單的方法有很多,我先後用過的方法就很雜,有直接echo表單的html代碼 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完成最好的顯示輸出。

下面我們舉個簡單的例子來看看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();


XOOPS源碼分析之--表單組件淺析(二)

也就是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 XoopsFormPassword("更改密碼", '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();
表單物件列表

* 引入表單物件會用到的檔案

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

* 新增一個表單物件實例,第一個參數是標題名稱,第二個參數是表單名稱,第三個參數是表單送出後執行的程式,第四個參數表單傳送方式。

$form = new XoopsThemeForm("表單標題", 'form', "action.php", 'post', true);
//XoopsThemeForm( string $title, string $name, string $action, string $method = "post" );

* 加入一個欄位

$form->addElement(新增的實體欄位new XoopsFormXXX , 是否必填true or false );

* 加入標籤

$form->addElement(new XoopsFormLabel("標籤標題", "標籤值"));
//XoopsFormLabel($caption="", $value="");

* 加入文字欄位

$form->addElement(new XoopsFormText("文字欄位標題", "text_name", 35, 255, "預設值"));
//XoopsFormText( string $caption, string $name, int $size, int $maxlength, string $value = "" )

* 加入隱藏欄位

$form->addElement(new XoopsFormHidden('op', 'save'));
//XoopsFormHidden($name, $value);

* 加入TOKEN REQUEST

$form->addElement(new XoopsFormHiddenToken('XOOPS_TOKEN_REQUEST',360));
//XoopsFormHiddenToken($name = 'XOOPS_TOKEN_REQUEST', $timeout = 360);

* 加入上傳欄位

$form->setExtra("enctype='multipart/form-data'");
$form->addElement(new XoopsFormFile('上傳欄位標題', 'File_name', "2048"));

* 加入密碼欄位

$form->addElement(new XoopsFormPassword('密碼欄位標題', 'Password_name', 20, 255, "1234"));
//XoopsFormPassword($caption, $name, $size, $maxlength, $value="");

* 加入文字方塊

$form->addElement(new XoopsFormTextArea("文字方塊標題", 'field_description', "預設值",5,50,));
//XoopsFormTextArea($caption, $name, $value="", $rows=5, $cols=50, $id = "");

* 加入Dhtml編輯框

$form->addElement(new XoopsFormDhtmlTextArea("編輯框標題", 'DhtmlTextArea_name', , 5, 50, "xoopsHiddenText"));
//XoopsFormDhtmlTextArea($caption, $name, $value, $rows=5, $cols=50, $hiddentext="xoopsHiddenText");

若想改成 TinyMCE

//$textarea = new XoopsFormDhtmlTextArea(_AM_CONTENT, 'bcontent', $block['content'], 15, 70);
if ( is_readable(XOOPS_ROOT_PATH . "/class/xoopseditor/tinymce/formtinymce.php")) {
include_once(XOOPS_ROOT_PATH . "/class/xoopseditor/tinymce/formtinymce.php");
$textarea = new XoopsFormTinymce(array('caption'=>_AM_CONTENT, 'name'=>'bcontent', 'value'=>$block['content'], 'width'=>'100%', 'height'=>'400px', 'xEditor'=>'1'));
}else{
$textarea = new XoopsFormDhtmlTextArea(_AM_CONTENT, 'bcontent', $block['content'], 15, 70);
}

若想改成 FCKeditor

//$textarea = new XoopsFormDhtmlTextArea(_AM_CONTENT, 'bcontent', $block['content'], 15, 70);
if ( is_readable(XOOPS_ROOT_PATH . "/class/xoopseditor/fckeditor/formfckeditor.php")) {
include_once(XOOPS_ROOT_PATH . "/class/xoopseditor/fckeditor/formfckeditor.php");
$textarea = new XoopsFormFckeditor(array('caption'=>_AM_CONTENT, 'name'=>'bcontent', 'value'=>$block['content'], 'width'=>'100%', 'height'=>'400px', 'xEditor'=>'1'));
}else{
$textarea = new XoopsFormDhtmlTextArea(_AM_CONTENT, 'bcontent', $block['content'], 15, 70);
}

若想改成 Koivi

//$textarea = new XoopsFormDhtmlTextArea(_AM_CONTENT, 'bcontent', $block['content'], 15, 70);

if ( is_readable(XOOPS_ROOT_PATH . "/class/xoopseditor/koivi/formwysiwygtextarea.php")) {
include_once(XOOPS_ROOT_PATH . "/class/xoopseditor/koivi/formwysiwygtextarea.php");
$textarea = new XoopsFormWysiwygTextArea(array('caption'=>_AM_CONTENT, 'name'=>'bcontent', 'value'=>$block['content'], 'width'=>'100%', 'height'=>'400px', 'xEditor'=>'1'));
}else{
$textarea = new XoopsFormDhtmlTextArea(_AM_CONTENT, 'bcontent', $block['content'], 15, 70);
}

* 加入送出與清除按鈕與同一欄

$Tray1=new XoopsFormElementTray("按鈕標題", " ", "name", true);
$Tray1->addElement(new XoopsFormButton(, 'submit_name', "送出", 'submit'));
$Tray1->addElement(new XoopsFormButton(, 'reset_name', "清除", 'reset'));
$form->addElement($Tray1);
//XoopsFormButton(str $caption, str $name, bool $value="", button|submit|reset $type="button")

* 加入核取方塊

//第一個參數為標題,第二個參數為表單欄位名稱,第三個參數可設定選取單一選項
$checkbox = new XoopsFormCheckBox('複選方塊標題', 'box_name', "k1","");
//XoopsFormCheckBox($caption, $name, $value = null, $id = "")
$checkbox->addOption("a1", "顯示值1");
//多重預設值設定
$def_arr=array("k1","k4");
$checkbox->setValue($def_arr);
$options["k2"]="顯示值2";
$options["k3"]="顯示值3";
$options["k4"]="顯示值4";
$checkbox->addOptionArray($options);
$form->addElement($checkbox);


* 加入單選鈕

//第一個參數為標題,第二個參數為表單欄位名稱,第三個參數可設定預設選取選項
$Radio = new XoopsFormRadio('單選鈕標題', 'radio_name', "w1","");
$Radio->addOption("w1", "顯示值1");
$Roptions["w2"]="顯示值2";
$Roptions["w3"]="顯示值3";
$Roptions["w4"]="顯示值4";
$Radio->addOptionArray($Roptions);
$form->addElement($Radio);

* 加入是否單選鈕

第三個參數為預選值, "0" (No) 或 "1" (Yes)
$form->addElement(new XoopsFormRadioYN('是否單選鈕標題', 'radioYN_name', 1));

* 加入下拉選單

//參數一:標題、參數二:選單欄位名稱、參三:單一預設值,參四:選單長度,參五:是否多重
$select=new XoopsFormSelect("下拉選單標題", "select_name", "s2", 2, true);
//XoopsFormSelect($caption, $name, $value=null, $size=1, $multiple=false);
$select->addOption("s1", "顯示值1", true);
//addOption($value, $name="", $disabled = false) ;
$Soptions["s2"]="顯示值2";
$Soptions["s3"]="顯示值3";
$Soptions["s4"]="顯示值4";
$Soptions["s5"]="顯示值5";
$Soptions["s6"]="顯示值6";
$Soptions["s7"]="顯示值7";
$select->addOptionArray($Soptions);
//addOptionArray($options, $disabled=array());
//多重預選陣列
$sdef_arr=array("s6","s4");
$select->setValue($sdef_arr);
$form->addElement($select);

* 加入文字日期欄位

$form->addElement(new XoopsFormTextDateSelect('文字日期欄位標題', 'textDateSelect_name', 15, 0));
//XoopsFormTextDateSelect($caption, $name, $size = 15, $value= 0);

* 加入日期時間

$form->addElement(new XoopsFormDateTime("日期時間框標題", 'DateTime_name', 15, 0));
//XoopsFormDateTime( mixed $caption, mixed $name, mixed $size = 15, mixed $value = 0 );

範例

if ($_POST['op']=='save') {
echo 'Will SAVE:
';
echo "姓名:".$_POST['name'].'
';
echo "電子郵件:".$_POST['email'].'
';
$html=1;
$smiley=1;
$xcodes = 1;
$myts =&MyTextSanitizer::getInstance();
$message = $myts->displayTarea($_POST['message'],$html,$smiley,$xcodes);
echo "訊息:".$message.'
';
} else {
$contact_form=creat_form();
echo $contact_form;
}
function creat_form() {
//引入表單物件會用到的檔案
include_once XOOPS_ROOT_PATH."/class/xoopsformloader.php";
//新增一個表單物件實例,第一個參數是標題名稱,第二個參數是表單名稱,第三個參數是表單送出後執行的程式
$form = new XoopsThemeForm('留下消息', 'contactform', $_SERVER['PHP_SELF']);
//加入一個文字列
$form->addElement(new XoopsFormText("姓名", 'name', 30, 70, 'test'), true);
//加入一個文字列
$form->addElement(new XoopsFormText("電子郵件", 'email', 40, 90, 'test@edu.tw'), false);
//加入一個文字方塊,第一個參數是標題名稱,第二個參數是表單名稱
$form->addElement(new XoopsFormDhtmlTextArea("訊息", 'message', , 12, 35), true);
//TOKEN
$form->addElement(new XoopsFormHiddenToken('XOOPS_TOKEN_REQUEST',2));
//Hidden
$form->addElement(new XoopsFormHidden('op', 'save'));
//加入送出表單的按鈕
$form->addElement(new XoopsFormButton('操作', 'submit', "送出", 'submit'),0);
//加入驗證表單用的JavaScript程式
$form->renderValidationJS();
return $form->render();
}

參考:http://163.30.191.22/wiki/index.php/XOOPS的表單設計

沒有留言:

張貼留言