<?xml version="1.0" encoding="UTF-8"?>
<section id="template" xreflabel="template">
    <?dbhtml filename="template.html"?>
    <sectioninfo>
        <keywordset>
            <keyword>templating</keyword>
            <keyword>UI</keyword>
            <keyword>CDK</keyword>
            <keyword>Guide</keyword>
        </keywordset>
    </sectioninfo>
    <title>Templating</title>
    <para> The <property>Component Development Kit (CDK)</property> allows to use <property>templates</property> for generation <property>Renderer</property> class. </para>
    <para> Templates are JSP-like markup pages with special tags that are converted into
            <property>Renderer</property> by a build script. </para>
    <para> It&apos;s possible to use evaluated expressions in components templates with the help of <property>scriptlets</property>.
        It&apos;s also possible to create the <property>base class</property> for a template to
        implement additional functions in it, so as the functions could be called from the template.
        Hence, in the generated <property>Renderer</property> class there are corresponding function
        calls on the place of these elements. </para>
    <para> Let&apos;s create the template for <property>HTML 4.0</property> markup. At first you should proceed to the
            <property>inputDate/src/main/templates/org/mycompany</property> directory where
            <property>htmlInputDate.jspx</property> template file is stored. This file contains a
            <property>Template Skeleton</property> like this one: </para>
    <programlisting role="XML"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<f:root 
	xmlns:f="http://ajax4jsf.org/cdk/template" 
	xmlns:c=" http://java.sun.com/jsf/core" 
	xmlns:ui=" http://ajax4jsf.org/cdk/ui"
	xmlns:u=" http://ajax4jsf.org/cdk/u"
	xmlns:x=" http://ajax4jsf.org/cdk/x"
	class="org.mycompany.renderkit.html.InputDateRenderer"
	baseclass="org.ajax4jsf.renderkit.AjaxComponentRendererBase"
	component="org.mycompany.component.UIInputDate" 
	>
	<f:clientid var="clientId"/>
	<div id="#{clientId}"
		x:passThruWithExclusions="value,name,type,id"
		>
	</div>
</f:root>
    ]]></programlisting>
    <para> According to the created <property>UI prototype</property> you need to extend
            <property>Template Skeleton</property> with proper elements:
</para>
<itemizedlist>
	<listitem>
		<para>
			<emphasis role="bold"><property>&lt;div&gt;</property></emphasis>-wrapper element with 
			<emphasis><property>&quot;title&quot;</property></emphasis>,
<emphasis><property>&quot;id&quot;</property></emphasis> attributes and with 
the<emphasis><property>&quot;caption&quot;</property></emphasis> facet
		</para>
		   <programlisting role="XML"><![CDATA[...
<div id="#{clientId}" title="#{value}" x:passThruWithExclusions="value,name,type,id">
	...
</div>
...]]></programlisting>
	</listitem>
	<listitem>
		<para>
			<emphasis role="bold"><property>&lt;input&gt;</property></emphasis> element with 
<emphasis><property>&quot;id&quot;</property></emphasis>,			
<emphasis><property>&quot;value&quot;</property></emphasis>,
<emphasis><property>&quot;name&quot;</property></emphasis>,
<emphasis><property>&quot;type&quot;</property></emphasis>,
<emphasis><property>&quot;class&quot;</property></emphasis>,
<emphasis><property>&quot;style&quot;</property></emphasis> attributes.
It is possible to use the <emphasis><property>&quot;icon&quot;</property></emphasis> facet in order to redefine a default icon of the component.
		</para>
	<programlisting role="XML"><![CDATA[...
<input  id="#{clientId}" 
		name="#{clientId}"
		type="text" 
		value="#{this:getValueAsString(context, component)}" 
		class="my-inputDate-input #{component.attributes['inputClass']}" 
		style="#{component.attributes['inputStyle']}"/>
...]]></programlisting>
	</listitem>
	<listitem>
		<para>
			<emphasis role="bold"><property>&lt;img&gt;</property></emphasis> element with 
<emphasis><property>&quot;src&quot;</property></emphasis>,
<emphasis><property>&quot;class&quot;</property></emphasis>,
<emphasis><property>&quot;style&quot;</property></emphasis> attributes which defines a default icon of the component.
	In order to add an image to the Template you should register it with the help of
	<emphasis role="bold"><property>&lt;f:resource&gt;</property></emphasis> template tag 
	and bind to a variable specified by the <emphasis><property>&quot;var&quot;</property></emphasis> attribute:
		</para>
			<programlisting role="XML"><![CDATA[...
<f:resource name="/org/mycompany/renderkit/html/images/inputDate.png" var="icon" />
	...
<img src="#{icon}" class="my-inputDate-icon #{component.attributes['iconClass']}" style="#{component.attributes['iconStyle']}"/>
...]]></programlisting>
	</listitem>
</itemizedlist>
<para>
	The <emphasis role="bold"><property>&lt;inputDate&gt;</property></emphasis> component uses styles that should 
	be defined in the template with the help of <emphasis role="bold"><property>&lt;h:styles&gt;</property></emphasis> tag: 
</para>
	<programlisting role="XML"><![CDATA[...
<h:styles>/org/mycompany/renderkit/html/css/inputDate.xcss</h:styles>
...]]></programlisting>
<para>
	How to register all resources is explained in the
	<link linkend="register">&quot;Component resources registration&quot;</link> chapter.
</para>
<important>
	<title>Important:</title>
	<para>
		Don&apos;t forget to add namespace <code>xmlns:h=&quot; http://ajax4jsf.org/cdk/h&quot;</code> to the 
		<emphasis role="bold"><property>&lt;f:root&gt;</property></emphasis> element:
	</para>
    <programlisting role="XML"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<f:root 
	...
	xmlns:h=" http://ajax4jsf.org/cdk/h"
	...
	>
	...
</f:root>]]></programlisting>	
</important>
<para>
Here is a full example of the template for
        the <emphasis role="bold">
            <property>&lt;inputDate&gt;</property>
        </emphasis> component: 
    <ulink url="examples/htmlInputDate.txt">htmlInputDate.jspx</ulink>. 
    </para>
    <note>
	<title>Note:</title>
	<para>
		As it is seen in the <property>Template Skeleton</property> the Renderer Baseclass is <code>org.ajax4jsf.renderkit.AjaxComponentRendererBase</code>.
		You need to define Renderer Base class special for the <emphasis role="bold"><property>&lt;inputDate&gt;</property></emphasis> component.
		In the next section <link linkend="rendererbase">&quot;Creating a Renderer Base class&quot;</link> 
		we will create Renderer Base class <code>org.mycompany.renderkit.InputDateRendererBase</code>.
	</para>
    </note>
    <para>
	All the Template tags you could find in the  <link linkend="temptags">&quot;Template tags overview&quot;</link> chapter.
    </para>
    </section>
