<?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 Layout</title> <abstract>This document defines an extension to the Data Forms protocol enabling an application to specify form layouts.</abstract> &LEGALNOTICE; <number>0141</number> <status>Draft</status> <type>Standards Track</type> <sig>Standards</sig> <dependencies> <spec>XMPP Core</spec> <spec>XEP-0004</spec> </dependencies> <supersedes/> <supersededby/> <shortname>xdata-layout</shortname> <schemaloc> <url>http://www.xmpp.org/schemas/xdata-layout.xsd</url> </schemaloc> &linuxwolf; <revision> <version>1.0</version> <date>2005-05-12</date> <initials>psa</initials> <remark>Per a vote of the Jabber Council, advanced status to Draft.</remark> </revision> <revision> <version>0.3</version> <date>2005-05-03</date> <initials>psa</initials> <remark>Renamed <desc/> element to <text/> to avoid confusion with XEP-0004 element names; clarified formal definition of <text/> element; added <text/> elements to examples.</remark> </revision> <revision> <version>0.2</version> <date>2005-03-28</date> <initials>psa</initials> <remark>Editorial review: cleanup of text, examples, and schema.</remark> </revision> <revision> <version>0.1</version> <date>2004-08-10</date> <initials>lw</initials> <remark>Initial version.</remark> </revision> </header> <section1 topic='Introduction' anchor='intro'> <p>&xep0004; ("x:data") provides a simple and interoperable way to request and present information for both applications and humans. However, the simple nature of "x:data" requires the form renderer to use a generic "key/value" format. This document builds upon "x:data" to enable applications to specify additional layout information.</p> </section1> <section1 topic='Requirements' anchor='reqs'> <p>The requirements for this document are:</p> <ul> <li>Provide hints for laying out form fields in pages.</li> <li>Provide hints for laying out pages in sections.</li> <li>Provide hints for laying out sections in subsections.</li> <li>Ensure backwards-compatibility with the existing "x:data" protocol.</li> </ul> </section1> <section1 topic='Use Cases' anchor='usecases'> <p>This document defines a new namespace, "http://jabber.org/protocol/xdata-layout". All layout is defined by "pages" and "sections".</p> <p>All of the use cases refer to the following form:</p> <example caption='Sample form'><![CDATA[ <x xmlns='jabber:x:data' type='form'> <title>XSF Application</title> <instructions>Please fill out this form</instructions> <field var='name.first' type='text-single' label='First Name'> <required/> </field> <field var='name.last' type='text-single' label='Last Name'> <required/> </field> <field var='email' type='text-single' label='E-mail Address'> <required/> </field> <field var='jid' type='jid-single' label='Jabber JID'> <required/> </field> <field var='background' type='text-multi' label='Background Information'> </field> <field var='future' type='text-multi' label='Jabber Plans for the Next Six Months'> </field> <field var='reasoning' type='text-multi' label='Reasons for Joining'> </field> <field var='activity.mailing-lists' type='text-multi' label='Recent Mailing List Activity'> </field> <field var='activity.xeps' type='text-multi' label='XEPs Authored or Co-Authored'> </field> </x> ]]></example> <p>Note: Any newlines in the following examples are provided for the purpose of legibility only.</p> <section2 topic='Paging Fields' anchor='paging'> <p>One of the simplest layout usages is to partition fields into pages. This is done by including one or more <page/> elements within the x:data form. Each <page/> element SHOULD possess a "label" attribute to label the page, MAY contain a <text/> child element for additional information, and SHOULD contain a <fieldref/> element for each field to be included in the page. To reference an x:data field, the <fieldref/> element's "var" attribute MUST be the same as the intended <field/> element's "var" attribute.</p> <example caption='Pages of fields'><![CDATA[ <x xmlns='jabber:x:data' type='form'> <title>XSF Application</title> <instructions>Please fill out this form</instructions> <page xmlns='http://jabber.org/protocol/xdata-layout' label='Personal Information'> <text>This is page one of three.</text> <text> Note: In accordance with the XSF privacy policy, your personal information will never be shared outside the organization in any way for any purpose; however, your name and JID may be published in the XSF membership directory. </text> <fieldref var='name.first'/> <fieldref var='name.last'/> <fieldref var='email'/> <fieldref var='jid'/> <fieldref var='background'/> </page> <page xmlns='http://jabber.org/protocol/xdata-layout' label='Community Activity'> <text>This is page two of three.</text> <text> We use this page to gather information about any XEPs you've worked on, as well as your mailing list activity. </text> <text>You do post to the mailing lists, don't you?</text> <fieldref var='activity.mailing-lists'/> <fieldref var='activity.xeps'/> </page> <page xmlns='http://jabber.org/protocol/xdata-layout' label='Plans and Reasonings'> <text>This is page three of three.</text> <text>You're almost done!</text> <text> This is where you describe your future plans and why you think you deserve to be a member of the XMPP Standards Foundation. </text> <fieldref var='future'/> <fieldref var='reasoning'/> </page> <field var='name.first' type='text-single' label='First Name'> <required/> </field> <field var='name.last' type='text-single' label='Last Name'> <required/> </field> <field var='email' type='text-single' label='E-mail Address'> <required/> </field> <field var='jid' type='jid-single' label='Jabber JID'> <required/> </field> <field var='background' type='text-multi' label='Background Information'> </field> <field var='future' type='text-multi' label='Jabber Plans for the Next Six Months'> </field> <field var='reasoning' type='text-multi' label='Reasons for Joining'> </field> <field var='activity.mailing-lists' type='text-multi' label='Recent Mailing List Activity'> </field> <field var='activity.xeps' type='text-multi' label='XEPs Authored or Co-Authored'> </field> </x> ]]></example> <p>Note: The preceding example partitions the fields into three pages, labeled "Personal Information", "Community Activity", and "Plans and Reasonings".</p> </section2> <section2 topic='Sectioning Fields' anchor='sectioning'> <p>The next usage of layout is to partition pages into sections. This is done by including one or more <section/> elements within each <page/> element. Each <section/> element SHOULD possess a "label" attribute to identify the section, MAY contain a <text/> child element for additional information, and SHOULD contain a <fieldref/> element for each field to be included in the section. A <section/> element MUST contain at least one <fieldref/> element or <reportedref/> element. To reference an x:data field, the <fieldref/> element's "var" attribute MUST be the same as the intended <field/> element's "var" attribute.</p> <example caption='Sections of fields'><![CDATA[ <x xmlns='jabber:x:data' type='form'> <title>XSF Application</title> <instructions>Please fill out this form</instructions> <page xmlns='http://jabber.org/protocol/xdata-layout'> <section label='Personal Information'> <text> Note: In accordance with the XSF privacy policy, your personal information will never be shared outside the organization in any way for any purpose; however, your name and JID may be published in the XSF membership directory. </text> <fieldref var='name.first'/> <fieldref var='name.last'/> <fieldref var='email'/> <fieldref var='jid'/> <fieldref var='background'/> </section> <section label='Community Activity'> <text> We use this page to gather information about any XEPs you've worked on, as well as your mailing list activity. </text> <text>You do post to the mailing lists, don't you?</text> <fieldref var='activity.mailing-lists'/> <fieldref var='activity.xeps'/> </section> <section label='Plans and Reasoning'> <text>You're almost done!</text> <text> This is where you describe your future plans and why you think you deserve to be a member of the XMPP Standards Foundation. </text> <fieldref var='future'/> <fieldref var='reasoning'/> </section> </page> <field var='name.first' type='text-single' label='First Name'> <required/> </field> <field var='name.last' type='text-single' label='Last Name'> <required/> </field> <field var='email' type='text-single' label='E-mail Address'> <required/> </field> <field var='jid' type='jid-single' label='Jabber JID'> <required/> </field> <field var='background' type='text-multi' label='Background Information'> </field> <field var='future' type='text-multi' label='Jabber Plans for the Next Six Months'> </field> <field var='reasoning' type='text-multi' label='Reasons for Joining'> </field> <field var='activity.mailing-lists' type='text-multi' label='Recent Mailing List Activity'> </field> <field var='activity.xeps' type='text-multi' label='XEPs Authored or Co-Authored'> </field> </x> ]]></example> <p>Note: The preceding example demonstrates a layout similar to the previous example, but using three sections within one page instead of three pages.</p> <p>As shown in the following example, sections may be nested to produce a more granular partitioning of fields.</p> <example caption='Sections of fields (nested)'><![CDATA[ <x xmlns='jabber:x:data' type='form'> ... <page xmlns='http://jabber.org/protocol/xdata-layout'> <section label='Personal Information'> <text> Note: In accordance with the XSF privacy policy, your personal information will never be shared outside the organization in any way for any purpose; however, your name and JID may be published in the XSF membership directory. </text> <section label='Name'> <text>Who are you?</text> <fieldref var='name.first'/> <fieldref var='name.last'/> </section> <section label='Contact Information'> <text>How can we contact you?</text> <fieldref var='email'/> <fieldref var='jid'/> </section> <fieldref var='background'/> </section> <section label='Community Activity'> <text> We use this page to gather information about any XEPs you've worked on, as well as your mailing list activity. </text> <text>You do post to the mailing lists, don't you?</text> <fieldref var='activity.mailing-lists'/> <fieldref var='activity.xeps'/> </section> <section label='Plans and Reasoning'> <text> This is where you describe your future plans and why you think you deserve to be a member of the XMPP Standards Foundation. </text> <fieldref var='future'/> <fieldref var='reasoning'/> </section> </page> ... </x> ]]></example> <p>Note: The preceding example partitions the fields into one page and three sections, with the first section being further partitioned into two sub-sections and one free-standing field reference.</p> </section2> <section2 topic="Including Tables" anchor='tables'> <p>Data forms tables (the <reported/> and <item/> elements) can also be included in the layout, using the <reportedref/> element. This element MAY be included anywhere that the <fieldref/> element is allowed, but MUST NOT appear more than once.</p> <p>If a <reportedref/> element is specified when no <reported/> element is included, then the reference MUST be ignored.</p> </section2> </section1> <section1 topic='Business Rules' anchor='bizrules'> <section2 topic='Discovery' anchor='bizrules-disco'> <p>Form providers MAY attempt to discover if the recipient of a form supports the data forms layout protocol extension, although implementations are not required to do so. If implemented, Discovery MUST be implemened as defined in &xep0030;, using the namespace "http://jabber.org/protocol/xdata-layout" as a feature.</p> </section2> <section2 topic='Field Distribution' anchor='bizrules-distribution'> <p>In order to prevent the processing from becoming too complex, there are some restrictions in how fields are distributed within the layout.</p> <p>First, all displayable, modifiable fields (e.g. all except fields of type "FIXED" or "HIDDEN") SHOULD be referenced by a page or section. Any that are not referenced MAY NOT be rendered, although implementations MAY provide some support for this. To include a "FIXED" field in the layout, it MUST possess a "var" attribute.</p> <p>Second, the same field SHOULD NOT be referenced by more than one page or section. Additionally, a field SHOULD NOT be referenced by the same page or section more than once.</p> <p>Finally, the order of layout elements SHOULD be maintained. Pages SHOULD be rendered in the order they are defined within the x:data form, and sections and fields SHOULD be rendered in the order they are defined or referenced within a page or section.</p> </section2> <section2 topic='Page Labels and Descriptions' anchor='bizrules-pages'> <p>The "label" attribute of the <page/> element is RECOMMENDED (although not required). If it is missing, the renderer MAY display whatever it deems appropriate (including nothing or character data of the containing form's <title/> element).</p> <p>The <text/> child element of the <page/> element is OPTIONAL. If it is missing, the renderer MAY display whatever it deems appropriate (including nothing or character data of the containing form's <instructions/> element).</p> </section2> <section2 topic='Section Labels and Descriptions' anchor='bizrules-sections'> <p>The "label" attribute of the <section/> element RECOMMENDED (but not required). If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).</p> <p>The <text/> child element of the <section/> element is OPTIONAL. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).</p> </section2> <section2 topic='Internationalization/Localization' anchor='bizrules-i18n'> <p>This document relies on the internationalization/localization mechanisms provided by &xmppcore;. Specifically, labels and descriptions MUST be appropriate for the locale indicated by the containing stanza or <form/> element.</p> </section2> </section1> <section1 topic='Security Considerations' anchor='security'> <p>There are no security considerations introduced by this document.</p> </section1> <section1 topic='IANA Considerations' anchor='iana'> <p>This document requires no interaction with &IANA;.</p> </section1> <section1 topic='XMPP Registrar Considerations' anchor='registrar'> <section2 topic='Protocol Namespaces' anchor='registrar-ns'> <p>The ®ISTRAR; includes 'http://jabber.org/protocol/xdata-layout' in its registry of protocol namespaces.</p> </section2> </section1> <section1 topic='Formal Definition' anchor='def'> <section2 topic='<page/> Root Element' anchor='def-page'> <p>The <page/> element is the root layout element for "http://jabber.org/protocol/xdata-layout" namespace. One <page/> elements is contained within the <x xmlns='jabber:x:data'/> element for each page to be rendered. The <page/> element MAY possess an attribute that specifies a natural-language label for the page, and MAY contain child elements specifying a description, sections of the page, and field and table references.</p> <p>The 'label' attribute specifies the label for this page. This attribute is OPTIONAL. Its value is any string.</p> </section2> <section2 topic='<section/> Element' anchor='def-section'> <p>The <section/> element is used to further partition the layout within a page. The <section/> element MAY possess an attribute that specifies a natural-language label for the section, and MAY contain child elements specifying a description, subsections, and field and table references.</p> <p>The 'label' attribute specifies the label for this section. This attribute is OPTIONAL. Its value is any string.</p> </section2> <section2 topic='<fieldref/> Element' anchor='def-fieldref'> <p>The <fieldref/> element is used to situate a form field within the layout. The <fieldref/> element MUST possess a single attribute to identify the field it references, and is otherwise empty.</p> <p>If a <fieldref/> element within a <page/> or <section/> references a non-existent field, then that reference MUST be ignored.</p> <p>The 'var' attribute specifies the form field being referenced. This attribute is REQUIRED, and its value SHOULD be the same as the "var" attribute of one of the <field/> elements in the containing form.</p> </section2> <section2 topic='<reportedref/> Element' anchor='def-reportedref'> <p>The <reportedref/> element is used to situate a form "table" (as described by the <reported/< and <item/> elements) within the layout. The <reportedref/> element has no attributes or children.</p> </section2> <section2 topic='<text/> Element' anchor='def-text'> <p>The <text/> element is used to provide natural-language text that describes a page or section, provides instructions or notes about the page or section, and the like. A <page/> or <section/> element MAY contain an unbounded number of <text/> child elements. The XML character data of this element SHOULD NOT contain newlines (the \n and \r characters), and any handling of newlines (e.g., presentation in a user interface) is unspecified herein.</p> </section2> <section2 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-layout' xmlns='http://jabber.org/protocol/xdata-layout' elementFormDefault='qualified'> <xs:annotation> <xs:documentation> The protocol documented by this schema is defined in XEP-0141: http://www.xmpp.org/extensions/xep-0141.html </xs:documentation> </xs:annotation> <xs:element name='page'> <xs:complexType> <xs:choice minOccurs='0' maxOccurs='unbounded'> <xs:element ref='text' minOccurs='0' maxOccurs='unbounded'/> <xs:element ref='section' minOccurs='0' maxOccurs='unbounded'/> <xs:element ref='fieldref' minOccurs='0' maxOccurs='unbounded'/> <xs:element ref='reportedref' minOccurs='0' maxOccurs='unbounded'/> </xs:choice> <xs:attribute name='label' type='xs:string' use='optional'/> </xs:complexType> </xs:element> <xs:element name='section'> <xs:complexType> <xs:choice minOccurs='0' maxOccurs='unbounded'> <xs:element ref='text' minOccurs='0' maxOccurs='unbounded'/> <xs:element ref='section' minOccurs='0' maxOccurs='unbounded'/> <xs:element ref='fieldref' minOccurs='0' maxOccurs='unbounded'/> <xs:element ref='reportedref' minOccurs='0' maxOccurs='unbounded'/> </xs:choice> <xs:attribute name='label' type='xs:string' use='optional'/> </xs:complexType> </xs:element> <xs:element name='fieldref'> <xs:complexType> <xs:simpleContent> <xs:extension base='empty'> <xs:attribute name='var' type='xs:string' use='required'/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:element> <xs:element name='reportedref' type='empty'/> <xs:element name='text' type='xs:string'/> <xs:simpleType name='empty'> <xs:restriction base='xs:string'> <xs:enumeration value=''/> </xs:restriction> </xs:simpleType> </xs:schema> ]]></code> </section2> </section1> </xep>