mirror of https://github.com/moparisthebest/xeps
707 lines
38 KiB
XML
707 lines
38 KiB
XML
|
<?xml version='1.0' encoding='UTF-8'?>
|
||
|
|
<!DOCTYPE xep SYSTEM 'xep.dtd' [
|
||
|
|
<!ENTITY % ents SYSTEM 'xep.ent'>
|
||
|
|
%ents;
|
||
|
|
]>
|
||
|
|
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
|
||
|
|
<xep>
|
||
|
|
<header>
|
||
|
|
<title>Data Forms - Dynamic Forms</title>
|
||
|
|
<abstract>
|
||
|
|
This specification provides extensions to the data forms model defined in previous XEPs that permits enhanced end-user interaction and
|
||
|
|
a better user experience. It permits forms to react on user input by permitting the addition, updating or removal of fields in the form,
|
||
|
|
server-side validation of fields as well as define new states making it possible to display disabled controls,
|
||
|
|
controls with undefined values or error messages, while still being backwards compatible with the existing data form model with available
|
||
|
|
extensions.
|
||
|
|
</abstract>
|
||
|
|
<legal>
|
||
|
|
<copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF).</copyright>
|
||
|
|
<permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
|
||
|
|
<warranty>## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
|
||
|
|
<liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
|
||
|
|
<conformance>
|
||
|
|
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <<link url='http://www.xmpp.org/extensions/ipr-policy.shtml'>http://www.xmpp.org/extensions/ipr-policy.shtml</link>> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).
|
||
|
|
</conformance>
|
||
|
|
</legal>
|
||
|
|
<number>xxxx</number>
|
||
|
|
<status>ProtoXEP</status>
|
||
|
|
<type>Standards Track</type>
|
||
|
|
<sig>Standards</sig>
|
||
|
|
<approver>Council</approver>
|
||
|
|
<dependencies>
|
||
|
|
<spec>XMPP Core</spec>
|
||
|
|
<spec>XEP-0004</spec>
|
||
|
|
</dependencies>
|
||
|
|
<supersedes/>
|
||
|
|
<supersededby/>
|
||
|
|
<shortname>NOT_YET_ASSIGNED</shortname>
|
||
|
|
<author>
|
||
|
|
<firstname>Peter</firstname>
|
||
|
|
<surname>Waher</surname>
|
||
|
|
<email>peter.waher@clayster.com</email>
|
||
|
|
<jid>peter.waher@jabber.org</jid>
|
||
|
|
<uri>http://www.linkedin.com/in/peterwaher</uri>
|
||
|
|
</author>
|
||
|
|
<revision>
|
||
|
|
<version>0.0.1</version>
|
||
|
|
<date>2013-07-23</date>
|
||
|
|
<initials>pw</initials>
|
||
|
|
<remark>
|
||
|
|
<p>First draft.</p>
|
||
|
|
</remark>
|
||
|
|
</revision>
|
||
|
|
</header>
|
||
|
|
<section1 topic='Introduction' anchor='intro'>
|
||
|
|
<p>
|
||
|
|
Data forms are used in many XEPs and provide a mechanism whereby a form can be hosted on one end and displayed on another. XMPP data forms are
|
||
|
|
defined and enhanced in many different XEPs, as is shown in the following list:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
&xep0004; defines the basics of data forms: How forms are defined, sent to the recipient, how the recipient submits forms (or cancels them)
|
||
|
|
and how results can be returned. It defines the concepts of field, field type and field value.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
&xep0122; enhances the data forms architecture permitting rules for client-side validation of fields in the form.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
&xep0137; defines a new data type that can be used to publish file upload controls.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
&xep0141; enhances the data forms architecture permitting the form to have pages or tabs with sections containing grouped controls.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
&xep0221; defines a means to include content such as images, video or audio in forms.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
&xep0331; permits the publication of color fields, where the end user can be presented with a color picker dialog instead of having to
|
||
|
|
enter a color value manually or select one from a limited list of colors.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>
|
||
|
|
This specification enhances the data form model further by providing the following features:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
Form post-back when fields flagged for post-back are edited. This permits the form to adapt itself based on user input, i.e. creating, changing
|
||
|
|
or removing fields in the form, creating dynamic forms. It also provides a mechanism to publish server-side validation of fields during user input.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
Allows fields to be disabled. They will be shown as normal controls, but in a disabled state. Combining post-back form
|
||
|
|
fields it is possible to enable and disable (or add or remove) fields depending on user input.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
Allows fields to have not well-defined values. This can be used for instance, when a value is unknown or when multiple objects
|
||
|
|
are edited at the same time in the same form and the objects have different values for the corresponding field.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
<li>
|
||
|
|
<p>
|
||
|
|
Permits fields to have errors flagged on them. This can be used to give users intuitive feedback on errors in forms. Together
|
||
|
|
with post-back fields, this provides a mechanism whereby server-side validation of fields can be made while the user is still
|
||
|
|
editing the form.
|
||
|
|
</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> This extension is only dependent upon the <link url='http://xmpp.org/extensions/xep-0004.html'>Data Forms</link> XEP. It works in
|
||
|
|
parallel with any of the above mentioned data form extensions, but do not require that any of them are supported. The examples provided
|
||
|
|
in this document may still reference extensions made in other documents, but these are considered to be examples only, used to illustrate
|
||
|
|
a specific point or example.
|
||
|
|
</p>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='Glossary' anchor='glossary'>
|
||
|
|
<p>The following table lists terms and corresponding descriptions or definitions for use throughout this document.</p>
|
||
|
|
<dl>
|
||
|
|
<di>
|
||
|
|
<dt>Control</dt>
|
||
|
|
<dd>
|
||
|
|
The visual control used to display a <strong>field</strong>.
|
||
|
|
</dd>
|
||
|
|
</di>
|
||
|
|
<di>
|
||
|
|
<dt>Data Form</dt>
|
||
|
|
<dd>
|
||
|
|
A form of parameters (a.k.a. fields), as defined in <link url='http://xmpp.org/extensions/xep-0004.html'>Data Forms</link>.
|
||
|
|
</dd>
|
||
|
|
</di>
|
||
|
|
<di>
|
||
|
|
<dt>Field</dt>
|
||
|
|
<dd>
|
||
|
|
A field representing a parameter or control, in a data form, as defined in <link url='http://xmpp.org/extensions/xep-0004.html'>Data Forms</link>.
|
||
|
|
</dd>
|
||
|
|
</di>
|
||
|
|
<di>
|
||
|
|
<dt>Form Client</dt>
|
||
|
|
<dd>
|
||
|
|
For simplicity, we will call the XMPP client that fills in the data form, the <strong>form client</strong>.
|
||
|
|
</dd>
|
||
|
|
</di>
|
||
|
|
<di>
|
||
|
|
<dt>Form Server</dt>
|
||
|
|
<dd>
|
||
|
|
For simplicity, we will call the XMPP client that hosts a data form, the <strong>form server</strong>.
|
||
|
|
</dd>
|
||
|
|
</di>
|
||
|
|
<di>
|
||
|
|
<dt>Parameter</dt>
|
||
|
|
<dd>
|
||
|
|
Used sometimes synonymously with <strong>field</strong>.
|
||
|
|
</dd>
|
||
|
|
</di>
|
||
|
|
</dl>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='Use Cases' anchor='usecases'>
|
||
|
|
<p>
|
||
|
|
The following subsections list use cases for the different enhancements defined by this extension. Elements are defined using the namespace
|
||
|
|
<strong>http://jabber.org/protocol/xdata-dynamic</strong> and namespace prefix <strong>xdd</strong>.
|
||
|
|
</p>
|
||
|
|
<section2 topic='Publishing post-back fields'>
|
||
|
|
<p>
|
||
|
|
Post-back fields are fields that require the client to post the form to the server after being edited. This permits the server
|
||
|
|
to perform server-side validation on the field, provide immediate user feed-back and change the form according to user input.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Post-back fields are declared as normal fields in a form, except they also have the <strong>xdd:postBack</strong> flag present in
|
||
|
|
the declaration, as is shown in the following example:
|
||
|
|
</p>
|
||
|
|
<example caption='Publishing post-back fields'>
|
||
|
|
<![CDATA[
|
||
|
|
<x xmlns="jabber:x:data" type="form"
|
||
|
|
xmlns:xdd="http://jabber.org/protocol/xdata-dynamic"
|
||
|
|
xmlns:xdv="http://jabber.org/protocol/xdata-validate">
|
||
|
|
<title>Current location</title>
|
||
|
|
<instructions>Select your current location to continue.</instructions>
|
||
|
|
<field var='xdd session' type='hidden'>
|
||
|
|
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
|
||
|
|
</field>
|
||
|
|
<field var="Country_ISO_3166_1" type="list-single" label="Country:">
|
||
|
|
<desc>Select your country of residence.</desc>
|
||
|
|
<xdv:validate xmlns:xdv="http://jabber.org/protocol/xdata-validate" datatype="xs:string">
|
||
|
|
<xdv:basic/>
|
||
|
|
</xdv:validate>
|
||
|
|
<value/>
|
||
|
|
<xdd:postBack/>
|
||
|
|
<option label="Chile">
|
||
|
|
<value>CL</value>
|
||
|
|
</option>
|
||
|
|
<option label="Sweden">
|
||
|
|
<value>SE</value>
|
||
|
|
</option>
|
||
|
|
<option label="United States">
|
||
|
|
<value>US</value>
|
||
|
|
</option>
|
||
|
|
...
|
||
|
|
</field>
|
||
|
|
</x>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> A system maintaining multiple dynamic forms open at the same time needs to maintain control
|
||
|
|
of available open forms. This can be done using a hidden session variable, as is shown in the example above. How this
|
||
|
|
is done however, is implementation specific.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Performing a server post-back'>
|
||
|
|
<p>
|
||
|
|
A server post-back is performed by sending an IQ set stanza with a <strong>formPostBack</strong> child element containing the
|
||
|
|
current state of the form. The type of the form must be <strong>submit</strong>. The client should also provide the current
|
||
|
|
user language in a <strong>xml:lang</strong> attribute, if available.
|
||
|
|
</p>
|
||
|
|
<example caption='Performing a server post-back'>
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='set'
|
||
|
|
from='formclient@clayster.com/client'
|
||
|
|
to='formserver@clayster.com'
|
||
|
|
id='1'>
|
||
|
|
<formPostBack xmlns='http://jabber.org/protocol/xdata-dynamic' xml:lang='en'>
|
||
|
|
<x xmlns="jabber:x:data" type="submit">
|
||
|
|
<field var='xdd session'>
|
||
|
|
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
|
||
|
|
</field>
|
||
|
|
<field var="Country_ISO_3166_1">
|
||
|
|
<value>CL</value>
|
||
|
|
</field>
|
||
|
|
</x>
|
||
|
|
</formPostBack>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
It is important to note that this server post-back is part of editing the form, and must not be treated by the server as a final
|
||
|
|
submission of the data form.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
As a response to a successful form post-back, the server returns a <strong>formPostBackResponse</strong> element with a result code of <strong>OK</strong>
|
||
|
|
containing a new data form, as is shown in the following example:
|
||
|
|
</p>
|
||
|
|
<example caption='Post-back response'>
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='formserver@clayster.com'
|
||
|
|
to='formclient@clayster.com/client'
|
||
|
|
id='1'>
|
||
|
|
<formPostBackResponse xmlns='http://jabber.org/protocol/xdata-dynamic' result='OK'>
|
||
|
|
<x xmlns="jabber:x:data" type="form"
|
||
|
|
xmlns:xdd="http://jabber.org/protocol/xdata-dynamic"
|
||
|
|
xmlns:xdv="http://jabber.org/protocol/xdata-validate">
|
||
|
|
<title>Current location</title>
|
||
|
|
<instructions>Select your current location to continue.</instructions>
|
||
|
|
<field var='xdd session' type='hidden'>
|
||
|
|
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
|
||
|
|
</field>
|
||
|
|
<field var="Country_ISO_3166_1" type="list-single" label="Country:">
|
||
|
|
<desc>Select your country of residence.</desc>
|
||
|
|
<xdv:validate xmlns:xdv="http://jabber.org/protocol/xdata-validate" datatype="xs:string">
|
||
|
|
<xdv:basic/>
|
||
|
|
</xdv:validate>
|
||
|
|
<value>CL</value>
|
||
|
|
<xdd:postBack/>
|
||
|
|
<option label="Chile">
|
||
|
|
<value>CL</value>
|
||
|
|
</option>
|
||
|
|
<option label="Sweden">
|
||
|
|
<value>SE</value>
|
||
|
|
</option>
|
||
|
|
<option label="United States">
|
||
|
|
<value>US</value>
|
||
|
|
</option>
|
||
|
|
...
|
||
|
|
</field>
|
||
|
|
<field var="Region_ISO_3166_2" type="list-single" label="Region:">
|
||
|
|
<desc>Select your region of residence.</desc>
|
||
|
|
<xdv:validate xmlns:xdv="http://jabber.org/protocol/xdata-validate" datatype="xs:string">
|
||
|
|
<xdv:basic/>
|
||
|
|
</xdv:validate>
|
||
|
|
<value/>
|
||
|
|
<xdd:postBack/>
|
||
|
|
<option label="Antofagasta">
|
||
|
|
<value>AN</value>
|
||
|
|
</option>
|
||
|
|
<option label="Arica y Parinacota">
|
||
|
|
<value>AP</value>
|
||
|
|
</option>
|
||
|
|
<option label="Atacama">
|
||
|
|
<value>AT</value>
|
||
|
|
</option>
|
||
|
|
...
|
||
|
|
</field>
|
||
|
|
</x>
|
||
|
|
</formPostBackResponse>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
In this example, the server adds a new parameter to the form, containing options that depend on the value of the first parameter.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> Server post-back should be made after the user is done editing a post-back field, but before actually navigating to the
|
||
|
|
next field. It should not be done while the user is editing the field. For check boxes or list boxes, it is easy for the application
|
||
|
|
to decide when the field has been edited, since the application can react to the controls click event. But for text edit boxes, you
|
||
|
|
cannot perform a server post-back only just because the text property of the control has changed. You need to wait until the user
|
||
|
|
leaves the control or something similar. However, as new fields can be added to the form, the client should wait for the response
|
||
|
|
before deciding which control is the next control to go to.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Publishing read-only fields'>
|
||
|
|
<p>
|
||
|
|
Read-only fields should be laid out on the form just as a similar but editable field would, except editing should be disabled. Together with
|
||
|
|
post-back fields, this option allows the form to enable/disable fields depending on user input. Read-only fields are declared as normal fields
|
||
|
|
in a form, except they also have the <strong>xdd:readOnly</strong> flag present in the declaration, as is shown in the following example:
|
||
|
|
</p>
|
||
|
|
<example caption='Publishing read-only fields'>
|
||
|
|
<![CDATA[
|
||
|
|
<x xmlns="jabber:x:data" type="form"
|
||
|
|
xmlns:xdd="http://jabber.org/protocol/xdata-dynamic"
|
||
|
|
xmlns:xdv="http://jabber.org/protocol/xdata-validate">
|
||
|
|
<title>Object properties</title>
|
||
|
|
<field var='xdd session' type='hidden'>
|
||
|
|
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
|
||
|
|
</field>
|
||
|
|
<field var="ID" type="text-single" label="ID:">
|
||
|
|
<desc>ID of object.</desc>
|
||
|
|
<xdv:validate xmlns:xdv="http://jabber.org/protocol/xdata-validate" datatype="xs:string">
|
||
|
|
<xdv:basic/>
|
||
|
|
</xdv:validate>
|
||
|
|
<value>Object 1</value>
|
||
|
|
<xdd:readOnly/>
|
||
|
|
</field>
|
||
|
|
<field var="RenameID" type="boolean" label="Rename object">
|
||
|
|
<desc>To avoid accidental renaming of the objcet, this box must be checked to rename the object.</desc>
|
||
|
|
<value>0</value>
|
||
|
|
<xdd:postBack/>
|
||
|
|
</field>
|
||
|
|
...
|
||
|
|
</x>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> Using this flag is different from the field type <strong>fixed</strong> defined in
|
||
|
|
<link url='http://xmpp.org/extensions/xep-0004.html'>Data Forms</link>. Fields of type <strong>fixed</strong>
|
||
|
|
can also be used to display read-only content. However, this is done as static text, and not as a disabled
|
||
|
|
control, specific for the type of content corresponding to the data in question. Using the <strong>readOnly</strong>
|
||
|
|
flag instead, gives greater flexibility when it comes to presentation, as well as permitting the form server
|
||
|
|
to enable and disable controls during the lifetime of the form.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Publishing fields with undefined values'>
|
||
|
|
<p>
|
||
|
|
There are many cases where you want to flag a control as having an <strong>undefined value</strong> or an
|
||
|
|
<strong>uncertain</strong> value, instead of simply a missing value. This permits the form client to display the
|
||
|
|
control in a specific way (for instance greyed), and omit the field when submitting the form back to the server,
|
||
|
|
to avoid errors.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
This technique can be used for instance, when editing the properties of multiple objects at the same time. Attributes
|
||
|
|
that are equal among the objects can be reported as normal fields, while attributes that have different values among
|
||
|
|
the objects, can be reported as having a value that is not the same everywhere. The client can then show the
|
||
|
|
corresponding control greyed and omitting it in submissions of the form. If the user edits the control however, the
|
||
|
|
form client can remove the flag and render the control normally. Submitting the now well-defined field value will
|
||
|
|
set the corresponding attribute in all objects to the same new value. Omitting undefined values makes sure that
|
||
|
|
the corresponding attributes are left as-is.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Fields with undefined or uncertain values are declared as normal fields in a form, except they also have the
|
||
|
|
<strong>xdd:notSame</strong> flag present in the declaration, as is shown in the following example:
|
||
|
|
</p>
|
||
|
|
<example caption='Publishing fields with undefined values'>
|
||
|
|
<![CDATA[
|
||
|
|
<x xmlns="jabber:x:data" type="form"
|
||
|
|
xmlns:xdd="http://jabber.org/protocol/xdata-dynamic"
|
||
|
|
xmlns:xdv="http://jabber.org/protocol/xdata-validate">
|
||
|
|
<title>Communication properties</title>
|
||
|
|
<field var='xdd session' type='hidden'>
|
||
|
|
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
|
||
|
|
</field>
|
||
|
|
<field var="Address" type="text-single" label="Bus Address:">
|
||
|
|
<desc>Enter the bus address of the device.</desc>
|
||
|
|
<xdv:validate xmlns:xdv="http://jabber.org/protocol/xdata-validate" datatype="xs:int">
|
||
|
|
<xdv:range min="1" max="250"/>
|
||
|
|
</xdv:validate>
|
||
|
|
<value>1</value>
|
||
|
|
<xdd:notSame/>
|
||
|
|
</field>
|
||
|
|
<field var="BaudRate" type="list-single" label="Baud rate:">
|
||
|
|
<desc>Baud rate to use when communicating with the device.</desc>
|
||
|
|
<value>2400</value>
|
||
|
|
<option label='300 baud'><value>300</value></option>
|
||
|
|
<option label='2400 baud'><value>2400</value></option>
|
||
|
|
</field>
|
||
|
|
...
|
||
|
|
</x>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
In the above example communication properties of a set of objects are edited. The form contains two fields, one address field, which will contain
|
||
|
|
unique values for each individual object and therefore be flagged with the <strong>xdd:notSame</strong> flag, and
|
||
|
|
a second baud rate field. This second field will probably contain the same value, if devices are connected to the
|
||
|
|
same bus. Therefore, the field value is not flagged with the <strong>xdd:notSame</strong> flag.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> If the <strong>xdd:notSame</strong> flag is available in a field, the field must not be
|
||
|
|
flagged as being <strong>required</strong>. They must also be omitted in any form submissions unless they have been
|
||
|
|
edited first. Furthermore, any field submitted in a post-back as described in this document, must not be returned
|
||
|
|
in the post-back response having the <strong>xdd:notSame</strong> flag.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
Notice also that there's a difference between a missing value, i.e. a field without a <strong>value</strong> element defined, and
|
||
|
|
a field with a <strong>value</strong> defined, but with the <strong>xdd:notSame</strong> flag present. In the latter example,
|
||
|
|
the value might represent the value of one of the objects in a set of objects being edited.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Publishing fields containing errors'>
|
||
|
|
<p>
|
||
|
|
A field can be flagged with an error message using the <strong>xdd:error</strong> element. Together with the post-back feature this allows
|
||
|
|
for more advanced server-side validation of field values, as is shown in the following example.
|
||
|
|
</p>
|
||
|
|
<example caption='Publishing fields with undefined values'>
|
||
|
|
<![CDATA[
|
||
|
|
<x xmlns="jabber:x:data" type="form"
|
||
|
|
xmlns:xdd="http://jabber.org/protocol/xdata-dynamic"
|
||
|
|
xmlns:xdv="http://jabber.org/protocol/xdata-validate">
|
||
|
|
<title>Expression</title>
|
||
|
|
<field var='xdd session' type='hidden'>
|
||
|
|
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
|
||
|
|
</field>
|
||
|
|
<field var="Expression" type="text-single" label="Expression:">
|
||
|
|
<desc>Enter the expression you want to plot.</desc>
|
||
|
|
<xdv:validate xmlns:xdv="http://jabber.org/protocol/xdata-validate" datatype="xs:string">
|
||
|
|
<xdv:basic/>
|
||
|
|
</xdv:validate>
|
||
|
|
<value>sin(x</value>
|
||
|
|
<xdd:postBack/>
|
||
|
|
<xdd:error>Unexpected end of expression. ) expected.</xdd:error>
|
||
|
|
</field>
|
||
|
|
...
|
||
|
|
</x>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
In the above example, the user can enter a script expression into a text box using a server-specific scripting language.
|
||
|
|
There's no way for the client to validate the script expression. However, by flagging the field with <strong>xdd:postBack</strong>
|
||
|
|
the client posts the form back to the server when the user is finished writing the expression, and the server can validate it.
|
||
|
|
In the example, the user has made an error, and the server returns the field, with an <strong>xdd:error</strong> flag, containing
|
||
|
|
an error message that can be displayed to the user in an appropriate way.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> If a field is flagged with an error, and the user starts editing it, the client should remove the error
|
||
|
|
flag of the field. The field can be flagged again with a new error flag during the next post-back.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Cancelling a dynamic form'>
|
||
|
|
<p>
|
||
|
|
The <link url='http://xmpp.org/extensions/xep-0004.html'>Data Forms</link> XEP provides a mechanism to cancel forms, by submitting the
|
||
|
|
form using <strong>type='cancel'</strong>. The <link url='http://xmpp.org/extensions/xep-0004.html'>Data Forms</link> XEP stipulates that
|
||
|
|
fields should not be included when using the form type cancel. However dynamic forms, i.e. forms containing post-back fields, will need
|
||
|
|
the fields, since any dynamic form session will be identified using hidden fields in the form. So, to cancel a dynamic form, the
|
||
|
|
<strong>xdd:cancel</strong> element with the entire submitted form should be sent to the form server using an IQ set stanza, as is shown
|
||
|
|
in the following example:
|
||
|
|
</p>
|
||
|
|
<example caption='Cancelling a dynamic form'>
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='set'
|
||
|
|
from='formclient@clayster.com/client'
|
||
|
|
to='formserver@clayster.com'
|
||
|
|
id='4'>
|
||
|
|
<cancel xmlns='http://jabber.org/protocol/xdata-dynamic'>
|
||
|
|
<x xmlns="jabber:x:data" type="submit">
|
||
|
|
<field var='xdd session'>
|
||
|
|
<value>009c7956-001c-43fb-8edb-76bcf74272c9</value>
|
||
|
|
</field>
|
||
|
|
...
|
||
|
|
</x>
|
||
|
|
</formPostBack>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
After receiving the cancel request the form server returns a cancel response having a result code of <strong>OK</strong> if the form
|
||
|
|
was found (and therefore cancelled), or <strong>NotFound</strong> if the form was not found. The following example shows an OK response:
|
||
|
|
</p>
|
||
|
|
<example caption='Dynamic form cancelled'>
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='formserver@clayster.com'
|
||
|
|
to='formclient@clayster.com/client'
|
||
|
|
id='4'>
|
||
|
|
<cancelResponse xmlns='http://jabber.org/protocol/xdata-dynamic' result='OK'/>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> If cancelling a dynamic form using the approach described in this document, there's no need to also submit
|
||
|
|
a cancel form as defined in the <link url='http://xmpp.org/extensions/xep-0004.html'>Data Forms</link> XEP. The form server automatically
|
||
|
|
makes sure the form is cancelled in all instances on the form server.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Dynamic form not found during post-back'>
|
||
|
|
<p>
|
||
|
|
It might happen that the form server does not find the dynamic form posted by the form client during a post back. Reasons for this can be
|
||
|
|
that the form does not include a post-back field, or that a form session timeout has occurred and the form server has discarded the dynamic
|
||
|
|
form to avoid memory leaks. Regardless of the reason, the form server responds using a <strong>NotFound</strong> result in the response, when
|
||
|
|
the client posts a form that is not found back.
|
||
|
|
</p>
|
||
|
|
<example caption='Dynamic form not found during post-back'>
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='formserver@clayster.com'
|
||
|
|
to='formclient@clayster.com/client'
|
||
|
|
id='2'>
|
||
|
|
<formPostBackResponse xmlns='http://jabber.org/protocol/xdata-dynamic' result='NotFound'/>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> Form post-back must only be performed on forms containing post-back fields. The form server
|
||
|
|
is not required to maintain dynamic form sessions for forms that lack post-back fields.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Other error during post-back'>
|
||
|
|
<p>
|
||
|
|
If another error occurs during post-back, the form server can inform the client about this, using the <strong>OtherError</strong>
|
||
|
|
result code, and include an <strong>error</strong> element to describe the error, as is shown in the following example:
|
||
|
|
</p>
|
||
|
|
<example caption='Other error during post-back'>
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='formserver@clayster.com'
|
||
|
|
to='formclient@clayster.com/client'
|
||
|
|
id='3'>
|
||
|
|
<formPostBackResponse xmlns='http://jabber.org/protocol/xdata-dynamic' result='OtherError'>
|
||
|
|
<error>An internal error occurred: Stack limit has been reached.</error>
|
||
|
|
</formPostBackResponse>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
</section2>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='Determining Support' anchor='support'>
|
||
|
|
<p>If an entity supports the protocol specified herein, regardless if the entity represents a form server or a form client; it MUST advertise
|
||
|
|
that fact by returning a feature of "http://jabber.org/protocol/xdata-dynamic" in response to &xep0030; information requests.</p>
|
||
|
|
<example caption="Service discovery information request">
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='get'
|
||
|
|
from='formclient@clayster.com/client'
|
||
|
|
to='formserver@clayster.com'
|
||
|
|
id='disco1'>
|
||
|
|
<query xmlns='http://jabber.org/protocol/disco#info'/>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
<example caption="Service discovery information response">
|
||
|
|
<![CDATA[
|
||
|
|
<iq type='result'
|
||
|
|
from='formserver@clayster.com'
|
||
|
|
to='formclient@clayster.com/client'
|
||
|
|
id='disco1'>
|
||
|
|
<query xmlns='http://jabber.org/protocol/disco#info'>
|
||
|
|
...
|
||
|
|
<feature var='http://jabber.org/protocol/xdata-dynamic'/>
|
||
|
|
...
|
||
|
|
</query>
|
||
|
|
</iq>]]>
|
||
|
|
</example>
|
||
|
|
<p>
|
||
|
|
In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined
|
||
|
|
in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.
|
||
|
|
</p>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='Implementation Notes' anchor='impl'>
|
||
|
|
<section2 topic='Dynamic Form Sessions'>
|
||
|
|
<p>
|
||
|
|
For a form server to maintain the status of the dynamic form, it will probably need to publish state or session
|
||
|
|
information using hidden fields in the dynamic form. It's important that form clients be aware that such hidden
|
||
|
|
fields are available and must always return them in all submissions of the form to the server.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
A form client that supports dynamic forms and opens a dynamic form, i.e. containing parameters requiring post-back,
|
||
|
|
must call the specific <strong>cancel</strong> method described in this document to cancel the form if not
|
||
|
|
submitted. This to let the form server to release any dynamic form session resources it maintains.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<strong>Note:</strong> When submitting a dynamic form the normal way, any dynamic form session resources are also
|
||
|
|
automatically released.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
<section2 topic='Session Timeouts'>
|
||
|
|
<p>
|
||
|
|
The form server must be aware that some form clients do not support dynamic forms. This in turn implies that form clients
|
||
|
|
may not call the correct cancel method to cancel a dynamic form. To protect the form server from memory leaks, it must
|
||
|
|
include a session timeout, and release any dynamic form session resources if no activity has been made during the
|
||
|
|
corresponding time period. If the client would perform a post-back after the timeout period, a <strong>NotFound</strong>
|
||
|
|
error message must be returned, to show the corresponding dynamic form session no longer exists, and therefore could
|
||
|
|
not be found.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
For normal operations, a dynamic form session timeout of 15 minutes is sufficient.
|
||
|
|
</p>
|
||
|
|
</section2>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='Security Considerations' anchor='security'>
|
||
|
|
<p>
|
||
|
|
There are no security concerns related to this specification above, beyond those described in the relevant section of <strong>XMPP Core</strong>.
|
||
|
|
</p>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='IANA Considerations' anchor='iana'>
|
||
|
|
<p>
|
||
|
|
<p>This document requires no interaction with &IANA;.</p>
|
||
|
|
</p>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
||
|
|
<p>
|
||
|
|
The <link url="#schema">protocol schema</link> needs to be added to the list of <link url="http://xmpp.org/resources/schemas/">XMPP protocol schemas</link>.
|
||
|
|
</p>
|
||
|
|
</section1>
|
||
|
|
<section1 topic='XML Schema' anchor='schema'>
|
||
|
|
<code>
|
||
|
|
<![CDATA[
|
||
|
|
<?xml version='1.0' encoding='UTF-8'?>
|
||
|
|
<xs:schema
|
||
|
|
xmlns:xs='http://www.w3.org/2001/XMLSchema'
|
||
|
|
targetNamespace='http://jabber.org/protocol/xdata-dynamic'
|
||
|
|
xmlns='http://jabber.org/protocol/xdata-dynamic'
|
||
|
|
xmlns:xd="jabber:x:data"
|
||
|
|
elementFormDefault='qualified'>
|
||
|
|
|
||
|
|
<xs:import namespace='jabber:x:data'/>
|
||
|
|
|
||
|
|
<xs:element name='postBack'>
|
||
|
|
<xs:annotation>
|
||
|
|
<xs:documentation>Flags a field as requiring server post-back after having been edited.</xs:documentation>
|
||
|
|
</xs:annotation>
|
||
|
|
<xs:complexType/>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:element name='readOnly'>
|
||
|
|
<xs:annotation>
|
||
|
|
<xs:documentation>Flags a field as being read-only.</xs:documentation>
|
||
|
|
</xs:annotation>
|
||
|
|
<xs:complexType/>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:element name='notSame'>
|
||
|
|
<xs:annotation>
|
||
|
|
<xs:documentation>Flags a field as having an undefined or uncertain value.</xs:documentation>
|
||
|
|
</xs:annotation>
|
||
|
|
<xs:complexType/>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:element name='error'>
|
||
|
|
<xs:annotation>
|
||
|
|
<xs:documentation>Flags a field as having an error.</xs:documentation>
|
||
|
|
</xs:annotation>
|
||
|
|
<xs:simpleType>
|
||
|
|
<xs:restriction base='xs:string'/>
|
||
|
|
</xs:simpleType>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:element name='formPostBack'>
|
||
|
|
<xs:complexType>
|
||
|
|
<xs:sequence>
|
||
|
|
<xs:element ref='xd:x' minOccurs='1' maxOccurs='1'/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:element name='formPostBackResponse'>
|
||
|
|
<xs:complexType>
|
||
|
|
<xs:choice>
|
||
|
|
<xs:element ref='xd:x' minOccurs='0' maxOccurs='1'/>
|
||
|
|
<xs:element name='error' type='xs:string' minOccurs='0' maxOccurs='1'/>
|
||
|
|
</xs:choice>
|
||
|
|
<xs:attribute name='result' type='PostBackResultCode' use='required'/>
|
||
|
|
</xs:complexType>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:simpleType name='PostBackResultCode'>
|
||
|
|
<xs:restriction base='xs:string'>
|
||
|
|
<xs:enumeration value='OK'/>
|
||
|
|
<xs:enumeration value='NotFound'/>
|
||
|
|
<xs:enumeration value='OtherError'/>
|
||
|
|
</xs:restriction>
|
||
|
|
</xs:simpleType>
|
||
|
|
|
||
|
|
<xs:element name='cancel'>
|
||
|
|
<xs:complexType>
|
||
|
|
<xs:sequence>
|
||
|
|
<xs:element ref='xd:x' minOccurs='1' maxOccurs='1'/>
|
||
|
|
</xs:sequence>
|
||
|
|
</xs:complexType>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
<xs:element name='cancelResponse'>
|
||
|
|
<xs:complexType>
|
||
|
|
<xs:attribute name='result' type='PostBackResultCode' use='required'/>
|
||
|
|
</xs:complexType>
|
||
|
|
</xs:element>
|
||
|
|
|
||
|
|
</xs:schema>]]>
|
||
|
|
</code>
|
||
|
|
</section1>
|
||
|
|
</xep>
|