No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0141.xml 20KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. ]>
  6. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  7. <xep>
  8. <header>
  9. <title>Data Forms Layout</title>
  10. <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>
  11. &LEGALNOTICE;
  12. <number>0141</number>
  13. <status>Draft</status>
  14. <type>Standards Track</type>
  15. <sig>Standards</sig>
  16. <dependencies>
  17. <spec>XMPP Core</spec>
  18. <spec>XEP-0004</spec>
  19. </dependencies>
  20. <supersedes/>
  21. <supersededby/>
  22. <shortname>xdata-layout</shortname>
  23. <schemaloc>
  24. <url>http://www.xmpp.org/schemas/xdata-layout.xsd</url>
  25. </schemaloc>
  26. &linuxwolf;
  27. <revision>
  28. <version>1.0</version>
  29. <date>2005-05-12</date>
  30. <initials>psa</initials>
  31. <remark>Per a vote of the Jabber Council, advanced status to Draft.</remark>
  32. </revision>
  33. <revision>
  34. <version>0.3</version>
  35. <date>2005-05-03</date>
  36. <initials>psa</initials>
  37. <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>
  38. </revision>
  39. <revision>
  40. <version>0.2</version>
  41. <date>2005-03-28</date>
  42. <initials>psa</initials>
  43. <remark>Editorial review: cleanup of text, examples, and schema.</remark>
  44. </revision>
  45. <revision>
  46. <version>0.1</version>
  47. <date>2004-08-10</date>
  48. <initials>lw</initials>
  49. <remark>Initial version.</remark>
  50. </revision>
  51. </header>
  52. <section1 topic='Introduction' anchor='intro'>
  53. <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>
  54. </section1>
  55. <section1 topic='Requirements' anchor='reqs'>
  56. <p>The requirements for this document are:</p>
  57. <ul>
  58. <li>Provide hints for the layout of form fields.</li>
  59. <li>Provide hints for the layout of sections within pages.</li>
  60. <li>Provide hints for the layout of subsections within sections.</li>
  61. <li>Ensure backwards-compatibility with the existing "x:data" protocol.</li>
  62. </ul>
  63. </section1>
  64. <section1 topic='Use Cases' anchor='usecases'>
  65. <p>This document defines a new namespace, "http://jabber.org/protocol/xdata-layout". All layout is defined by "pages" and "sections".</p>
  66. <p>All of the use cases refer to the following form:</p>
  67. <example caption='Sample form'><![CDATA[
  68. <x xmlns='jabber:x:data' type='form'>
  69. <title>XSF Application</title>
  70. <instructions>Please fill out this form</instructions>
  71. <field var='name.first' type='text-single' label='First Name'>
  72. <required/>
  73. </field>
  74. <field var='name.last' type='text-single' label='Last Name'>
  75. <required/>
  76. </field>
  77. <field var='email' type='text-single' label='E-mail Address'>
  78. <required/>
  79. </field>
  80. <field var='jid' type='jid-single' label='Jabber JID'>
  81. <required/>
  82. </field>
  83. <field var='background' type='text-multi' label='Background Information'>
  84. </field>
  85. <field var='future' type='text-multi' label='Jabber Plans for the Next Six Months'>
  86. </field>
  87. <field var='reasoning' type='text-multi' label='Reasons for Joining'>
  88. </field>
  89. <field var='activity.mailing-lists' type='text-multi' label='Recent Mailing List Activity'>
  90. </field>
  91. <field var='activity.xeps' type='text-multi' label='XEPs Authored or Co-Authored'>
  92. </field>
  93. </x>
  94. ]]></example>
  95. <p>Note: Any newlines in the following examples are provided for the purpose of legibility only.</p>
  96. <section2 topic='Paging Fields' anchor='paging'>
  97. <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>
  98. <example caption='Pages of fields'><![CDATA[
  99. <x xmlns='jabber:x:data' type='form'>
  100. <title>XSF Application</title>
  101. <instructions>Please fill out this form</instructions>
  102. <page xmlns='http://jabber.org/protocol/xdata-layout' label='Personal Information'>
  103. <text>This is page one of three.</text>
  104. <text>
  105. Note: In accordance with the XSF privacy policy, your personal information will
  106. never be shared outside the organization in any way for any purpose; however,
  107. your name and JID may be published in the XSF membership directory.
  108. </text>
  109. <fieldref var='name.first'/>
  110. <fieldref var='name.last'/>
  111. <fieldref var='email'/>
  112. <fieldref var='jid'/>
  113. <fieldref var='background'/>
  114. </page>
  115. <page xmlns='http://jabber.org/protocol/xdata-layout' label='Community Activity'>
  116. <text>This is page two of three.</text>
  117. <text>
  118. We use this page to gather information about any XEPs you&apos;ve worked on,
  119. as well as your mailing list activity.
  120. </text>
  121. <text>You do post to the mailing lists, don't you?</text>
  122. <fieldref var='activity.mailing-lists'/>
  123. <fieldref var='activity.xeps'/>
  124. </page>
  125. <page xmlns='http://jabber.org/protocol/xdata-layout' label='Plans and Reasonings'>
  126. <text>This is page three of three.</text>
  127. <text>You're almost done!</text>
  128. <text>
  129. This is where you describe your future plans and why you think you
  130. deserve to be a member of the XMPP Standards Foundation.
  131. </text>
  132. <fieldref var='future'/>
  133. <fieldref var='reasoning'/>
  134. </page>
  135. <field var='name.first' type='text-single' label='First Name'>
  136. <required/>
  137. </field>
  138. <field var='name.last' type='text-single' label='Last Name'>
  139. <required/>
  140. </field>
  141. <field var='email' type='text-single' label='E-mail Address'>
  142. <required/>
  143. </field>
  144. <field var='jid' type='jid-single' label='Jabber JID'>
  145. <required/>
  146. </field>
  147. <field var='background' type='text-multi' label='Background Information'>
  148. </field>
  149. <field var='future' type='text-multi' label='Jabber Plans for the Next Six Months'>
  150. </field>
  151. <field var='reasoning' type='text-multi' label='Reasons for Joining'>
  152. </field>
  153. <field var='activity.mailing-lists' type='text-multi' label='Recent Mailing List Activity'>
  154. </field>
  155. <field var='activity.xeps' type='text-multi' label='XEPs Authored or Co-Authored'>
  156. </field>
  157. </x>
  158. ]]></example>
  159. <p>Note: The preceding example partitions the fields into three pages, labeled "Personal Information", "Community Activity", and "Plans and Reasonings".</p>
  160. </section2>
  161. <section2 topic='Sectioning Fields' anchor='sectioning'>
  162. <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>
  163. <example caption='Sections of fields'><![CDATA[
  164. <x xmlns='jabber:x:data' type='form'>
  165. <title>XSF Application</title>
  166. <instructions>Please fill out this form</instructions>
  167. <page xmlns='http://jabber.org/protocol/xdata-layout'>
  168. <section label='Personal Information'>
  169. <text>
  170. Note: In accordance with the XSF privacy policy, your personal information will
  171. never be shared outside the organization in any way for any purpose; however,
  172. your name and JID may be published in the XSF membership directory.
  173. </text>
  174. <fieldref var='name.first'/>
  175. <fieldref var='name.last'/>
  176. <fieldref var='email'/>
  177. <fieldref var='jid'/>
  178. <fieldref var='background'/>
  179. </section>
  180. <section label='Community Activity'>
  181. <text>
  182. We use this page to gather information about any XEPs you&apos;ve worked on,
  183. as well as your mailing list activity.
  184. </text>
  185. <text>You do post to the mailing lists, don't you?</text>
  186. <fieldref var='activity.mailing-lists'/>
  187. <fieldref var='activity.xeps'/>
  188. </section>
  189. <section label='Plans and Reasoning'>
  190. <text>You're almost done!</text>
  191. <text>
  192. This is where you describe your future plans and why you think you
  193. deserve to be a member of the XMPP Standards Foundation.
  194. </text>
  195. <fieldref var='future'/>
  196. <fieldref var='reasoning'/>
  197. </section>
  198. </page>
  199. <field var='name.first' type='text-single' label='First Name'>
  200. <required/>
  201. </field>
  202. <field var='name.last' type='text-single' label='Last Name'>
  203. <required/>
  204. </field>
  205. <field var='email' type='text-single' label='E-mail Address'>
  206. <required/>
  207. </field>
  208. <field var='jid' type='jid-single' label='Jabber JID'>
  209. <required/>
  210. </field>
  211. <field var='background' type='text-multi' label='Background Information'>
  212. </field>
  213. <field var='future' type='text-multi' label='Jabber Plans for the Next Six Months'>
  214. </field>
  215. <field var='reasoning' type='text-multi' label='Reasons for Joining'>
  216. </field>
  217. <field var='activity.mailing-lists' type='text-multi' label='Recent Mailing List Activity'>
  218. </field>
  219. <field var='activity.xeps' type='text-multi' label='XEPs Authored or Co-Authored'>
  220. </field>
  221. </x>
  222. ]]></example>
  223. <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>
  224. <p>As shown in the following example, sections may be nested to produce a more granular partitioning of fields.</p>
  225. <example caption='Sections of fields (nested)'><![CDATA[
  226. <x xmlns='jabber:x:data' type='form'>
  227. ...
  228. <page xmlns='http://jabber.org/protocol/xdata-layout'>
  229. <section label='Personal Information'>
  230. <text>
  231. Note: In accordance with the XSF privacy policy, your personal information will
  232. never be shared outside the organization in any way for any purpose; however,
  233. your name and JID may be published in the XSF membership directory.
  234. </text>
  235. <section label='Name'>
  236. <text>Who are you?</text>
  237. <fieldref var='name.first'/>
  238. <fieldref var='name.last'/>
  239. </section>
  240. <section label='Contact Information'>
  241. <text>How can we contact you?</text>
  242. <fieldref var='email'/>
  243. <fieldref var='jid'/>
  244. </section>
  245. <fieldref var='background'/>
  246. </section>
  247. <section label='Community Activity'>
  248. <text>
  249. We use this page to gather information about any XEPs you&apos;ve worked on,
  250. as well as your mailing list activity.
  251. </text>
  252. <text>You do post to the mailing lists, don't you?</text>
  253. <fieldref var='activity.mailing-lists'/>
  254. <fieldref var='activity.xeps'/>
  255. </section>
  256. <section label='Plans and Reasoning'>
  257. <text>
  258. This is where you describe your future plans and why you think you
  259. deserve to be a member of the XMPP Standards Foundation.
  260. </text>
  261. <fieldref var='future'/>
  262. <fieldref var='reasoning'/>
  263. </section>
  264. </page>
  265. ...
  266. </x>
  267. ]]></example>
  268. <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>
  269. </section2>
  270. <section2 topic="Including Tables" anchor='tables'>
  271. <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>
  272. <p>If a &lt;reportedref/&gt; element is specified when no &lt;reported/&gt; element is included, then the reference MUST be ignored.</p>
  273. </section2>
  274. </section1>
  275. <section1 topic='Business Rules' anchor='bizrules'>
  276. <section2 topic='Discovery' anchor='bizrules-disco'>
  277. <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>
  278. </section2>
  279. <section2 topic='Field Distribution' anchor='bizrules-distribution'>
  280. <p>In order to prevent the processing from becoming too complex, there are some restrictions in how fields are distributed within the layout.</p>
  281. <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>
  282. <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>
  283. <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>
  284. </section2>
  285. <section2 topic='Page Labels and Descriptions' anchor='bizrules-pages'>
  286. <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>
  287. <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>
  288. </section2>
  289. <section2 topic='Section Labels and Descriptions' anchor='bizrules-sections'>
  290. <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>
  291. <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>
  292. </section2>
  293. <section2 topic='Internationalization/Localization' anchor='bizrules-i18n'>
  294. <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>
  295. </section2>
  296. </section1>
  297. <section1 topic='Security Considerations' anchor='security'>
  298. <p>There are no security considerations introduced by this document.</p>
  299. </section1>
  300. <section1 topic='IANA Considerations' anchor='iana'>
  301. <p>This document requires no interaction with &IANA;.</p>
  302. </section1>
  303. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  304. <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
  305. <p>The &REGISTRAR; includes 'http://jabber.org/protocol/xdata-layout' in its registry of protocol namespaces.</p>
  306. </section2>
  307. </section1>
  308. <section1 topic='Formal Definition' anchor='def'>
  309. <section2 topic='&lt;page/&gt; Root Element' anchor='def-page'>
  310. <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>
  311. <p>The 'label' attribute specifies the label for this page. This attribute is OPTIONAL. Its value is any string.</p>
  312. </section2>
  313. <section2 topic='&lt;section/&gt; Element' anchor='def-section'>
  314. <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>
  315. <p>The 'label' attribute specifies the label for this section. This attribute is OPTIONAL. Its value is any string.</p>
  316. </section2>
  317. <section2 topic='&lt;fieldref/&gt; Element' anchor='def-fieldref'>
  318. <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>
  319. <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>
  320. <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>
  321. </section2>
  322. <section2 topic='&lt;reportedref/&gt; Element' anchor='def-reportedref'>
  323. <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>
  324. </section2>
  325. <section2 topic='&lt;text/&gt; Element' anchor='def-text'>
  326. <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>
  327. </section2>
  328. <section2 topic='XML Schema' anchor='schema'>
  329. <code><![CDATA[
  330. <?xml version='1.0' encoding='UTF-8'?>
  331. <xs:schema
  332. xmlns:xs='http://www.w3.org/2001/XMLSchema'
  333. targetNamespace='http://jabber.org/protocol/xdata-layout'
  334. xmlns='http://jabber.org/protocol/xdata-layout'
  335. elementFormDefault='qualified'>
  336. <xs:annotation>
  337. <xs:documentation>
  338. The protocol documented by this schema is defined in
  339. XEP-0141: http://www.xmpp.org/extensions/xep-0141.html
  340. </xs:documentation>
  341. </xs:annotation>
  342. <xs:element name='page'>
  343. <xs:complexType>
  344. <xs:choice minOccurs='0' maxOccurs='unbounded'>
  345. <xs:element ref='text' minOccurs='0' maxOccurs='unbounded'/>
  346. <xs:element ref='section' minOccurs='0' maxOccurs='unbounded'/>
  347. <xs:element ref='fieldref' minOccurs='0' maxOccurs='unbounded'/>
  348. <xs:element ref='reportedref' minOccurs='0' maxOccurs='unbounded'/>
  349. </xs:choice>
  350. <xs:attribute name='label' type='xs:string' use='optional'/>
  351. </xs:complexType>
  352. </xs:element>
  353. <xs:element name='section'>
  354. <xs:complexType>
  355. <xs:choice minOccurs='0' maxOccurs='unbounded'>
  356. <xs:element ref='text' minOccurs='0' maxOccurs='unbounded'/>
  357. <xs:element ref='section' minOccurs='0' maxOccurs='unbounded'/>
  358. <xs:element ref='fieldref' minOccurs='0' maxOccurs='unbounded'/>
  359. <xs:element ref='reportedref' minOccurs='0' maxOccurs='unbounded'/>
  360. </xs:choice>
  361. <xs:attribute name='label' type='xs:string' use='optional'/>
  362. </xs:complexType>
  363. </xs:element>
  364. <xs:element name='fieldref'>
  365. <xs:complexType>
  366. <xs:simpleContent>
  367. <xs:extension base='empty'>
  368. <xs:attribute name='var' type='xs:string' use='required'/>
  369. </xs:extension>
  370. </xs:simpleContent>
  371. </xs:complexType>
  372. </xs:element>
  373. <xs:element name='reportedref' type='empty'/>
  374. <xs:element name='text' type='xs:string'/>
  375. <xs:simpleType name='empty'>
  376. <xs:restriction base='xs:string'>
  377. <xs:enumeration value=''/>
  378. </xs:restriction>
  379. </xs:simpleType>
  380. </xs:schema>
  381. ]]></code>
  382. </section2>
  383. </section1>
  384. </xep>