<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>
<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>
<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>
<p>Note: Any newlines in the following examples are provided for the purpose of legibility only.</p>
<section2topic='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>
<p>Note: The preceding example partitions the fields into three pages, labeled "Personal Information", "Community Activity", and "Plans and Reasonings".</p>
<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>
<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>
<examplecaption='Sections of fields (nested)'><![CDATA[
<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>
<section2topic="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>
<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>
<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>
<section2topic='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>
<section2topic='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>
<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>
<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>
<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>
<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>
<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>
<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>