JEP-0141: Data Forms Layout

<x xmlns='jabber:x:data' type='form'>
  <title>JSF 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.jeps' type='text-multi' label='JEPs Authored or Co-Authored'>
  </field>
</x>
  

3.1 Paging Fields

One of the simplest layout usages is to separate fields into pages. This is done by including one or more <page/> elements within the x:data form. Each <page/> SHOULD have a "label" attribute to label the page, MAY include a <desc/> for additional information, and SHOULD include a <fieldref/> for each field to be included in the page. To reference an x:data field, the <fieldref/> element's "var" attribute MUST equal the intended <field/>s "var" attribute.

Example 2. Pages of fields

<x xmlns='jabber:x:data' type='form'>
  ...
  
  <page xmlns='http://jabber.org/protocol/xdata-layout' label='Personal Information'>
    <fieldref var='name.first'/>
    <fieldref var='name.last'/>
    <fieldref var='email'/>
    <fieldref var='jid'/>
    <fieldref var='background'/>
  </page>
  <page label='Community Activity'>
    <fieldref var='activity.mailing-lists'/>
    <fieldref var='activity.jeps'/>
  </page>
  <page label='Plans and Reasonings'>
    <fieldref var='future'/>
    <fieldref var='reasoning'/>
  </page>
  
  ...
</x>
    

The preceding example partitions the fields into three pages; labeled "Personal Information", "Community Activity", and "Plans and Reasonings".

If a <fieldref/> within a <page/> references a non-existent <field/>, that reference MUST be ignored.

3.2 Sectioning Fields

The next usage of layout is by sections within pages. This is done by including one or more <section/> elements within each <page/>. Each <section/> SHOULD have a "label" attribute to identify the section, MAY include a <desc/> for additional information, and SHOULD include a <fieldref/> for each field to be included in the section. A <section/> MUST contain at least one <fieldref/> or <reportedref/>. To reference an x:data field, the <fieldref/> element's "var" attribute MUST equal the intended <field/> element's "var" attribute.

Example 3. Sections of fields

<x xmlns='jabber:x:data' type='form'>
  ...
  
  <page xmlns='http://jabber.org/protocol/xdata-layout'>
    <section label='Personal Information'>
      <fieldref var='name.first'/>
      <fieldref var='name.last'/>
      <fieldref var='email'/>
      <fieldref var='jid'/>
      <fieldref var='background'/>
    </section>
    <section label='Community Activity'>
      <fieldref var='activity.mailing-lists'/>
      <fieldref var='activity.jeps'/>
    </section>
    <section label='Plans and Reasoning'>
      <fieldref var='future'/>
      <fieldref var='reasoning'/>
    </section>
  </page>
  
  ...
</x>
    

The preceeding example demonstrates a similar layout to the one previous, but using sections instead of pages.

Sections MAY be nested, to produce a more granular partitioning of fields.

Example 4. Sections of fields (nested)

<x xmlns='jabber:x:data' type='form'>
  ...
  
  <page xmlns='http://jabber.org/protocol/xdata-layout'>
    <section label='Personal Information'>
      <section label='Name'>
        <fieldref var='name.first'/>
        <fieldref var='name.last'/>
      </section>
      <section label='Contact Information'>
        <fieldref var='email'/>
        <fieldref var='jid'/>
      </section>
      <fieldref var='background'/>
    </section>
    <section label='Community Activity'>
      <fieldref var='activity.mailing-lists'/>
      <fieldref var='activity.jeps'/>
    </section>
    <section label='Plans and Reasoning'>
      <fieldref var='future'/>
      <fieldref var='reasoning'/>
    </section>
  </page>
  
  ...
</x>
    

If a <fieldref/> within a <section/> references a non-existent <field/>, that reference MUST be ignored.

3.3 Including Tables

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 the <fieldref/> is allowed, and MUST appear once at most.

If a <reportedref/> is specified when no <reported/> is available, the reference MUST be ignored.

4.1 Discovery

Form providers MAY attempt to discover if the recipient of a form supports styling, although implementations are NOT REQUIRED to do so. Discovery is implemened as defined in Service Discovery [2], using the namespace "http://jabber.org/protocol/xdata-layout" as a feature.

4.2 Field Distribution

In order to prevent the processing from becoming too complex, there are some restrictions in how fields are distributed within the layout.

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 have a "FIXED" field included in the layout, it MUST have a "var" attribute.

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.

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.

4.3 Page Labels and Descriptions

The "label" attribute for <page/> is OPTIONAL, although RECOMMENDED. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing). Usually the containing form's <title/> is used.

The <desc/> element for <page/> is OPTIONAL. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing). Usually the containing form's <instructions/> is used.

4.4 Section Labels and Descriptions

The "label" attribute for <section/> is OPTIONAL, although RECOMMENDED. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).

The <desc/> element for <section/> is OPTIONAL. If it is missing, the renderer MAY use whatever it deems appropriate (including nothing).

4.5 Internationalization/Localization

This JEP relies on the internationalization/localization mechanisms provided by XMPP Core [3]. Specifically, labels and descriptions MUST be appropriate for the locale indicated by the containing <form/> or stanza.

8.1 <page/> Root Element

The <page/> element is the root layout element for "http://jabber.org/protocol/xdata-layout" namespace. One <page/> elements are contained within the <x xmlns='jabber:x:data'/> element for each rendering page. The <page/> element possesses an attribute for its label, and contains child elements for its description, sections, and field and table references.

The 'label' attribute specifies the label for this <page/>. This attribute is OPTIONAL. Its value is any string.

8.2 <section/> Element

The <section/> element is used to further partition the layout within a <page/>. The <section/> element possesses an attribute for its label, and contains child elements for its description, sections, and field and table references.

The 'label' attribute specifies the label for this <section/>. This attribute is OPTIONAL. Its value is any string.

8.3 <fieldref/> Element

The <fieldref/> element is used to place a form field within the layout. The <fieldref/> possesses a single attribute to identify the field it references, and is otherwise empty.

The 'var' attribute specifies the form field being referenced. This attribute is REQUIRED, and its value SHOULD be equal to one of the <field/> "var" attributes in the containing form.

8.4 <reportedref/> Element

The <reportedref/> element is used to place a form "table" (as described by the <reported/< and <item/> elements) within the layout. The <reportedref/> element has no attributes or children.

8.5 <desc/> Element

The <desc/> element is used to provide additional textual information for a <page/> or <section/>. Its XML character data is the description text.

8.6 XML Schema

<?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-validate'
    elementFormDefault='qualified'>

  <xs:element name='page'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='unbounded'>
        <xs:element ref='desc' 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='desc' minOccurs='0' maxOccurs='unbounded'/>
        <xs:element ref='section'/>
        <xs:element ref='fieldref'/>
        <xs:element ref='reportedref'/>
      </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='desc' type='xs:string'/>
  
  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

Version 0.1 (2004-08-10)