XForms 天生適合當 Web 服務客戶端,因為它本來就在收發 XML。但若直接把 SOAP 請求當成表單的資料實例,操作起來會相當彆手。這篇技巧示範一個更清爽的做法:一個實例負責給使用者操作,另一個實例負責送進送出具體的服務。
為了簡單起見,這裡仍選用常見的天氣範例:送出一個郵遞區號,取回當地目前氣溫。服務由 XMethods.Net 提供。
最初的請求本質上就是一段 SOAP 訊息:
清單 1. SOAP 訊息
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="https://schemas.XMLsoap.org/soap/envelope/"
xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="https://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body>
<ns1:getTemp XMLns:ns1="urn:xmethods-Temperature"
SOAP-ENV:encodingStyle="https://schemas.XMLsoap.org/soap/encoding/">
<zipcode xsi:type="xsd:string">02134</zipcode>
</ns1:getTemp>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
此例不打算讓使用者直接面對這段結構。取而代之,我們會另建一個比較友善的實例,在提交之前把資料填進上面這副骨架裡。
一份 XForms 表單由模型與控制項組成,所以從最基本的實例和輸入框開始。
清單 2. 基本的 XForms 表單
<Html
XMLns="https://www.w3.org/1999/xHtml"
XMLns:xforms="https://www.w3.org/2002/xforms"
xmlns:xsd="https://www.w3.org/2001/XMLSchema"
xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
xmlns:ev="https://www.w3.org/2001/XML-events"
XMLns:ns1="urn:xmethods-Temperature"
xmlns:SOAP-ENV="https://schemas.XMLsoap.org/soap/envelope/"
>
<head>
<title>XForms and Web Services</title>
</head>
<body>
<object id="FormsPlayer"
classid="CLSID:4D0ABA11-C5F0-4478-991A-375C4B648F58">
<b>FormsPlayer has not loaded. Please check your installation.</b>
</object>
<?import namespace="xforms" implementation="#FormsPlayer" ?>
<xforms:model id="WeatherService">
<xforms:instance id="guiInstance" XMLns="">
<inputData>
<zip>enter zip</zip>
</inputData>
</xforms:instance>
</xforms:model>
<xforms:input ref="instance('guiInstance')//zip">
<xforms:label>Zip code: </xforms:label>
<xforms:hint>Enter a zip code and submit the form for the current
temperature in that area.</xforms:hint>
</xforms:input>
</body>
</Html>
這份頁面先宣告所有相關命名空間,接著導入 FormsPlayer 物件及其命名空間,然後才進入表單本體。模型此時还很朴素,只裝了一個保存輸入值的簡單實例;在真實專案裡,這個位置很可能放的是一份來自既有系統的複雜文件。頁面末尾則定義了一個綁到 zip 元素的輸入框。
圖 1:輸入控制項

注意我說的是「準備提交」,而不是「提交」。因為結果輸出這個控制項所依賴的資料在畫面初始時並不存在,所以得先準備好切換機制。做法是用一組 case 搭配 toggle 組成開關:
清單 3. 加入開關
...
</xforms:instance>
</xforms:model>
<xforms:switch>
<xforms:case id="request">
<h2>Enter your zip code</h2>
<xforms:input ref="instance('guiInstance')//zip">
<xforms:label>Zip code: </xforms:label>
<xforms:hint>Enter a zip code and submit the form for the current
temperature in that area.</xforms:hint>
</xforms:input>
</xforms:case>
<xforms:case id="response">
<h2>And the result is...</h2>
The zip code you requested is:
<xforms:output ref="instance('guiInstance')//zip" />
</xforms:case>
</xforms:switch>
</body>
</Html>
同一時間只會顯示一個 case,預設是第一個。要切到另一個,需要一個帶 toggle 的 trigger:
清單 4. 加入觸發器
...
<xforms:case id="request">
<h2>Enter your zip code</h2>
<xforms:input ref="instance('guiInstance')//zip">
<xforms:label>Zip code: </xforms:label>
<xforms:hint>Enter a zip code and submit the form for the current
temperature in that area.</xforms:hint>
</xforms:input>
<xforms:trigger style="display:block">
<xforms:label>Get current temperature</xforms:label>
<xforms:action ev:event="DOMactivate">
<xforms:toggle case="response" />
</xforms:action>
</xforms:trigger>
</xforms:case>
如圖 2 所示,trigger 會被渲染成一個普通按鈕:
圖 2:觸發器按鈕

使用者按下按鈕或以其他方式觸發時,畫面就會切到第二個 case。
接下來把第二個實例放進頁面。因為 Web 服務找的是 XML,這個實例就是服務期待收到的那則訊息:
清單 5. 加入第二個實例
...
<xforms:model id="WeatherService">
<xforms:instance id="messages">
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="https://schemas.XMLsoap.org/soap/envelope/"
xmlns:xsi="https://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="https://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body>
<ns1:getTemp XMLns:ns1="urn:xmethods-Temperature"
SOAP-ENV:encodingStyle=
"https://schemas.XMLsoap.org/soap/encoding/">
<zipcode xsi:type="xsd:string">NO DATA SUBMITTED</zipcode>
</ns1:getTemp>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
</xforms:instance>
<xforms:instance id="guiInstance" XMLns="">
<inputData>
<zip>enter zip</zip>
</inputData>
</xforms:instance>
</xforms:model>
...
整個拼圖的關鍵是 zipcode 元素。為了方便觀察它的狀態,可以在 response 這個 case 裡多加一個 output 控制項:
清單 6. 檢視即將送出的資料
...
<xforms:case id="response">
<h2>And the result is...</h2>
The zip code you requested is:
<xforms:output ref="instance('guiInstance')//zip" />
<br />
The zip code you are going to send is:
<xforms:output ref="instance('messages')//zipcode" />
</xforms:case>
...
輸入郵遞區號並按下按鈕,就能看見目前的狀態:
圖 3. 監看即將送出的資料

很明顯,這樣不會成功——使用者輸入的值還留在 guiInstance 裡,messages 中的 zipcode 依然是佔位文字。得先把值搬過去。
簡單說,使用者觸發時要將 guiInstance 的 zip 複製到 messages 的 zipcode。用 setvalue 一行就能搞定:
清單 7:把值複製到訊息實例
...
<xforms:trigger style="display:block">
<xforms:label>Get current temperature</xforms:label>
<xforms:action ev:event="DOMactivate">
<xforms:setvalue ref="instance('messages')//zipcode"
value="instance('guiInstance')//zip" />
<xforms:toggle case="response" />
</xforms:action>
</xforms:trigger>
...
使用者一觸發,表單就把 messages 裡 zipcode 的值設為 guiInstance 裡 zip 的值。重新載入表單再操作一次即可驗證:
圖 4. 設定 zipcode 元素的值

要送出 messages 實例,需要在模型中建立對應的 submission 元素,並從 trigger 觸發它。
清單 8. 建立 submission 元素
...
<xforms:instance id="guiInstance" XMLns="">
<inputData>
<zip>enter zip</zip>
</inputData>
</xforms:instance>
<xforms:submission id="getweather"
method="text-XML-post"
replace="instance"
ref="instance('messages')"
action="https://services.xmethods.Net:80/soap/servlet/rpcrouter"
/>
</xforms:model>
<xforms:switch>
<xforms:case id="request">
...
<xforms:trigger style="display:block">
<xforms:label>Get current temperature</xforms:label>
<xforms:action ev:event="DOMactivate">
<xforms:setvalue value="instance('guiInstance')//zip"
ref="instance('messages')//zipcode"/>
<xforms:toggle case="response" />
<xforms:send submission="getweather"/>
</xforms:action>
</xforms:trigger>
</xforms:case>
<xforms:case id="response">
<h2>And the result is...</h2>
The temperature in zip code
<xforms:output ref="instance('guiInstance')//zip" />
is approximately
<xforms:output ref="instance('messages')//return" /> degrees.
</xforms:case>
</xforms:switch>
</body>
</Html>
於是流程完整了:建立 submission、從 trigger 送出、再把回傳值取出來顯示。如圖 5 所示,原始資料依然可讀(因為它還留在原本的實例裡),同時我們也成功地把另一份獨立的實例交給了服務。
圖 5. 最終結果

XForms 像 Web 服務客戶端一樣好用,因為它天生就在收發 XML;但硬把 Web 服務請求當成資料實例,往往既麻煩又不便。這篇技巧示範了更實際的分工方式,重點可以整理成五步:
setvalue 把資料從前一個實例搬到後一個。這套「資料實例與訊息實例分離」的模式,是後續所有複雜 XForms 整合的基礎。一旦習慣這樣切分,畫面、資料、通訊三者的職責界線會清楚很多。