本文可搭配範例程式碼一併下載參考。
XForms 是相當出色的表單技術,具備許多能打造強大表單的特性。既然如此,何不直接在 PHP 裡用它?問題在於 PHP 開發者 habitually 輸出的是 HTML,而 HTML 對表單能力的限制向來不少。
XForms 的門檻則有兩層:一是它要求嚴格的 XHTML,標籤不閉合、格式不精確都會直接出錯;二是它有一套正規語法,對只熟悉 PHP 的開發者來說並不親切。
本系列文章要示範的,就是打造一支 PHP XForms 元件庫,讓 PHP 開發者能用呼叫函式的方式產生 XForms 元素。這樣做的好處很直接:初學者不必硬背語法,熟練的 XForms 開發者也能把 PHP 的動態能力放進網頁設計流程;更重要的是,不必再手寫一大堆 explicit XHTML,改由元件庫統一輸出,出錯的機率自然下降,開發速度也跟著上來。
實作環境需要 PHP 5 與 Firefox 的 XForms 擴充功能(下載連結見參考資料)。本系列的測試是在 WAMP5 Server 1.7.1(Apache 2 上執行 PHP5)完成。
設計這支程式庫時採用類別,把記憶體變數與區域變數都收在同一處,避免多餘的變數與混亂的程式碼。先從類別宣告與變數定義開始:
<?PHP
class xforms_lib{
var $namespace;
var $namespaceXforms;
var $namespaceEvents;
...
}
?>
類別名稱要記清楚,之後建立實體時會用到。這三個變數對應三個主要命名空間:通用的 XHTML、XForms,以及 Events。
建構式與後續所有方法都寫在這個類別宣告裡面。建立檔案時請命名為 xforms_lib.php,並放進 PHP 專案的子目錄(例如 lib)以便管理。
function xforms_lib($ns, $nsxforms, $nsevents){
$this->namespace = $ns;
$this->namespaceXforms = $nsxforms;
$this->namespaceEvents = $nsevents;
}
建構式負責接收並保存這三個命名空間,之後就不必到處重複指定。若同一支 PHP 程式要產生多份 XHTML 文件,這個設計尤其省事。
function HtmlTag($customNS='', $customNSnamespace=''){
$XML = '<Html';
if($this->namespace != '')
$xml .= ' XMLns="'.$this->namespace.'"';
if($this->namespaceXforms != '')
$xml .= ' XMLns:xforms="'.$this->namespaceXforms.'"';
if($this->namespaceEvents != '')
$xml .= ' XMLns:ev="'.$this->namespaceEvents.'"';
if($this->customNS != '' && $this->customNSnamespace != '')
$xml .= ' XMLns:'.$this->customNS.
'="'.$this->customNSnamespace.'"';
$XML .= ' >';
return $XML;
}
這個方法只負責產生開放的 html 標籤,並把各命名空間放到正確的位置上,回傳結果如下:
<html XMLns="https://www.w3.org/1999/xHtml" XMLns:xforms="https://www.w3.org/2002/xforms" xmlns:ev="https://www.w3.org/2001/XML-events" >
有了骨架,接著補上產生其他 XForms 標籤的函式。先看 submission:
function submissionTag($id, $action, $method = 'post', $ref='',
$instance = '', $replace = ''){
$XML = '<xforms:submission id="'.$id.'" action="'.$action.
'" method="'.$method.'"';
if($ref != '')
$XML .= ' ref="'.$ref.'"';
if($instance != '')
$XML .= ' instance="'.$instance.'"';
if($replace != '')
$XML .= ' replace="'.$replace.'"';
$XML .= " />";
return $XML;
}
其中 $id 與 $action 是必填,method 預設為 post,因此前四個屬性一定會出現在結果中;ref、instance、replace 則只在有值時才附加。若呼叫 submissionTag('xformsTest', 'receive.PHP'),得到的是:
<xforms:submission id="xformsTest" action="receive.PHP" method="post" />
function bindTag($nodeset, $relevant = '', $calculate = '',
$required = ''){
$XML = '<xforms:bind nodeset="'.$nodeset.'"';
if($relevant != '')
$XML .= ' relevant="'.$relevant.'"';
if($calculate != '')
$XML .= ' calculate="'.$calculate.'"';
$XML .= " />";
return $XML;
}
nodeset 是必要參數;此外,relevant、calculate、required 三者之中至少要有一個,這個 bind 才有意義。
function dispatchTag($name, $target){
$XML = '<xforms:dispatch';
if($name != '')
$XML .= ' name="'.$name.'"';
if($target != '')
$XML .= ' target="'.$target.'"';
$XML .= " />";
return $XML;
}
它需要 name 與 target 兩個參數,用途是把某個 XForms 事件(例如 xforms-submit)分派給指定的 submit 元素。
function loadTag($resource = '', $ref = '', $show='replace'){
$XML = '<xforms:load show="'.$show.'"';
if($ref != '')
$XML .= ' ref="'.$ref.'"';
else if($resource != '')
$XML .= ' resource="'.$resource.'"';
$XML .= " />";
return $XML;
}
這個標籤可用來導向另一個頁面,或開啟類似快顯視窗的行為(把 $show 傳成 'new')。要注意 resource 與 ref 不該同時指定,第二部分會補上這道檢查。
function insertTag($nodeset, $at, $position = 'after'){
$XML = '<xforms:insert nodeset="'.$nodeset.'" at="'.$at.
'" position="'.$position.'" />';
return $XML;
}
兩個必要參數,加上一個有預設值的 $position。
function setvalueTag($ref, $value){
$XML = '<xforms:setvalue ref="'.$ref.'" value="'.$value.'" />';
return $XML;
}
function inputTag($ref, $label = ''){
$XML = '<xforms:input ref="'.$ref.'">';
if($label != '')
$XML .= '<xforms:label>'.$label.'</xforms:label>';
$XML .= "</xforms:input>";
return $XML;
}
它的結構比較特別,因為 label 是嵌套在 input 裡面的子元素。只需要 $ref;若同時給了 $label,就會產生一個標籤文字顯示在輸入框旁,例如「電話號碼:」。測試段落會看到實際效果。
function outputTag($value){
$XML = '<xforms:output value="'.$value.'">';
$XML .= '</xforms:output>';
return $XML;
}
用法與 input 類似,差別在於它顯示的是值,而且會依 value 屬性所指向的 XML 內容動態更新,不像傳統 HTML 那樣寫死。
function select1Tag($ref, $label, $itemArray, $itemset,
$appearance = 'minimal'){
$XML = '<xforms:select1 ref="'.$ref.'" appearance="'.
$appearance.'">';
$XML .= '<xforms:label>'.$label.'</xforms:label>';
if(is_array($itemset)){
$XML .= '<xforms:itemset nodeset="'.$itemset['nodeset'].'">';
$XML .= '<xforms:label ref="'.$itemset['label'].'" />';
$XML .= '<xforms:value ref="'.$itemset['value'].'" />';
$XML .= '</xforms:itemset>';
}
else if(is_array($itemArray))
foreach($itemArray as $item){
$XML .= '<xforms:item>';
$XML .= '<xforms:label>'.$item['label'].'</xforms:label>';
$XML .= '<xforms:value>'.$item['value'].'</xforms:value>';
$XML .= '</xforms:item>';
}
$XML .= '</xforms:select1>';
return $XML;
}
這個函式一次產生完整的 select1。若傳入的是標籤/值的陣列,就逐一迭代輸出成選項;若傳入的是 itemset,則改用節點集來填充選單。語法細節不必自己操心。
function comment($comment){
$XML = '<!-- '.$comment.' -->';
return $XML;
}
把文字包進合法的 XHTML 註解後回傳,方便在輸出中留下說明。
function instanceTag($id = '', $instanceXML = '', $src = ''){
$XML = '<xforms:instance';
if($id != '')
$XML .= ' id="'.$id.'"';
if($src != '')
$XML .= ' src="'.$src.'"';
else if($instanceXML != ''){
$XML .= '>'."rn";
$xml .= $instanceXML;
$XML .= "rn".'</xforms:instance>';
}
else
$XML .= " />";
return $XML;
}
instance 的內容可以直接用 $instanceXML 寫入,也可以用 $src 指向外部 URL;之後其他元素再用 $id 來引用它。
function submitTag($submission, $label='Submit', $ref = ''){
$XML = '<xforms:submit submission="'.$submission.'"';
if($ref != '')
$XML .= ' ref="'.$ref.'"';
$XML .= ' >';
$XML .= '<xforms:label>'.$label.'</xforms:label>';
$XML .= '</xforms:submit>';
return $XML;
}
$submission 這裡要填的,就是先前 submissionTag 用到的那個 $id,如此 submit 元素才連得上 submission 元素。
function actionTagOpen($event){
$XML = '<xforms:action ev:event="'.$event.'">';
return $XML;
}
function actionTagClose(){
$XML = '</xforms:action>';
return $XML;
}
function repeatTagOpen($nodeset, $id = ''){
$XML = '<xforms:repeat nodeset="'.$nodeset.'"';
if($id != '')
$XML .= ' id="'.$id.'"';
$XML .= ' >';
return $XML;
}
function repeatTagClose(){
$XML = '</xforms:repeat>';
return $XML;
}
function modelTagOpen($id = ''){
$XML = '<xforms:model';
if($id != '')
$XML .= ' id="'.$id.'"';
$XML .= ' >';
return $XML;
}
function modelTagClose(){
$XML = '</xforms:model>';
return $XML;
}
function triggerTagOpen($ref, $submission = '', $label = 'default'){
$XML = '<xforms:trigger ref="'.$ref.'"';
if($submission != '')
$XML .= ' submission="'.$submission.'"';
$XML .= ' >';
return $XML;
}
function triggerTagClose(){
$XML = '</xforms:trigger>';
return $XML;
}
這八個函式風格一致,差別只在於它們處理的標籤通常還會包一層子元素——例如 model 裡面可以有 instance、bind、submission 等。命名規則很單純:xxxxTagOpen() 產生開放的標籤(如 <xforms:model>),xxxxTagClose() 負責閉合(如 </xforms:model>)。close 版本一般不帶參數,open 版本則與前面幾個函式同樣接受屬性參數,只是不立即閉合,好讓中間能插入對應的嵌套元素。
THEORY 說完,來實際跑一次。先建立 index.php:
<?PHP
header("Content-Type: application/xHtml+XML; charset=UTF-8");
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHtml 1.0 Transitional//EN"
"https://www.w3.org/TR/xhtml1/DTD/xHtml1-transitional.dtd">
<?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");
echo $xformsDoc->HtmlTag();
?>
<head><title>XForms served via PHP</title>
<?PHP
// display model here
$model1 = 'first';
$instance1 = 'firstInstance';
$xformsTestSubmit = 'xformsTest';
$instance1data = '<root XMLns=""><data1/></root>';
echo $xformsDoc->modelTagOpen($model1);
echo $xformsDoc->instanceTag($instance1, $instance1data);
echo $xformsDoc->submissionTag($xformsTestSubmit,
"receive.PHP", 'post');
echo $xformsDoc->modelTagClose();
?>
</head><body>
<?PHP
// display form here
echo $xformsDoc->inputTag("instance('$instance1')//data1", 'input1: ');
echo $xformsDoc->submitTag($xformsTestSubmit);
?>
</body>
</Html>
由於輸出的是 XHTML,Content-Type 必須宣告為 application/xhtml+xml,Firefox 才會把它當成 XForms 來處理,這由 header() 負責。接著帶入三個命名空間建立 xforms_lib 實體,然後在「display model here」下方定義 instance 的 ID、submission 的 ID 與 instance 資料——這正是 PHP 與 XForms 結合後最實用的一點:元素名稱與內容都可以是 PHP 變數,能運算、能暫存,也能直接從資料庫取出來。
model 區塊由 modelTagOpen 開啟,中間寫入 instance 與 submission,最後以 modelTagClose 收尾。body 裡則用 inputTag 與 submitTag 產生輸入框與提交鈕,畫面如下:
圖 1. 概念驗證
接著建立接收端。清單 18 的 submission 指向 receive.php,所以新增這個檔案:
<?PHP
if (!isset($HTTP_RAW_POST_DATA))
$HTTP_RAW_POST_DATA = file_get_contents("PHP://input");
echo str_replace('>', '><br />',
str_replace('<', '<', $HTTP_RAW_POST_DATA));
?>
這樣就能把從串流讀到的資料原樣回顯到畫面上。
現在在輸入框隨便打字,按下 Submit。若輸入「testing testing 1 2 3」,會收到:
<?XML version="1.0" encoding="UTF-8"?> <root XMLns:xforms="https://www.w3.org/2002/xforms" xmlns:ev="https://www.w3.org/2001/XML-events"> <data1> testing testing 1 2 3</data1> </root>
成功。這代表 PHP 產生的 XForms 標籤已被瀏覽器正確解析,提交上去的是一份結構完整的 XML 文件。
你已經完成 PHP XForms 元件庫的第一版,接下來就能用它來建構與開發 XForms 內容。請繼續看本系列的第二部分:那裡會替這支程式庫加上錯誤檢查與一批便利方法,並用它組出完整的概念驗證表單。