moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-21 23:28:51 -05:00
Code Issues Releases Wiki Activity

2.9pre1

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1031 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-07-10 21:04:17 +00:00
parent 113df2a86e
commit c75b4bd708
1 changed files with 18 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
xep-0004.xml
View File

@ -27,6 +27,12 @@
&jer; &jer;
&temas; &temas;
&stpeter; &stpeter;
<revision>
<version>2.9pre1</version>
<date>in progress, last updated 2007-07-10</date>
<initials>psa</initials>
<remark><p>Clarified the definition and handling of the list-multi and list-single field types.</p></remark>
</revision>
<revision> <revision>
<version>2.8</version> <version>2.8</version>
<date>2007-05-21</date> <date>2007-05-21</date>
@ -208,7 +214,7 @@
<ul> <ul>
<li><p><strong>&lt;desc/&gt;</strong> -- The XML character data of this element provides a natural-language description of the field, intended for presentation in a user-agent (e.g., as a "tool-tip", help button, or explanatory text provided near the field). The &lt;desc/&gt; element SHOULD NOT contain newlines (the \n and \r characters), since layout is the responsibility of a user agent, and any handling of newlines (e.g., presentation in a user interface) is unspecified herein. (Note: To provide a description of a field, it is RECOMMENDED to use a &lt;desc/&gt; element rather than a separate &lt;field/&gt; element of type "fixed".)</p></li> <li><p><strong>&lt;desc/&gt;</strong> -- The XML character data of this element provides a natural-language description of the field, intended for presentation in a user-agent (e.g., as a "tool-tip", help button, or explanatory text provided near the field). The &lt;desc/&gt; element SHOULD NOT contain newlines (the \n and \r characters), since layout is the responsibility of a user agent, and any handling of newlines (e.g., presentation in a user interface) is unspecified herein. (Note: To provide a description of a field, it is RECOMMENDED to use a &lt;desc/&gt; element rather than a separate &lt;field/&gt; element of type "fixed".)</p></li>
<li><p><strong>&lt;required/&gt;</strong> -- This element, which MUST be empty, flags the field as required in order for the form to be considered valid.</p></li> <li><p><strong>&lt;required/&gt;</strong> -- This element, which MUST be empty, flags the field as required in order for the form to be considered valid.</p></li>
<li><p><strong>&lt;value/&gt;</strong> -- The XML character data of this element defines the default value for the field (according to the form-processing entity), the data provided by a form-submitting entity, or a data result. In data forms of type "form", if the form-processing entity provides a default value via the &lt;value/&gt; element, then the form-submitting entity SHOULD NOT attempt to enforce a different default value (although it MAY do so to respect user preferences or anticipate expected user input). Fields of type list-multi, jid-multi, text-multi, and hidden MAY contain more than one &lt;value/&gt; element; all other field types MUST NOT contain more than one &lt;value/&gt; element.</p></li> <li><p><strong>&lt;value/&gt;</strong> -- The XML character data of this element defines the default value for the field (according to the form-processing entity) in a data form of type "form", the data provided by a form-submitting entity in a data form of type "submit", or a data result in a data form of type "result". In data forms of type "form", if the form-processing entity provides a default value via the &lt;value/&gt; element, then the form-submitting entity SHOULD NOT attempt to enforce a different default value (although it MAY do so to respect user preferences or anticipate expected user input). Fields of type list-multi, jid-multi, text-multi, and hidden MAY contain more than one &lt;value/&gt; element; all other field types MUST NOT contain more than one &lt;value/&gt; element.</p></li>
<li><p><strong>&lt;option/&gt;</strong> -- One of the options in a field of type "list-single" or "list-multi". The XML character of the &lt;value/&gt; child defines the option value, and the 'label' attribute defines a human-readable name for the option. The &lt;option/&gt; element MUST contain one and only one &lt;value/&gt; child. If the field is not of type "list-single" or "list-multi", it MUST NOT contain an &lt;option/&gt; element.</p></li> <li><p><strong>&lt;option/&gt;</strong> -- One of the options in a field of type "list-single" or "list-multi". The XML character of the &lt;value/&gt; child defines the option value, and the 'label' attribute defines a human-readable name for the option. The &lt;option/&gt; element MUST contain one and only one &lt;value/&gt; child. If the field is not of type "list-single" or "list-multi", it MUST NOT contain an &lt;option/&gt; element.</p></li>
</ul> </ul>
<p>If the &lt;field/&gt; element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The &lt;field/&gt; element MAY possess a 'label' attribute that defines a human-readable name for the field. For data forms of type "form", each &lt;field/&gt; element SHOULD possess a 'type' attribute that defines the data "type" of the field data (if no 'type' is specified, the default is "text-single"); fields provided in the context of other forms types MAY possess a 'type' attribute as well.</p> <p>If the &lt;field/&gt; element type is anything other than "fixed" (see below), it MUST possess a 'var' attribute that uniquely identifies the field in the context of the form (if it is "fixed", it MAY possess a 'var' attribute). The &lt;field/&gt; element MAY possess a 'label' attribute that defines a human-readable name for the field. For data forms of type "form", each &lt;field/&gt; element SHOULD possess a 'type' attribute that defines the data "type" of the field data (if no 'type' is specified, the default is "text-single"); fields provided in the context of other forms types MAY possess a 'type' attribute as well.</p>
@ -234,28 +240,28 @@
<td>The field is not shown to the form-submitting entity, but instead is returned with the form.</td> <td>The field is not shown to the form-submitting entity, but instead is returned with the form.</td>
</tr> </tr>
<tr> <tr>
<td>jid-multi *</td> <td>jid-multi</td>
<td>The field enables an entity to gather or provide multiple Jabber IDs.</td> <td>The field enables an entity to gather or provide multiple Jabber IDs. *</td>
</tr> </tr>
<tr> <tr>
<td>jid-single *</td> <td>jid-single</td>
<td>The field enables an entity to gather or provide a single Jabber ID.</td> <td>The field enables an entity to gather or provide a single Jabber ID. *</td>
</tr> </tr>
<tr> <tr>
<td>list-multi</td> <td>list-multi</td>
<td>The field enables an entity to gather or provide one or more options from among many.</td> <td>The field enables an entity to gather or provide one or more options from among many. A form-submitting entity chooses one or more items from among the options presented by the form-processing entity and MUST NOT insert new options. **</td>
</tr> </tr>
<tr> <tr>
<td>list-single</td> <td>list-single</td>
<td>The field enables an entity to gather or provide one option from among many.</td> <td>The field enables an entity to gather or provide one option from among many. A form-submitting entity chooses one item from among the options presented by the form-processing entity and MUST NOT insert new options. **</td>
</tr> </tr>
<tr> <tr>
<td>text-multi **</td> <td>text-multi</td>
<td>The field enables an entity to gather or provide multiple lines of text.</td> <td>The field enables an entity to gather or provide multiple lines of text. ***</td>
</tr> </tr>
<tr> <tr>
<td>text-private</td> <td>text-private</td>
<td>The field enables an entity to gather or provide a single line or word of text, which shall be obscured in an interface (e.g., *****).</td> <td>The field enables an entity to gather or provide a single line or word of text, which shall be obscured in an interface (e.g., with multiple instances of the asterisk character).</td>
</tr> </tr>
<tr> <tr>
<td>text-single</td> <td>text-single</td>
@ -263,7 +269,8 @@
</tr> </tr>
</table> </table>
<p>* Note: Data provided for fields of type "jid-single" or "jid-multi" MUST contain one or more valid Jabber IDs, where validity is determined by the addressing rules defined in <cite>XMPP Core</cite> (see the <link url='#validation'>Data Validation</link> section below).</p> <p>* Note: Data provided for fields of type "jid-single" or "jid-multi" MUST contain one or more valid Jabber IDs, where validity is determined by the addressing rules defined in <cite>XMPP Core</cite> (see the <link url='#validation'>Data Validation</link> section below).</p>
<p>** Note: Data provided for fields of type "text-multi" SHOULD NOT contain any newlines (the \n and \r characters). Instead, the application SHOULD split the data into multiple strings (based on the newlines inserted by the platform), then specify each string as the XML character data of a distinct &lt;value/&gt; element. Similarly, an application that receives multiple &lt;value/&gt; elements for a field of type "text-multi" SHOULD merge the XML character data of the value elements into one text block for presentation to a user, with each string separated by a newline character as appropriate for that platform.</p> <p>** Note: The &lt;option/&gt; elements in list-multi and list-single fields MUST be unique, where uniqueness is determined by the value of the 'label' attribute and the XML character data of the &lt;value/&gt; element (i.e., both must be unique).</p>
<p>*** Note: Data provided for fields of type "text-multi" SHOULD NOT contain any newlines (the \n and \r characters). Instead, the application SHOULD split the data into multiple strings (based on the newlines inserted by the platform), then specify each string as the XML character data of a distinct &lt;value/&gt; element. Similarly, an application that receives multiple &lt;value/&gt; elements for a field of type "text-multi" SHOULD merge the XML character data of the value elements into one text block for presentation to a user, with each string separated by a newline character as appropriate for that platform.</p>
</section2> </section2>
<section2 topic='Multiple Items in Form Results' anchor='protocol-results'> <section2 topic='Multiple Items in Form Results' anchor='protocol-results'>
<p>In some contexts (e.g., the results of a search request), it may be necessary to communicate multiple items. Therefore, a data form of type "result" MAY contain two child elements not described in the basic syntax above: one &lt;reported/&gt; element followed by zero or more &lt;item/&gt; elements. The syntax is as follows:</p> <p>In some contexts (e.g., the results of a search request), it may be necessary to communicate multiple items. Therefore, a data form of type "result" MAY contain two child elements not described in the basic syntax above: one &lt;reported/&gt; element followed by zero or more &lt;item/&gt; elements. The syntax is as follows:</p>