<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.docbook.org/xsd/4.3/docbook.xsd"
[	
<!ENTITY intro SYSTEM "modules/intro.xml">
<!ENTITY roadmap SYSTEM "modules/roadmap.xml">
<!ENTITY namingconv SYSTEM "modules/namingconv.xml">
<!ENTITY setup SYSTEM "modules/setup.xml">
<!ENTITY overview SYSTEM "modules/overview.xml">
<!ENTITY devsample SYSTEM "modules/devsample.xml">
<!ENTITY ide SYSTEM "modules/ide.xml">
<!ENTITY ref SYSTEM "modules/ref.xml">
<!ENTITY test SYSTEM "modules/test.xml">


<!ENTITY pcreate SYSTEM "includes/pcreate.xml">
<!ENTITY ccreate SYSTEM "includes/ccreate.xml">
<!ENTITY ui SYSTEM "includes/ui.xml">
<!ENTITY ui_conf SYSTEM "includes/ui_conf.xml">
<!ENTITY protoui SYSTEM "includes/protoui.xml">
<!ENTITY template SYSTEM "includes/template.xml">
<!ENTITY skin SYSTEM "includes/skin.xml">
<!ENTITY register SYSTEM "includes/register.xml">
<!ENTITY taghandler SYSTEM "includes/taghandler.xml">
<!ENTITY rendererbase SYSTEM "includes/rendererbase.xml">
<!--Check the links page -->
<!ENTITY links SYSTEM "modules/links.xml">

<!ENTITY forEach SYSTEM "tags/forEach.xml">
<!ENTITY cif SYSTEM "tags/cif.xml">
<!ENTITY cset SYSTEM "tags/cset.xml">
<!ENTITY fattribute SYSTEM "tags/fattribute.xml">
<!ENTITY finsert SYSTEM "tags/finsert.xml">
<!ENTITY fclientId SYSTEM "tags/fclientId.xml">
]>

<book>
    <bookinfo>
        <title>RichFaces CDK Developer Guide</title>
	<subtitle>This documentation is work in progress, thus some mistakes or incompleteness is possible</subtitle>
	<author>
		<firstname>Gleb</firstname>
		<surname>Galkin</surname>
		<email>ggalkin@exadel.com</email>
	</author>   
        <copyright>
            <year>2008</year>
            <holder>Red Hat</holder>
        </copyright>

<abstract>
   <title/>
       <!--para>
           <ulink url="http://www.jboss.org/file-access/default/members/jbossrichfaces/freezone/docs/devguide/en/pdf/richfaces-usersguide.pdf">PDF version</ulink>
       </para-->
</abstract>


    </bookinfo>
    <toc/> 
    
    &intro; 
    &roadmap; 
    &setup; 
    
    <chapter id="compdev" xreflabel="compdev">
        <?dbhtml filename="compdev.html"?>
        <chapterinfo>
            <keywordset>
                <keyword>inputDate</keyword>
                <keyword>component</keyword>
                <keyword>CDK</keyword>
                <keyword>Guide</keyword>
            </keywordset>
        </chapterinfo>
        <title>inputDate component development</title>
        <para> We a going to create the <emphasis role="bold">
                <property>&lt;inputDate&gt;</property>
            </emphasis> component that can take a value, process that value, and then push it back
            to the underlying model as a strongly typed <property>Date</property> object. </para>
        <para> The <emphasis role="bold">
                <property>&lt;inputDate&gt;</property>
            </emphasis> component allows to attach a converter in order to set the desired date
            format such as <property>mm/dd/yyyy</property>. So the component could convert and
            validate the date entered by user. </para> 
	    <?forseChanks?>
		&pcreate; 
		&ccreate; 
		&protoui;
		
            <section id="crenderer" xreflabel="crenderer">
            <?dbhtml filename="crenderer.html"?>
            <sectioninfo>
                <keywordset>
                    <keyword>renderer</keyword>
                    <keyword>UI</keyword>
                    <keyword>CDK</keyword>
                    <keyword>Guide</keyword>
                </keywordset>
            </sectioninfo>
            <title>Creating a Renderer</title>
	    	<para>
			Component functionality typically centers around two actions: 
			<property>decoding</property> and <property>encoding</property> data. 
			Decoding is the process of converting incoming request parameters to the values of the component. 
			Encoding is the process of converting the current values of the component into the corresponding markup. In the
			following figure you can see decoding and encoding occur in the JSF lifecycle:
		</para>
	    <figure>
			<title>Decoding and encoding in the JSF lifecycle</title>
		        <mediaobject> 
				    <imageobject>
						<imagedata fileref="images/lifecycle.png"/>
		            </imageobject>
				</mediaobject>
	    </figure>
	    <para>
		Thus, JSF components consist of two parts: the <property>component class</property> and the <property>renderer</property>.
		The <property>component class</property> is responsible for the state and behavior of a UI component and will be discussed later in the <property>&quot;Configuring component&quot;</property> section.
	    </para>
            <para>The <property>Renderer</property> is responsible for the JSF component representation. It generates the
                appropriate client-side markup, such as HTML, WML, XUL, etc. Renderer is also
                responsible for the converting information coming from the client to the proper type
                for the component (for example, a string value from the request is converted to a
                strongly type <code>Date</code> object). 
		</para>
		<para>
			It is necessary to create following renderer classes for the <emphasis role="bold"><property>&lt;inputDate&gt;</property></emphasis> component:
		</para>
		<itemizedlist>
			<listitem>
				<para>
					 <code>InputDateRenderer</code> class where you should override <code>encode()</code> methods for encoding the markup and resources
				</para>
			</listitem>
			<listitem>
				<para>
					 <code>InputDateRendererBase</code> class where you should override <code>decode()</code> method.
					 You could also define associated converter in this class.
				</para>
			</listitem>
		</itemizedlist>
            <para> You could actually implement the renderer-specific component subclass that
                exposes client-side attributes such as <emphasis>
                    <property>&quot;style&quot;</property>
                </emphasis>, <emphasis>
                    <property>&quot;class&quot;</property>
                </emphasis>, etc. It is common practice to implement the client-specific component
                subclass to make some aspects of application development easier, but in our case we
                do not need to do it. The <emphasis role="bold">
                    <property>&lt;inputDate&gt;</property>
                </emphasis> is a simple <code>UIInput</code> component, therefore
                    <code>InputDateRenderer</code> class generates all the markup itself. </para>
        <para> It is a time to start creating the <code>InputDateRenderer</code> class. 
		The smartest way to create the <code>InputDateRenderer</code> class is a <property>Templating</property> mechanism,
		one of the most convenient features of the <property>Component Development Kit (CDK)</property>. 
	</para>
		    
		    
		&template; 
		&rendererbase; 
		&skin; 
	</section> 
		&register; 
		&ui;
		&ui_conf;
		&taghandler; 
</chapter> 
	&overview; 
	&devsample;
	&test; 
<chapter id="button"  xreflabel="button">
        <?dbhtml filename="button.html"?>
        <chapterinfo>
            <keywordset>
                <keyword>button</keyword>
                <keyword>component</keyword>
                <keyword>CDK</keyword>
                <keyword>Guide</keyword>
            </keywordset>
        </chapterinfo>
        <title>Button component development</title>
        <para> Work in progress... </para>

    </chapter> &ide; &namingconv; &ref; 
    
    <chapter id="temptags" xreflabel="temptags">
    <?dbhtml filename="temptags.html"?>
    <chapterinfo>
        <keywordset>
            <keyword>template</keyword>
            <keyword>CDK</keyword>
	    <keyword>Guide</keyword>
        </keywordset>
    </chapterinfo>
<title>Template tags overview</title>

&forEach;
&cif;
&cset;
&fattribute;
&finsert;
&fclientId;
</chapter>
    </book>
