0.0.2

inbox/color-parameter.xml

@@ -6,7 +6,7 @@
 <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
 <xep>
     <header>
-        <title>Data Forms - Color Field Type</title>
+        <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>
         <legal>
             <copyright>This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF).</copyright>
@@ -39,7 +39,15 @@
             <jid>peter.waher@jabber.org</jid>
             <uri>http://se.linkedin.com/pub/peter-waher/1a/71b/a29/</uri>
         </author>
-        <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>
@@ -66,8 +74,8 @@
 			as an encoded color string.
 		</p>
         <p>
-            This extension also relies on &xep0122; as a fall-back mechanism so clients not recognizing the color data type can handle it as a
+            This extension also relies on &xep0122; as a fallback mechanism so clients not recognizing the color data types can handle them as
-            string with a regular expression validating user input.
+			strings with a regular expressions validating user input.
         </p>
     </section1>
     <section1 topic='Publishing a Color Field in a Data Form'>
@@ -84,8 +92,7 @@
             <xdv:regex>^[0-9a-fA-F]{6}$</xdv:regex>
         </xdv:validate>
         <value>9400D3</value>
-    </field>
+    </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, 
@@ -106,6 +113,42 @@
             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='http://jabber.org/protocol/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>
@@ -116,8 +159,8 @@
 				<![CDATA[
     <datatype-prefix>
         <prefix>xdc</prefix>
-        <desc>Defines the Color data type.</desc>
+        <desc>defines the Color data type</desc>
-        <doc>xep-0000-ColorParameter.html</doc>
+        <doc>color-parameter.html</doc>
     </datatype-prefix>]]>
 			</code>
 		</section2>
@@ -130,7 +173,25 @@
 				<![CDATA[
     <datatype>
         <name>xdc:Color</name>
-        <desc>A color value represented as an RGB value.</desc>
+        <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>
@@ -154,7 +215,16 @@
         </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>