<?xml version="1.0" encoding="UTF-8"?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>rich:colorPicker</keyword>
      <keyword>colorPicker</keyword>
    </keywordset>
  </sectioninfo>
  <table>
    <title>Component identification parameters</title>
    <tgroup cols="2">
      <thead>
        <row>
          <entry>Name</entry>
          <entry>Value</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>component-type</entry>
          <entry>org.richfaces.ColorPicker</entry>
        </row>
        <row>
          <entry>component-class</entry>
          <entry>org.richfaces.component.html.HtmlColorPicker</entry>
        </row>
        <row>
          <entry>component-family</entry>
          <entry>org.richfaces.ColorPicker</entry>
        </row>
        <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.ColorPickerRenderer</entry>
        </row>
        <row>
          <entry>tag-class</entry>
          <entry>org.richfaces.taglib.ColorPickerTag</entry>
        </row>
      </tbody>
    </tgroup>
  </table>
  <section>
    <title>Creating the Component with a Page Tag</title>
    <para>Here is a simple example of how the component can be used on a page:</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <!-- itemLabels has to have realy value-->
    <programlisting role="XML">
<![CDATA[...
<rich:colorPicker value="#{bean.color}" />
...]]>
		</programlisting>
  </section>
  <section>
    <title>Creating the Component Dynamically Using Java</title>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="JAVA">
<![CDATA[import org.richfaces.component.html.colorPicker;
...	
HtmlColorPicker myColorPicker = new ColorPicker();
...]]>
		</programlisting>
  </section>
  <section>
    <title>Details of Usage</title>
    <para> The <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> component allows you easily select a color or define it in hex, RGB, or HSB input
      fields. There are two squares in the widget that help you to compare the currently selected
      color and the already selected color. </para>
    <para> The <property>
        <emphasis>&quot;value&quot;</emphasis>
      </property> attribute stores the selected color. </para>
    <para> The value of the <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> component could be saved in hex or RGB color models. You can explicitly define a
      color model in the <property>
        <emphasis>&quot;colorMode&quot;</emphasis>
      </property> attribute. </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML">
<![CDATA[...
<rich:colorPicker value="#{bean.color}" colorMode="rgb" />
...]]>
		</programlisting>
    <para>This is the result:</para>
    <figure>
      <title> Usage of the <property>
          <emphasis>&quot;colorMode&quot;</emphasis>
        </property> attribute. </title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/colorPicker_rgb.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <para> The <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> component has two representation states: flat and inline. With the help of the <property>
        <emphasis>&quot;flat&quot;</emphasis>
      </property> attribute you can define whether the component is rendered flat. </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML">
<![CDATA[...
<rich:colorPicker value="#{bean.color}" flat="true" />
...]]>
		</programlisting>

    <para>The component specific event handler <property><emphasis>&quot;onbeforeshow&quot;</emphasis></property> captures the event which occurs before
      the <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> widget is opened. The <property><emphasis>&quot;onbeforeshow&quot;</emphasis></property> attribute could be used in order to cancel this
      event. See the example below:</para>
    <programlisting role="XML">
<![CDATA[...
<rich:colorPicker value="#{bean.color}" onbeforeshow="if (!confirm('Are you sure you want to change a color?')){return false;}" />
...]]>
     </programlisting>
    
    <para> The <property>
        <emphasis>&quot;showEvent&quot;</emphasis>
      </property> attribute defines the event that shows <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> widget. The default value is &quot;onclick&quot;. </para>
    <para> The <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> component allows to use the <emphasis>
        <property>&quot;icon&quot;</property>
      </emphasis> facet. </para>
    <para> You can also customize <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> rainbow slider ( <inlinemediaobject>
        <imageobject>
          <imagedata fileref="images/colorPicker_arrows.png"/>
        </imageobject>
      </inlinemediaobject> ) with the help of the <property>
        <emphasis>&quot;arrows&quot;</emphasis>
      </property> facet. </para>
    <programlisting role="XML">
<![CDATA[...
<rich:colorPicker value="#{bean.color}">
	<f:facet name="icon">
		<h:graphicImage value="/pages/colorPicker_ico.png" />
	</f:facet>
	<f:facet name="arrows">
		<f:verbatim>		
			<div style="width: 33px; height: 5px; border: 1px solid #bed6f8; background:none;" />
		</f:verbatim>
	</f:facet>
</rich:colorPicker>
...]]>
		</programlisting>
    <para>This is the result:</para>
    <figure>
      <title> Usage of the <emphasis>
          <property>&quot;icon&quot;</property>
        </emphasis>, and <emphasis>
          <property>&quot;arrows&quot;</property>
        </emphasis> facets </title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/colorPicker_facets.png"/>
        </imageobject>
      </mediaobject>
    </figure>
  </section>

  <section>
    <title>Look-and-Feel Customization</title>
    <para>For skinnability implementation, the components use a <emphasis>
        <property>style class redefinition method.</property>
      </emphasis> Default style classes are mapped on <emphasis>
        <property>skin parameters.</property>
      </emphasis></para>
    <para>There are two ways to redefine the appearance of all <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> components at once: <itemizedlist>
        <listitem>
          <para>Redefine the corresponding skin parameters</para>
        </listitem>
        <listitem>
          <para> Add style classes used by a <emphasis role="bold">
              <property>&lt;rich:colorPicker&gt;</property>
            </emphasis> component to your style sheets</para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
  <section>
    <title>Skin Parameters Redefinition</title>
    <table>
      <title>Skin parameters redefinition for the input field that contains selected color</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
          <row>
            <entry>generalSizeFont</entry>
            <entry>font-size</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <table>
      <title>Skin parameters redefinition for the wrapper &lt;div&gt; element of a
        widget</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
          <row>
            <entry>generalBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <table>
      <title>Skin parameters redefinition for the icon, color palette, current color, and new
        color</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <table>
      <title>Skin parameters redefinition for the hex, RGB, and HSB input fileds</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>generalSizeFont</entry>
            <entry>font-size</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
          <row>
            <entry>generalTextColor</entry>
            <entry>color</entry>
          </row>
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
          <row>
            <entry>controlBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <table>
      <title>Skin parameters redefinition for the &quot;Apply&quot; and
        &quot;Cancel&quot; button</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>
            <entry>CSS properties</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>buttonFontSize</entry>
            <entry>font-size</entry>
          </row>
          <row>
            <entry>buttonFamilyFont</entry>
            <entry>font-family</entry>
          </row>
          <row>
            <entry>headerTextColor</entry>
            <entry>color</entry>
          </row>
          <row>
            <entry>headerBackgroundColor</entry>
            <entry>border-color</entry>
          </row>
          <row>
            <entry>panelBorderColor</entry>
            <entry>border-color</entry>
          </row>
          <row>
            <entry>generalSizeFont</entry>
            <entry>font-size</entry>
          </row>
          <row>
            <entry>generalFamilyFont</entry>
            <entry>font-family</entry>
          </row>
          <row>
            <entry>headerBackgroundColor</entry>
            <entry>background-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </section>
  <!-- Definition of Custom Style Classes-->
  <section>
    <title>Definition of Custom Style Classes</title>
    <para>On the screenshot there are classes names that define styles for component
      elements.</para>

    <figure>
      <title>Classes names</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/colorPicker_cn.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <table id="colorPicker_cn_inline">
      <title> Classes names for the representation of the input field and icon containing selected
        color </title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Selector name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>.rich-colorPicker-span input</entry>
            <entry>Defines styles for the input field that contains selected color</entry>
          </row>
          <row>
            <entry>.rich-colorPicker-icon</entry>
            <entry>Defines styles for the icon</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <table id="colorPicker_cn_widget">
      <title>Classes names for the widget</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>.rich-colorPicker-ext</entry>
            <entry>Defines styles for the wrapper &lt;div&gt; element of a widget</entry>
          </row>
          <row>
            <entry>.rich-colorPicker-color</entry>
            <entry>Defines styles for the color palette</entry>
          </row>
          <row>
            <entry>.rich-colorPicker-current-color</entry>
            <entry>Defines styles for the currently selected color</entry>
          </row>
          <row>
            <entry>.rich-colorPicker-new-color</entry>
            <entry>Defines styles for the already selected color</entry>
          </row>
          <row>
            <entry>.rich-colorPicker-colors-input</entry>
            <entry>Defines styles for the hex, RGB, and HSB input fileds</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <table id="colorPicker_cn_buttons">
      <title>Classes names for the buttons representation</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Class name</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>.rich-colorPicker-submit</entry>
            <entry>Defines styles for the &quot;Apply&quot; button</entry>
          </row>
          <row>
            <entry>.rich-colorPicker-cancel</entry>
            <entry>Defines styles for the &quot;Cancel&quot; button</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>In order to redefine styles for all <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> components on a page using CSS, it&apos;s enough to create classes with the
      same names (possible classes could be found in the tables <link
        linkend="colorPicker_cn_inline"> above</link>) and define necessary properties in them. </para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-colorPicker-ext{
    background-color: #ecf4fe;
}						
...]]></programlisting>

    <para>This is the result:</para>
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/colorPicker_pc.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    <para>In the shown example the background color for the widget is changed.</para>

    <!--para>It&apos;s aslo possible to change styles of a particular 
      <emphasis role="bold"> <property>&lt;rich:colorPicker&gt;</property></emphasis> component. 
	  In this case you should create own style classes and use them in corresponding <emphasis role="bold"><property>&lt;rich:colorPicker&gt;</property></emphasis> <property>styleClass</property> attributes. 
	  An example is placed below:</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.myClass {
    background-color:#bed6f8;
}
...]]></programlisting>  
    <para>The <emphasis><property>&quot;viewClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:colorPicker&gt; </property></emphasis> is defined as it&apos;s shown in the example below:</para>
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[<rich:colorPicker value="click to edit" viewClass="myClass"/>
]]></programlisting>    
    
    <para>This is a result:</para>
    
    <figure>
      <title>Modificaton of a look and feel with own classes and <emphasis><property>styleClass</property></emphasis> attributes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/inplaceSelect_oc.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above, the font style and background color in <property>view</property> state is changed.</para-->


  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/colorPicker.jsf?c=colorPicker"
        >On the component LiveDemo page</ulink> you can see the example of <emphasis role="bold">
        <property>&lt;rich:colorPicker&gt;</property>
      </emphasis> component usage and sources for the given example. </para>
  </section>
</section>
