xep-0141.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 Layout</title>
  <abstract>This specification defines a backwards-compatible extension to the XMPP Data Forms protocol that enables an application to specify form layouts, including the layout of form fields, sections within pages, and subsections within sections.</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 &lt;desc/&gt; element to &lt;text/&gt; to avoid confusion with XEP-0004 element names; clarified formal definition of &lt;text/&gt; element; added &lt;text/&gt; 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 the layout of form fields.</li>
    <li>Provide hints for the layout of sections within pages.</li>
    <li>Provide hints for the layout of subsections within sections.</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 &lt;page/&gt; elements within the x:data form. Each &lt;page/&gt; element SHOULD possess a "label" attribute to label the page, MAY contain a &lt;text/&gt; child element for additional information, and SHOULD contain a &lt;fieldref/&gt; element for each field to be included in the page. To reference an x:data field, the &lt;fieldref/&gt; element's "var" attribute MUST be the same as the intended &lt;field/&gt; 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&apos;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 &lt;section/&gt; elements within each &lt;page/&gt; element. Each &lt;section/&gt; element SHOULD possess a "label" attribute to identify the section, MAY contain a &lt;text/&gt; child element for additional information, and SHOULD contain a &lt;fieldref/&gt; element for each field to be included in the section. A &lt;section/&gt; element MUST contain at least one &lt;fieldref/&gt; element or &lt;reportedref/&gt; element. To reference an x:data field, the &lt;fieldref/&gt; element's "var" attribute MUST be the same as the intended &lt;field/&gt; 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&apos;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&apos;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 &lt;reported/&gt; and &lt;item/&gt; elements) can also be included in the layout, using the &lt;reportedref/&gt; element. This element MAY be included anywhere that the &lt;fieldref/&gt; element is allowed, but MUST NOT appear more than once.</p>
    <p>If a &lt;reportedref/&gt; element is specified when no &lt;reported/&gt; 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 remain unrendered, 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 &lt;page/&gt; 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 &lt;title/&gt; element).</p>
    <p>The &lt;text/&gt; child element of the &lt;page/&gt; 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 &lt;instructions/&gt; element).</p>
  </section2>
  <section2 topic='Section Labels and Descriptions' anchor='bizrules-sections'>
    <p>The "label" attribute of the &lt;section/&gt; element RECOMMENDED (but not required). If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).</p>
    <p>The &lt;text/&gt; child element of the &lt;section/&gt; 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 &lt;form/&gt; 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 &REGISTRAR; includes 'http://jabber.org/protocol/xdata-layout' in its registry of protocol namespaces.</p>
  </section2>
</section1>
<section1 topic='Formal Definition' anchor='def'>
  <section2 topic='&lt;page/&gt; Root Element' anchor='def-page'>
    <p>The &lt;page/&gt; element is the root layout element for "http://jabber.org/protocol/xdata-layout" namespace. One &lt;page/&gt; elements is contained within the &lt;x xmlns='jabber:x:data'/&gt; element for each page to be rendered. The &lt;page/&gt; 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='&lt;section/&gt; Element' anchor='def-section'>
    <p>The &lt;section/&gt; element is used to further partition the layout within a page. The &lt;section/&gt; 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='&lt;fieldref/&gt; Element' anchor='def-fieldref'>
    <p>The &lt;fieldref/&gt; element is used to situate a form field within the layout. The &lt;fieldref/&gt; element MUST possess a single attribute to identify the field it references, and is otherwise empty.</p>
    <p>If a &lt;fieldref/&gt; element within a &lt;page/&gt; or &lt;section/&gt; 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 &lt;field/&gt; elements in the containing form.</p>
  </section2>
  <section2 topic='&lt;reportedref/&gt; Element' anchor='def-reportedref'>
    <p>The &lt;reportedref/&gt; element is used to situate a form "table" (as described by the &lt;reported/&lt; and &lt;item/&gt; elements) within the layout. The &lt;reportedref/&gt; element has no attributes or children.</p>
  </section2>
  <section2 topic='&lt;text/&gt; Element' anchor='def-text'>
    <p>The &lt;text/&gt; 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 &lt;page/&gt; or &lt;section/&gt; element MAY contain an unbounded number of &lt;text/&gt; 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>