DIV CSS 佈局教程網

您现在的位置: DIV+CSS佈局教程網 >> 網頁腳本 >  >> XML學習教程 >> XML詳解
用 PHP 打造 XForms 元件庫(下):例外檢查、便利函式與表單實作
編輯:XML詳解     

本文可搭配範例程式碼一併下載參考。

接續進度:從「能跑」到「能交出去用」

上一階段完成的 PHP XForms 元件庫骨架大致可以運轉了,但它還沒真正被驗證過。接下來要做三件事:把輸出的樣子整理乾淨、替函式的輸入加上把關邏輯(因為 XForms 前處理器給的錯誤訊息往往不太好用),最後實際跑一套操作示範,看看這支程式庫在真實表單裡是什麼模樣。

以下就從這三項任務開始。

為程式庫加上防護網

核心功能既然已經就位,下一步就是替 PHP XForms 元件庫補上防護。理由很實際:並不是所有參數組合都說得通,若放任不管,錯誤只會延後到最後產生的 XHTML 文件裡才爆發,那時除錯成本更高。除此之外,還需要幾個方便的小工具,能把 XHTML 直接送到瀏覽器,並妥善處理程式碼縮排。先從檢查機制談起。

錯誤檢查

在程式庫裡加入檢查邏輯,等於把問題提前攔下來,XForms 處理器要除錯的地方變少,開發時間自然縮短。這裡用兩種方式把關:

  • 針對允許包含子元素的 XHTML 標籤(也就是上一階段新增的 action、model、trigger 與 repeat),確認只有被允許的標籤才能被塞進去當子元素。
  • 針對個別函式的輸入做驗證,一旦出現不該發生的組合,就丟出例外,再由外層攔下來並把訊息呈現在瀏覽器上。

首先在 xforms_lib.php 這個類別檔的變數宣告區補上兩個新成員:

清單 1. 新增的類別變數

<?php
 ...
 var $namespaceEvents;
 var $allowed;
 var $tag;

 function xforms_lib($ns, $nsxforms, $nsevents){
 ...
 $this->tag = '';
 $this->allowed =
 array('action' => array('dispatch', 'insert',
 'setvalue', 'load'),
 'model' => array('instance', 'submission',
 'bind', 'action'),
 'trigger' => array('label', 'action'),
 'root' => array('trigger', 'submit', 'select1',
 'repeat', 'input', 'output',
 'label', 'model'));
 ...

$allowed 與 $tag 都在建構式中完成初始化。$tag 存放的是「目前正開啟的標籤名稱」,後面會經常用到。$allowed 的每個鍵都是一個頂層 XForms 標籤,值則是它允許的子標籤清單。以 action 為例,只有 dispatch、insert、setvalue、load 這四個能放在裡面。root 是尚未指定任何標籤時的預設情境;repeat 在新增子元素的行為上等於 root,所以開啟 repeat 時同樣以 root 參與檢查。

接著改造 dispatchTag,讓它用上這套機制:

清單 2. 改寫 dispatchTag

function dispatchTag($name, $target){
 $this->check('dispatch');
 $XML = '<xforms:dispatch';
 if($name != '')
 $XML .= ' name="'.$name.'"';
 if($target != '')
 $XML .= ' target="'.$target.'"';
 $XML .= " />";
 }

關鍵只有一行:把即將產生的標籤名稱交給新的 check() 函式,其餘邏輯維持原樣。

真正動手檢查的是 check():

清單 3. check 函式

function check($newTag, $action=''){
 $openTag = $this->tag;
 if($openTag == '')
 $openTag = 'root';
 if($action == 'close' && ($openTag != $newTag || $openTag == 'root'))
 throw new Exception("Cannot close $openTag with a $newTag " .
 "close tag statement!");
 else if($action == 'close' && $openTag == $newTag)
 return;
 else if(!in_array($newTag, $this->allowed["$openTag"]))
 throw new Exception("$newTag is not allowed within $openTag!");
 }

逐段拆解這幾條判斷:

  • 第一個 if:若 $tag 目前是空字串,$openTag 一律視為 root。
  • 第二個 if:要求關閉某一層,但被關閉的標籤($newTag)跟目前開啟的標籤($openTag)對不上,或者想關掉的是不能被關閉的 root,就丟出錯誤。
  • 第一個 else if:關閉的標籤與開啟的標籤相符,一切正常,直接結束。
  • 第二個 else if:要新增的標籤不在目前開啟標籤允許的子清單裡(例如在 action 裡想放 repeat),同樣丟出錯誤,交由外層攔下並提示使用者。

剩下的工作是把 check 呼叫補進每一個會產生標籤的函式:

清單 4. 在各處插入 check 呼叫

function loadTag($resource = '', $ref = '', $show='replace'){
 $this->check('load');
 $XML = '<xforms:load show="'.$show.'"';
 ...
 }

 function triggerTagOpen($ref, $submission = '', $label = 'default'){
 $this->check('trigger', 'open');
 $XML = '<xforms:trigger ref="'.$ref.'"';
 if($submission != '')
 $XML .= ' submission="'.$submission.'"';
 $XML .= ' >';
 }

 function triggerTagClose(){
 $this->check('trigger', 'close');
 $XML = '</xforms:trigger>';
 }

注意 triggerTagOpen 與 triggerTagClose 的差別:關閉時必須多帶一個參數('open' 或 'close'),check 才知道這次動作是開還是被關。

再來補上維護「目前開啟標籤」狀態的 setter:

清單 5. setTag 函式

function setTag($t){
 $this->tag = $t;
 }

每當開啟最外層元素就呼叫它,例如開完 model 之後執行 setTag('model');關閉之後則改呼叫 setTag('root'),把狀態退回 root。

輸入驗證同樣以丟出例外的方式處理。需要這層保護的共有五個函式:submission、bind、load、select1 與 instance。先看 submission:

清單 6. submissionTag 的輸入例外

function submissionTag($id, $action, $method = 'post', $ref='',
 $instance = '', $replace = ''){
 $this->check('submission');
 if(($instance != '' || $replace != '') &&
 $replace != '' && $instance != '')
 throw new Exception("instance or replace is set, but not both " .
 "in a submission tag!");
 $XML = '<xforms:submission id="'.$id.'" action="'.$action.
 '" method="'.$method.'"';
 ...
 }

submission 標籤的 instance 與 replace 只能擇一設定,不可同時給值,違反就丟出例外並把訊息顯示給使用者。

其餘四個函式沿用同樣思路:

清單 7. 其餘需要輸入例外檢查的函式

function bindTag($nodeset, $relevant = '', $calculate = '',
 $required = ''){
 $this->check('bind');
 if($relevant == '' && $calculate == '' && $required == '')
 throw new Exception("Must set one of: relevant, calculate or " .
 "required in a bind tag!");
 $XML = '<xforms:bind nodeset="'.$nodeset.'"';
 ...
 }

 function loadTag($resource = '', $ref = '', $show='replace'){
 $this->check('load');
 if($resource != '' && $ref != '')
 throw new Exception("Cannot specify both a resource and ref " .
 "for the load tag!");
 else if($resource == '' && $ref == '')
 throw new Exception("Must specify one of: resource or ref " .
 "for the load tag!");
 $XML = '<xforms:load show="'.$show.'"';
 ...
 }

 function select1Tag($ref, $label, $itemArray, $itemset){
 $this->check('select1');
 if(is_array($itemArray) && is_array($itemset))
 throw new Exception("Cannot specify both a list of items " .
 "and an itemset for a select1 element!");
 else if(!is_array($itemArray) && !is_array($itemset))
 throw new Exception("Must specify one of: itemArray or itemset " .
 "as arrays in the select1 tag!");
 $XML = '<xforms:select1 ref="'.$ref.'">';
 $XML .= '<xforms:label>'.$label.'</xforms:label>';
 ...
 }

 function instanceTag($id = '', $instanceXML = '', $src = ''){
 $this->check('instance');
 if($instanceXML != '' && $src != '')
 throw new Exception("Must define instance data or a src URL " .
 "for the instance tag!");
 $XML = '<xforms:instance';
 ...
 }

整理一下這幾條規則:bind 的 relevant、calculate、required 至少要有一個;load 的 resource 與 ref 必須擇一;select1 的 itemArray 與 itemset 同樣擇一,且兩者都必須是陣列;instance 則是 instanceXML 與 src 只能取其中一種資料來源。錯誤處理的部分到此完成,實際攔截與呈現留到後面的測試段落。

便利函式

為了讓開發者用 PHP 操作 XForms 時更順手,接著補上幾個輔助工具。

清單 8. 更多類別變數

var $allowed;
 var $print;
 var $indentation;
 var $indentationValue;

 function xforms_lib($ns, $nsxforms, $nsevents){
 ...
 $this->namespaceEvents = $nsevents;
 $this->print = 0;
 $this->indentation = 0;
 $this->indentationValue = " ";
 $this->allowed =
 ...
 }

這三個變數專門服務 XHTML 的格式化輸出。$print 決定是否由 printData() 直接把 XHTML 送到瀏覽器;$indentation 記錄目前需要幾層縮排;$indentationValue 則是縮排單位,這裡用四個空白。

清單 9. 增減縮排與切換輸出模式

function incrementIndentation(){
 $this->indentation++;
 }

 function decrementIndentation(){
 $this->indentation--;
 }

 function setPrint($p){
 if($p)
 $this->print = 1;
 else
 $this->print = 0;
 }

前兩個函式對建構式中歸零的 $indentation 做加減,第三個則依傳入的布林值決定 $print 開或關。

清單 10. 產生縮排字串

function indentation(){
 $XML = '';
 for($i = $this->indentation; $i > 0; $i--)
 $XML .= $this->indentationValue;
 return $XML;
 }

這個函式會依 $indentation 的值反覆附加 $indentationValue 再回傳。若 $indentation 為 2,回傳的就是八個空白。搭配 incrementIndentation 與 decrementIndentation,輸出的 XHTML 就能維持整齊的階層。

清單 11. 輸出 XHTML

function printData($XML){
 if($this->print){
 echo $this->indentation();
 echo $XML."rn";
 return 0;
 }
 return 1;
 }

每個標籤產生函式的最後都呼叫 printData():依 $print 的值決定是直接印到瀏覽器,還是原封不動把 XHTML 字串交還給呼叫端。

清單 12. 整合 printData 與縮排控制

function submissionTag($id, $action, $method = 'post', $ref='',
 $instance = '', $replace = ''){
 $this->check('submission');
 ...
 $XML .= ' replace="'.$replace.'"';
 $XML .= " />";
 $this->printData($XML);
 return $XML;
 }

 function triggerTagOpen($ref, $submission = '', $label = 'default'){
 $this->check('trigger', 'open');
 $XML = '<xforms:trigger ref="'.$ref.'"';
 if($submission != '')
 $XML .= ' submission="'.$submission.'"';
 $XML .= ' >';
 $this->incrementIndentation();
 $this->printData($XML);
 return $XML;
 }

 function triggerTagClose(){
 $this->check('trigger', 'close');
 $XML = '</xforms:trigger>';
 $this->decrementIndentation();
 $this->printData($XML);
 return $XML;
 }

值得留意兩點。第一,即使 printData 已經把內容送到瀏覽器,XHTML 字串仍然會照常回傳給呼叫端,兩種用法並不衝突。第二,triggerTagOpen 會先把縮排加一層,因此 trigger 開啟後的所有內容都會往內縮,直到 triggerTagClose 被呼叫才還原。

請把 $this->printData($XML); 補進其餘函式的合適位置,並在每個 tagOpen 尾端加上 incrementIndentation、每個 tagClose 尾端加上 decrementIndentation,可對照範例程式碼逐項確認。

清單 13. 一組實用的小工具

function doctypeTag(){
 $XML = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHtml 1.0 Transitional//EN"
 "https://www.w3.org/TR/xhtml1/DTD/xHtml1-transitional.dtd">';
 $this->printData($XML);
 return $XML;
 }

 function headTitle($title){
 $XML = "<head><title>$title</title>";
 $this->printData($XML);
 return $XML;
 }

 function closeHeadOpenBody(){
 $XML = "</head><body>";
 $this->printData($XML);
 return $XML;
 }

 function closeBodyCloseHtml(){
 $XML = "</body></Html>";
 $this->printData($XML);
 return $XML;
 }

 function outputXHtmlheader(){
 header("Content-Type: application/xHtml+XML; charset=UTF-8");
 }

這些函式專門負責輸出常見的固定標籤與 XHTML 相容的 HTTP 標頭,下一節建立測試表單時就會用到。

用元件庫組出一份表單

現在來看這支 PHP XForms 元件庫的實際用途。本節會建立幾個 XForms 控制項,並以 Firefox 的 XForms 擴充功能檢視執行結果。

先看新的 index.php 開頭:

清單 14. index.php 的起頭

<?PHP
include('lib/xforms_lib.PHP');
$xformsDoc = new xforms_lib("https://www.w3.org/1999/xHtml",
 "https://www.w3.org/2002/xforms",
 "https://www.w3.org/2001/XML-events");
$xformsDoc->setPrint(1);
$xformsDoc->outputXHtmlheader();
$xformsDoc->doctypeTag();
$xformsDoc->HtmlTag();
$xformsDoc->incrementIndentation();
$xformsDoc->headTitle('XForms served via PHP');
...
?>

第一行先把程式庫載入,接著建立 xforms_lib 實體並帶入三個命名空間。把 $print 設為 1 之後,程式庫就會直接把 XHTML 寫進輸出串流;最後依序輸出標頭、DOCTYPE、html 標籤與標題,把文件骨架搭好。

清單 15. 建立 XForms 模型

...
// display model here
$model1 = 'model';
$instance1 = 'instance';
$instance1data = '<root XMLns=""><data1>../here</data1><data2/>'.
 '<data3/><data4/><data5/></root>';
$instance2 = 'instance2';
$instance2data = '<root XMLns=""><data><datum>data1</datum>'.
 '<datum>d2</datum><datum>third data</datum></data>
 </root>';
$submitButton1 = 'submit1';
$submitButton2 = 'submit2';
$xformsDoc->setTag('root');
$xformsDoc->modelTagOpen($model1);
$xformsDoc->setTag('model');
$xformsDoc->incrementIndentation();
$xformsDoc->instanceTag($instance1, $instance1data);
$xformsDoc->instanceTag($instance2, $instance2data);
$xformsDoc->submissionTag($submitButton1,
 "receive.PHP", 'post', "instance('$instance1')");
$xformsDoc->submissionTag($submitButton2,
 "receive.PHP", 'post', "instance('$instance2')");
$xformsDoc->bindTag("instance('$instance1')/data4",
 "instance('$instance1')/data3='1'",
 "instance('$instance1')/data2");
$xformsDoc->modelTagClose();
$xformsDoc->setTag('root');
$xformsDoc->decrementIndentation();
...

開頭幾行只是 PHP 變數,用來存放 model、instance、submission 的名稱,另外還定義了兩份 instance 的 XML 內容。接著以 setTag 把狀態初始化為 root。

model 標籤開啟後,$tag 立刻改成 model,因為最外層已經換人當了;同時縮排要加一層,所以呼叫 incrementIndentation。

隨後建立兩份 instance,再接兩個 submission——它們會用 POST 把對應的 instance 送到上一階段完成的 receive.php。bind 的部分則是透過 calculate 把 data4 綁到 data2,並以 data3 作為 data4 的 relevant 條件。最後關閉 model,$tag 退回 root,縮排也還原。

清單 16. 以 inputTag 與 outputTag 建立表單主體

...
$xformsDoc->closeHeadOpenBody();
$xformsDoc->incrementIndentation();
// display form here
$xformsDoc->inputTag("instance('$instance1')//data1",
 'data1 (new page input): ');
echo "<br />";
$xformsDoc->inputTag("instance('$instance1')//data2",
 'data2 (data4 is bound to this field): ');
echo "<br />";
$xformsDoc->inputTag("instance('$instance1')//data3",
 'data3 (1 makes data4 relevant): ');
echo "<br />data4 (bound to data2): ";
$xformsDoc->outputTag("instance('$instance1')//data4");
echo "<br />data5 (value of select menu shown here): ";
$xformsDoc->outputTag("instance('$instance1')//data5");
echo "<br />";
...

先關掉 head、開啟 body,然後建立三個 input 分別對應 instance1 的 data1、data2、data3,再用兩個 output 顯示 data4 與 data5。實際操作時就能驗證清單 15 的綁定是否如預期運作。

清單 17. 定義 select1

...
$itemset['nodeset'] = "instance('$instance2')//datum";
$itemset['label'] = '.';
$itemset['value'] = '.';
$xformsDoc->select1Tag("instance('$instance1')//data5", 'select me',
 '', $itemset);
echo "<br />";
...

先用 instance2 裡所有 datum 節點組成節點集,再建立 select1 並指向 instance1 的 data5。選擇結果會同步反映到清單 16 的第二個 output 上。

清單 18. 兩個提交按鈕

...
$xformsDoc->submitTag($submitButton1, 'SubmitTextBoxes');
echo "<br />";
$xformsDoc->submitTag($submitButton2, 'SubmitSelect');
echo "<br />";
...

這兩個按鈕分別對應兩份 instance,按下後就能檢視各自的 XML 內容。

清單 19. 建立 trigger

...
$xformsDoc->triggerTagOpen("instance('$instance1')//data1", '', 'new page');
echo "<br />";
$xformsDoc->setTag('trigger');
$xformsDoc->actionTagOpen("DOMactivate");
$xformsDoc->setTag('action');
$xformsDoc->loadTag('', "instance('$instance1')/data1",
 'new');
$xformsDoc->actionTagClose();
$xformsDoc->setTag('trigger');
$xformsDoc->triggerTagClose();
$xformsDoc->setTag('root');
...

這裡建立一個文字為 new page 的 trigger。開啟後把 $tag 設為 trigger,並在其中放一個 action,於 DOMactivate 事件時觸發;接著把 $tag 改成 action,用 load 依 data1 的值開啟新視窗(試著在 data1 填個網址再按這顆按鈕)。最後依序關閉 action 與 trigger,$tag 回到 root。

清單 20. 建立 repeat

...
echo "<br/>repeat data:";
$xformsDoc->repeatTagOpen("instance('$instance2')//datum", 'id1');
$xformsDoc->setTag('root');
$xformsDoc->outputTag(".");
$xformsDoc->setTag('repeat');
$xformsDoc->repeatTagClose();
$xformsDoc->setTag('root');
$xformsDoc->decrementIndentation();
$xformsDoc->decrementIndentation();
$xformsDoc->closeBodyCloseHtml();
?>

repeat 的範圍是 instance2 底下所有 data 子元素。由於 repeat 在新增子元素時等同 root,$tag 先設為 root;接著放一個 output 顯示目前的節點內容(ref 為「.」代表當前節點);關閉 repeat 之前把 $tag 設回 repeat,關閉後再歸還 root。

所有 XForms 標籤都寫完之後,把縮排減少兩層並關上 body 與 html,文件即完成。

完成的表單如下圖:

圖 1. 最終的表單

在 XHTML 頁面上按右鍵選擇「檢視原始碼」,就能檢查 PHP 產生的標籤是否正確:

圖 2. 格式化確實生效

也別忘了確認表單中的各個控制項,是由這套 PHP 產生的 XForms 標籤所驅動。

結語

恭喜——你手上已經有一支相當穩固的 PHP XForms 元件庫,可以拿來繼續開發與擴充。要留意的是,它涵蓋的 XForms XHTML 標籤並不齊全,錯誤檢查也仍有精進空間。例如你可以自行定義新函式,把還沒支援的 XForms 標籤補進來。基本上一切都有可能,開源專案能長成什麼樣子,往往取決於開發者願意投入多少心力,這個兩部曲系列就是一個例子。祝你接下來的 PHP 與 XForms 之旅順利,寫程式愉快!

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved