mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-04 16:35:07 -05:00
239 lines
10 KiB
XML
239 lines
10 KiB
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 - Color Field Types</title>
|
|
<abstract>This specification defines how to publish fields in data forms that take color values. Color values are best edited using a color picker dialog, rather than manual input.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>0331</number>
|
|
<status>Experimental</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XEP-0001</spec>
|
|
<spec>XEP-0004</spec>
|
|
<spec>XEP-0030</spec>
|
|
<spec>XEP-0122</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>color-parameter</shortname>
|
|
<author>
|
|
<firstname>Peter</firstname>
|
|
<surname>Waher</surname>
|
|
<email>peter.waher@clayster.com</email>
|
|
<jid>peter.waher@jabber.org</jid>
|
|
<uri>http://www.linkedin.com/in/peterwaher</uri>
|
|
</author>
|
|
<revision>
|
|
<version>0.2</version>
|
|
<date>2014-03-10</date>
|
|
<initials>pw</initials>
|
|
<remark>
|
|
<p>Namespace changed to urn:xmpp:xdata:color.</p>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.1</version>
|
|
<date>2013-06-26</date>
|
|
<initials>psa</initials>
|
|
<remark>
|
|
<p>Initial published version approved by the XMPP Council.</p>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.2</version>
|
|
<date>2013-06-11</date>
|
|
<initials>pw</initials>
|
|
<remark>
|
|
<p>Added the ColorAlpha data type.</p>
|
|
</remark>
|
|
</revision>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2013-05-27</date>
|
|
<initials>pw</initials>
|
|
<remark>
|
|
<p>First draft.</p>
|
|
</remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>
|
|
Some applications require configuration of color values. Examples can be what colors to use for different situations in control applications.
|
|
There's up to this point no good way to publish color values in a &xep0004;.
|
|
</p>
|
|
<p>
|
|
Some applications provide parameters of type list-single enabling the user to choose a color from a list of colors. This only allows the user
|
|
to select from a small amount of colors, and doesn't provide any visual feedback of the actual color chosen.
|
|
</p>
|
|
<p>
|
|
Editing color values as color components or encoded strings is both impractical and unintuitive.
|
|
</p>
|
|
<p>
|
|
This document proposes a method to publish color field parameters in a way that allows clients to show a color picker dialog for the parameter
|
|
instead of forcing the user to enter an encoded color value. For clients not supporting this extensions, the color value will still be editable
|
|
as an encoded color string.
|
|
</p>
|
|
<p>
|
|
This extension also relies on &xep0122; as a fallback mechanism so clients not recognizing the color data types can handle them as
|
|
strings with a regular expressions validating user input.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Publishing a Color Field in a Data Form'>
|
|
<p>
|
|
The following example shows how to publish a Color Field parameter in a Data Form:
|
|
</p>
|
|
<example caption='Publishing a Color Field in a Data Form'>
|
|
<![CDATA[
|
|
<field var='color' type='text-single' label='Color:'>
|
|
<desc>Choose a color.</desc>
|
|
<xdv:validate xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
|
xmlns:xdc='urn:xmpp:xdata:color'
|
|
datatype='xdc:Color'>
|
|
<xdv:regex>^[0-9a-fA-F]{6}$</xdv:regex>
|
|
</xdv:validate>
|
|
<value>9400D3</value>
|
|
</field>]]>
|
|
</example>
|
|
<p>
|
|
The color value is represented by a string consisting of six case-insensitive hexadecimal digits. The first two represent the red component,
|
|
the next two the green component and the last two the blue component.
|
|
</p>
|
|
<p>
|
|
If the client does not support XEP-0122 (Data Form Validation), it will interpret the field as a normal <strong>text-single</strong> field. It is
|
|
up to the server to validate user input. But the user can still enter a color.
|
|
</p>
|
|
<p>
|
|
A client that supports XEP-0122 (Data Form Validation), but not this extension, will not understand the data type <strong>xdc:Color</strong>.
|
|
It will thus default to a normal string (xs:string). However, the client still supports the <strong>regex</strong> validation rule,
|
|
making sure the client only allows user input that forms valid color values.
|
|
</p>
|
|
<p>
|
|
A client supporting this specification will recognize the <strong>xdc:Color</strong> data type, and choose to show a color picker dialog instead
|
|
of a string input field. In this case, the regular expression in the validation statement will not be used, as the string is not edited
|
|
directly by the user. However, it is still available implicitly in the xdc:Color data type.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Publishing a Color Field with Alpha channel in a Data Form'>
|
|
<p>
|
|
The following example shows how to publish a Color Field parameter including an Alpha channel in a Data Form:
|
|
</p>
|
|
<example caption='Publishing a Color Field in a Data Form'>
|
|
<![CDATA[
|
|
<field var='color' type='text-single' label='Color:'>
|
|
<desc>Choose a color.</desc>
|
|
<xdv:validate xmlns:xdv='http://jabber.org/protocol/xdata-validate'
|
|
xmlns:xdc='urn:xmpp:xdata:color'
|
|
datatype='xdc:ColorAlpha'>
|
|
<xdv:regex>^[0-9a-fA-F]{8}$</xdv:regex>
|
|
</xdv:validate>
|
|
<value>9400D3C0</value>
|
|
</field>]]>
|
|
</example>
|
|
<p>
|
|
The color value is represented by a string consisting of eight case-insensitive hexadecimal digits. The first two represent the red component,
|
|
the next two the green component and the last two the blue component. The last two represents the alpha channel, where 00 means completely
|
|
transparent and FF means completely opaque.
|
|
</p>
|
|
<p>
|
|
As with the xdc:Color type defined above, if the client does not support XEP-0122 (Data Form Validation), it will interpret the field as a
|
|
normal <strong>text-single</strong> field. It is up to the server to validate user input. But the user can still enter a color.
|
|
</p>
|
|
<p>
|
|
A client that supports XEP-0122 (Data Form Validation), but not this extension, will not understand the data type <strong>xdc:ColorAlpha</strong>.
|
|
It will thus default to a normal string (xs:string). However, the client still supports the <strong>regex</strong> validation rule,
|
|
making sure the client only allows user input that forms valid color values.
|
|
</p>
|
|
<p>
|
|
A client supporting this specification will recognize the <strong>xdc:ColorAlpha</strong> data type, and choose to show a color picker dialog instead
|
|
of a string input field. In this case, the regular expression in the validation statement will not be used, as the string is not edited
|
|
directly by the user. However, it is still available implicitly in the xdc:ColorAlpha data type.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
|
|
<section2 topic='Color datatype prefix: xdc'>
|
|
<p>
|
|
As defined in <link url='http://xmpp.org/extensions/xep-0122.html#registar-reg-prefixes'>XEP-0122 §7.2.1</link>, following is the submission
|
|
to the XMPP Registrar of a new datatype prefix for use in data forms:
|
|
</p>
|
|
<code caption='Color datatype prefix: xdc'>
|
|
<![CDATA[
|
|
<datatype-prefix>
|
|
<prefix>xdc</prefix>
|
|
<desc>defines the Color data type</desc>
|
|
<doc>http://xmpp.org/extensions/xep-0331.html</doc>
|
|
</datatype-prefix>]]>
|
|
</code>
|
|
</section2>
|
|
<section2 topic='Color datatype'>
|
|
<p>
|
|
As defined in <link url='http://xmpp.org/extensions/xep-0122.html#registar-reg-datatypes'>XEP-0122 §7.2.2</link>, following is the submission
|
|
to the XMPP Registrar of a new datatype representing color values for use in data forms:
|
|
</p>
|
|
<code caption='Color datatype'>
|
|
<![CDATA[
|
|
<datatype>
|
|
<name>xdc:Color</name>
|
|
<desc>a color value represented as an RGB value, expressed using 6 hexadecimal digits, with each pair of
|
|
the hexadecimal digits representing the values of the Red, Green and Blue channel, respectively</desc>
|
|
<methods>basic regex</methods>
|
|
<min>N/A</min>
|
|
<max>N/A</max>
|
|
</datatype>]]>
|
|
</code>
|
|
</section2>
|
|
<section2 topic='ColorAlpha datatype'>
|
|
<p>
|
|
As defined in <link url='http://xmpp.org/extensions/xep-0122.html#registar-reg-datatypes'>XEP-0122 §7.2.2</link>, following is the submission
|
|
to the XMPP Registrar of a new datatype representing color values with alpha channel for use in data forms:
|
|
</p>
|
|
<code caption='ColorAlpha datatype'>
|
|
<![CDATA[
|
|
<datatype>
|
|
<name>xdc:ColorAlpha</name>
|
|
<desc>a color value represented as an RGBA value, expressed using 8 hexadecimal digits, with each pair of
|
|
the hexadecimal digits representing the values of the Red, Green, Blue and Alpha channel, respectively</desc>
|
|
<methods>basic regex</methods>
|
|
<min>N/A</min>
|
|
<max>N/A</max>
|
|
</datatype>]]>
|
|
</code>
|
|
</section2>
|
|
</section1>
|
|
<section1 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='urn:xmpp:xdata:color'
|
|
xmlns='urn:xmpp:xdata:color'
|
|
elementFormDefault='qualified'>
|
|
|
|
<xs:simpleType name='Color'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:pattern value='^[0-9a-fA-F]{6}$'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
<xs:simpleType name='ColorAlpha'>
|
|
<xs:restriction base='xs:string'>
|
|
<xs:pattern value='^[0-9a-fA-F]{8}$'/>
|
|
</xs:restriction>
|
|
</xs:simpleType>
|
|
|
|
</xs:schema>]]>
|
|
</code>
|
|
</section1>
|
|
<section1 topic='Acknowledgements' anchor='ack'>
|
|
<p>Thanks to Karin Forsell for all valuable feedback.</p>
|
|
</section1>
|
|
</xep>
|