Author: artdaw Date: 2008-08-13 10:42:34 -0400 (Wed, 13 Aug 2008) New Revision: 10073 Added: trunk/docs/cdkguide/en/src/main/resources/examples/inputDate.xml Removed: trunk/docs/cdkguide/en/src/main/docbook/modules/ccreate.xml trunk/docs/cdkguide/en/src/main/docbook/modules/compdev.xml Modified: trunk/docs/cdkguide/en/src/main/docbook/includes/register.xml trunk/docs/cdkguide/en/src/main/docbook/includes/taghandler.xml trunk/docs/cdkguide/en/src/main/docbook/includes/ui.xml trunk/docs/cdkguide/en/src/main/docbook/includes/ui_conf.xml trunk/docs/cdkguide/en/src/main/docbook/master.xml trunk/docs/cdkguide/en/src/main/docbook/modules/overview.xml Log: https://jira.jboss.org/jira/browse/RF-3692 - 'inputDate component development' chapter done. Modified: trunk/docs/cdkguide/en/src/main/docbook/includes/register.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/includes/register.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/includes/register.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -99,24 +99,51 @@ <para> With the help of the <emphasis role="bold"><property>&lt;cacheable&gt;</property></emphasis> element you could manage whether the resource is cached or not. - If the value of this element is &quot;true&quot;, the resource is cached on the server and also on the client sides. + If the value of this element is &quot;true&quot;, the resource is cached on the server and also on the client sides: </para> + <programlisting role="XML"><![CDATA[... +<resource class="org.mycompany.renderkit.html.images.inputDate"> + <name>org.mycompany.renderkit.html.images.inputDate</name> + <cacheable>true</cacheable> +</resource> +...]]></programlisting> + <para> + You could start a session for the some resource + using <emphasis role="bold"><property>&lt;session-aware&gt;</property></emphasis> element set to &quot;true&quot;: + </para> + <programlisting role="XML"><![CDATA[... +<resource> + <name>org/mycompany/renderkit/html/scripts/inputDate.js</name> + <path>org/mycompany/renderkit/html/scripts/inputDate.js</path> + <session-aware>true</session-aware> +</resource> +...]]></programlisting> + <para> + Sometimes the definition of content type of the resource is needed, so it is possible to add + the <emphasis role="bold"><property>&lt;content-type&gt;</property></emphasis> element with the proper MIME type. + </para> + <para> + You could also define a custom <property>renderer</property> for the resource: + </para> + <programlisting role="XML"><![CDATA[... +<resource> + <name>org/mycompany/renderkit/html/scripts/inputDate.js</name> + <path>org/mycompany/renderkit/html/scripts/inputDate.js</path> + <renderer class="org.ajax4jsf.resource.ScriptRenderer"/> +</resource> +...]]></programlisting> + <para> + It is possible to specify a MIME type for the resource <property>renderer</property> + using the <emphasis role="bold"><property>&lt;content-type&gt;</property></emphasis> element. + </para> + - <!--programlisting role="XML"><![CDATA[... -<resource> - <name></name> - <path></path> - <cacheable></cacheable> - <session-aware></session-aware> +<!-- +TBD <property> <name></name> </property> - <content-type></content-type> - <renderer> - <content-type></content-type> - </renderer> -</resource> -...]]></programlisting--> +--> </section> </section> \ No newline at end of file Modified: trunk/docs/cdkguide/en/src/main/docbook/includes/taghandler.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/includes/taghandler.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/includes/taghandler.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -1,16 +1,47 @@ <?xml version="1.0" encoding="UTF-8"?> <section id="taghandler" xreflabel="taghandler"> -<?dbhtml filename="taghandler.html"?> -<sectioninfo> -<keywordset> -<keyword>taghandler</keyword> -<keyword>UI</keyword> -<keyword>CDK</keyword> -<keyword>Guide</keyword> -</keywordset> -</sectioninfo> -<title>Creating tag classes and descriptor for JSP and Facelets</title> -<para> -Creating a JSP tag handler and TLD -</para> + <?dbhtml filename="taghandler.html"?> + <sectioninfo> + <keywordset> + <keyword>taghandler</keyword> + <keyword>UI</keyword> + <keyword>CDK</keyword> + <keyword>Guide</keyword> + </keywordset> + </sectioninfo> + <title>Creating tag class and descriptors for JSP and Facelets</title> + <para> + The last step is to create a JSP tag handler and descriptors. + </para> + <para> + JSF components are not inherently tied to JSP. You will use a custom tag (a.k.a action) on the JSP page to + indicate which JSF <code>UIComponent</code> is needed for the application. + The custom tag has a corresponding tag handler class, which is responsible for creating the <code>UIComponent</code> + and transferring each declarative JSP tag attribute to the <code>UIComponent</code> instance. + So you need a custom <property>tag class</property> that returns + the component type (<code>org.mycompany.InputDate</code>) and the renderer (<code>org.mycompany.InputDateRenderer</code>). + </para> + <para> + After the <property>tag class</property> creation you need to register it in the descriptors: + in the <property>TLD (Tag Library Descriptor)</property> file for JSP pages and + in the <property>inputDate.taglib.xml</property> file for Facelets. + </para> + <para> + But you know that <property>inputDate.xml</property> configuration file generates + the JSP tag handler and descriptors instead of you! + Just proceed to the <property>inputDate</property> folder and launch the following command: + </para> + <programlisting role="XML"><![CDATA[mvn clean install]]></programlisting> + <para> + After the generation process you will find in the <property>inputDate/target/classes/META-INF</property> folder + <property>inputDate.tld</property>, <property>inputDate.taglib.xml</property>, <property>resources-config.xml</property>, + and <property>faces-config.xml</property> files. + </para> + <para> + The <code>InputDateTag</code> class could be found in the <property>inputDate/target/classes/org/mycompany/taglib</property>. + </para> + <para> + Well done! The <emphasis role="bold"><property>&lt;inputDate&gt;</property></emphasis> component is created. + The <property>inputDate-1.0-SNAPSHOT.jar</property> for the component usage could be found in the <property>inputDate/target</property> folder. + </para> </section> \ No newline at end of file Modified: trunk/docs/cdkguide/en/src/main/docbook/includes/ui.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/includes/ui.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/includes/ui.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -9,7 +9,7 @@ <keyword>Guide</keyword> </keywordset> </sectioninfo> - <title>Extending a UIInput.</title> + <title>Extending a UIInput class</title> <para> The base class for all JSF components is <code>UIComponent</code>. When you develop <emphasis role="bold"><property>&lt;inputDate&gt;</property></emphasis> component Modified: trunk/docs/cdkguide/en/src/main/docbook/includes/ui_conf.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/includes/ui_conf.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/includes/ui_conf.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -9,18 +9,213 @@ <keyword>Guide</keyword> </keywordset> </sectioninfo> - <title>Configuring component.</title> + <title>Configuring component</title> <para> Well, it is almost the final step in the component creation process - component configuration. </para> <para> - There is <property>inputDate.xml</property> file in the <property>src/main/config/component</property> directory that is used - by <property>CDK</property> factory for generating not only the complete <code>UIInputDate</code> class, - but also a TLD file, a tag handler and a descriptor for JSP and Facelets. + Note that you should register all the classes and attributes of the <emphasis role="bold"><property>&lt;inputDate&gt;</property></emphasis> component. + If you will create the component dynamically on a page + you should register the component in the faces context configuration file - <property>faces-config.xml</property>. + If you use a custom tag on a JSP page you need a TLD file for registration. + If you plan to use Facelets you need <property>inputDate.taglib.xml</property> descriptor. </para> <para> - Please, open the <ulink url="examples/inputDate_skeleton.xml">inputDate.xml</ulink> in your favorite text editor - and take a look at the skeleton. + The <property>CDK</property> factory uses the <property>inputDate.xml</property> file + for generating not only the complete <code>UIInputDate</code> class, + but also a JSP Tag Handler, faces-config.xml and descriptors for JSP and Facelets. </para> + <para> + Please, proceed to the <property>src/main/config/component</property> directory, + open the <ulink url="examples/inputDate_skeleton.xml">inputDate.xml</ulink> in your favorite text editor + and take a look at the skeleton: there is a root element <emphasis role="bold"><property>&lt;components&gt;</property></emphasis> + with the one nested <emphasis role="bold"><property>&lt;component&gt;</property></emphasis> element. + </para> + <tip> + <title>Tip:</title> + <para> + It is possible to create a number of components in the one project. + For example <emphasis role="bold"><property>&lt;rich:dataTable&gt;</property></emphasis> is a complex component that + includes a <emphasis role="bold"><property>&lt;rich:column&gt;</property></emphasis> + and/or <emphasis role="bold"><property>&lt;rich:columns&gt;</property></emphasis> components. + </para> + </tip> + <para> + Application instance stores resources defined in the descriptors at application start-up, so it is neccessary to register + following classes: + </para> + <itemizedlist> + <listitem> + <para> + the <code>UIInputDate</code> class + </para> + <programlisting role="XML"><![CDATA[... +<name>org.mycompany.InputDate</name> +<family>org.mycompany.InputDate</family> +<classname>org.mycompany.component.html.HtmlInputDate</classname> +<superclass>org.mycompany.component.UIInputDate</superclass> +...]]></programlisting> + </listitem> + <listitem> + <para> + the <code>InputDateRenderer</code> class with the <code>htmlInputDate.jspx</code> template + </para> + <programlisting role="XML"><![CDATA[... +<renderer generate="true" override="true"> + <name>org.mycompany.InputDateRenderer</name> + <template>org/mycompany/htmlInputDate.jspx</template> +</renderer> +...]]></programlisting> + </listitem> + <listitem> + <para> + the <code>InputDateTag</code> class (the JSP Tag Handler) + </para> + <programlisting role="XML"><![CDATA[... +<tag> + <name>inputDate</name> + <classname>org.mycompany.taglib.InputDateTag</classname> + <superclass> + org.ajax4jsf.webapp.taglib.HtmlComponentTagBase + </superclass> +</tag> +...]]></programlisting> + </listitem> + </itemizedlist> + <para> + Note that you have not closed the <emphasis role="bold"><property>&lt;component&gt;</property></emphasis> element + because you are still going to add more metadata for your new component. + Lets to add attributes to the <property>inputDate.xml</property> configuration file as shown in the example below. + </para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[... +<property> + <name>value</name> + <classname>java.lang.String</classname> + <description> + The value of the component + </description> +</property> +<property> + <name>title</name> + <classname>java.lang.String</classname> + <description> + Defines a title of the component + </description> + <defaultvalue>&quot;inputDate&quot;</defaultvalue> +</property> +<property> + <name>styleClass</name> + <classname>java.lang.String</classname> + <description> + Corresponds to the HTML class attribute + </description> +</property> +<property> + <name>inputStyle</name> + <classname>java.lang.String</classname> + <description> + Style attribute for input field + </description> +</property> +<property> + <name>inputClass</name> + <classname>java.lang.String</classname> + <description> + Style Class attribute for the input field + </description> +</property> +<property> + <name>iconClass</name> + <classname>java.lang.String</classname> + <description> + Style Class attribute for the icon element + </description> +</property> +<property> + <name>iconStyle</name> + <classname>java.lang.String</classname> + <description> + Style attribute for the icon element + </description> +</property> +<property> + <name>captionClass</name> + <classname>java.lang.String</classname> + <description> + Style Class attribute for the Caption facet + </description> +</property> +...]]></programlisting> + <para> + As you can see in the example above every attribute is defined with the help of the + <emphasis role="bold"><property>&lt;property&gt;</property></emphasis> element with the following nested elements: + </para> + <itemizedlist> + <listitem> + <para> + the <emphasis role="bold"><property>&lt;name&gt;</property></emphasis> element that defines the name of the attribute + </para> + </listitem> + <listitem> + <para> + the <emphasis role="bold"><property>&lt;classname&gt;</property></emphasis> element that defines the class of the attribute&apos;s value + </para> + </listitem> + <listitem> + <para> + the <emphasis role="bold"><property>&lt;description&gt;</property></emphasis> element that defines the description of the attribute. + This description appears in the TLD file. + </para> + </listitem> + <listitem> + <para> + the <emphasis role="bold"><property>&lt;defaultvalue&gt;</property></emphasis> element that defines the default value for the attribute + </para> + </listitem> + </itemizedlist> + <para> + The last thing worth mentioning is the <property>common attributes</property> that are included through the named entities: + </para> + <programlisting role="XML"><![CDATA[... +&ui_component_attributes; +...]]></programlisting> + <para> + If you want to add <code>UIInput</code> components and HTML events common attributes for the + <emphasis role="bold"><property>&lt;inputDate&gt;</property></emphasis> component you should add the following entities: + </para> + + <programlisting role="XML"><![CDATA[... +&ui_component_attributes; +&html_events; +&ui_input_attributes; +...]]></programlisting> + <para> + More information about the <property>common attributes</property> you could find in the + <link linkend="attr_entity">Including common attributes</link> section. + </para> + <section id="attr_entity"> + <title>Including common attributes</title> + <para> + One of the useful features of the <property>CDK</property> is the possibility to include common attributes to the component. + In order to facilitate development process, the <property>CDK</property> provides a set of entities + that contain custom attributes sets for components (events, action attributes, etc.). + This common attributes could be included with the predefined entities + (for example <property>&amp;ui_component_attributes;</property>, + <property>&amp;html_events;</property>, <property>&amp;ui_input_attributes;</property>, etc.). + </para> + <para> + You could find all the entities <ulink url="http://anonsvn.jboss.org/repos/richfaces/trunk/cdk/generator/sr...;. + </para> + + <!-- + TBD + <para> + There is a table with main entities and descriptions below: + </para> + --> + </section> </section> Modified: trunk/docs/cdkguide/en/src/main/docbook/master.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/master.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/master.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -6,7 +6,6 @@ <!ENTITY roadmap SYSTEM "modules/roadmap.xml"> <!ENTITY namingconv SYSTEM "modules/namingconv.xml"> <!ENTITY setup SYSTEM "modules/setup.xml"> -<!ENTITY compdev SYSTEM "modules/compdev.xml"> <!ENTITY overview SYSTEM "modules/overview.xml"> <!ENTITY ide SYSTEM "modules/ide.xml"> <!ENTITY ref SYSTEM "modules/ref.xml"> @@ -45,10 +44,12 @@ </bookinfo> - <toc/> &intro; &roadmap; &setup; <!-- - &ccreate; - &compdev; ---> + <toc/> + + &intro; + &roadmap; + &setup; + <chapter id="compdev" xreflabel="compdev"> <?dbhtml filename="compdev.html"?> <chapterinfo> @@ -152,8 +153,8 @@ &ui_conf; &taghandler; </chapter> + &overview; &test; - &overview; <chapter id="button" xreflabel="button"> <?dbhtml filename="button.html"?> <chapterinfo> Deleted: trunk/docs/cdkguide/en/src/main/docbook/modules/ccreate.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/modules/ccreate.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/modules/ccreate.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -1,32 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="ccreate" xreflabel="ccreate"> - <?dbhtml filename="ccreate.html"?> - <chapterinfo> - <keywordset> - <keyword>create</keyword> - <keyword>component</keyword> - <keyword>CDK</keyword> - <keyword>Guide</keyword> - </keywordset> - </chapterinfo> - <title>Creating and building component</title> - <para> - Simple component (panel maybe) TBD - </para> - <section id="skeleton" xreflabel="skeleton"> - <?dbhtml filename="skeleton.html"?> - <title>Building the component skeleton</title> - <para> - TBD Skeleton - </para> - </section> - <section id="structure" xreflabel="structure"> - <?dbhtml filename="structure.html"?> - <title>Component project structure</title> - <para> - TBD structure - </para> - </section> -</chapter> - - Deleted: trunk/docs/cdkguide/en/src/main/docbook/modules/compdev.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/modules/compdev.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/modules/compdev.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -1,135 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="compdev" xreflabel="compdev"> - <?dbhtml filename="pccreate.html"?> - <chapterinfo> - <keywordset> - <keyword>development</keyword> - <keyword>component</keyword> - <keyword>CDK</keyword> - <keyword>Guide</keyword> - </keywordset> - </chapterinfo> - <title>Component Development</title> - <para> - Some info - </para> - <section id="rules"> - <title>Limitation and rules</title> - <para> - Rules - </para> - </section> - -<section id="pcreate" xreflabel="pcreate"> - <?dbhtml filename="pcreate.html"?> - <sectioninfo> - <keywordset> - <keyword>project</keyword> - <keyword>component</keyword> - <keyword>CDK</keyword> - <keyword>Guide</keyword> - </keywordset> - </sectioninfo> - <title>Creating project for component</title> - <para> - Web Resources - </para> - -</section> - - -<section id="ccreate" xreflabel="ccreate"> - <?dbhtml filename="ccreate.html"?> - <sectioninfo> - <keywordset> - <keyword>create</keyword> - <keyword>component</keyword> - <keyword>CDK</keyword> - <keyword>Guide</keyword> - </keywordset> - </sectioninfo> - <title>Creating and building component</title> - <para> - Simple component (panel maybe) TBD - </para> - <section id="skeleton" xreflabel="skeleton"> - <?dbhtml filename="skeleton.html"?> - <title>Building the component skeleton</title> - <para> - TBD Skeleton - </para> - </section> - <section id="structure" xreflabel="structure"> - <?dbhtml filename="structure.html"?> - <title>Component project structure</title> - <para> - TBD structure - </para> - </section> -</section> - - - <section id="settings"> - <title>Specifying component attributes</title> - <para> - settings - </para> - </section> - - <section id="renderer"> - <title>Creating component renderer</title> - <para> - Renderer explanation. - </para> - <section id="template"> - <title>Templating</title> - <para> - How to write your renderer with the help of template. - </para> - <section id="tempex"> - <title>Template example</title> - <para> - Example - </para> - </section> - <section id="tempmech"> - <title>Templating mechanism</title> - <para> - Mechanism - </para> - </section> - <section id="temptags"> - <title>Template tags overview</title> - <para> - tags - </para> - </section> - </section> - </section> - <section id="skin"> - <title>Skinnability</title> - <para> - Plug-n-Skin creation - </para> - </section> - <section id="resource"> - <title>Resources Handling</title> - <para> - Resources Handling - </para> - <section id="regres"> - <title>Component resources registration</title> - <para> - How to register component resources - </para> - </section> - <section id="resconf"> - <title>resources-config.xml file format</title> - <para> - resources-config.xml file format - </para> - </section> - </section> -</chapter> - - Modified: trunk/docs/cdkguide/en/src/main/docbook/modules/overview.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/docbook/modules/overview.xml 2008-08-13 13:53:07 UTC (rev 10072) +++ trunk/docs/cdkguide/en/src/main/docbook/modules/overview.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -13,12 +13,15 @@ <para> overview </para> - <section id="devsample"> - <title>Developer sample creation</title> - <para> -Sample creation - </para> - </section> + <!-- + TBD + <section id="devsample"> + <title>Developer sample creation</title> + <para> + Sample creation + </para> + </section> + --> </chapter> Added: trunk/docs/cdkguide/en/src/main/resources/examples/inputDate.xml =================================================================== --- trunk/docs/cdkguide/en/src/main/resources/examples/inputDate.xml (rev 0) +++ trunk/docs/cdkguide/en/src/main/resources/examples/inputDate.xml 2008-08-13 14:42:34 UTC (rev 10073) @@ -0,0 +1,89 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE components PUBLIC "-//AJAX4JSF//CDK Generator config/EN" "http://labs.jboss.com/jbossrichfaces/component-config.dtd"> + +<components> + <component> + <name>org.mycompany.InputDate</name> + <family>org.mycompany.InputDate</family> + <classname>org.mycompany.component.html.HtmlInputDate</classname> + <superclass>org.mycompany.component.UIInputDate</superclass> + <description> + <![CDATA[ + ]]> + </description> + <renderer generate="true" override="true"> + <name>org.mycompany.InputDateRenderer</name> + <template>org/mycompany/htmlInputDate.jspx</template> + </renderer> + <tag> + <name>inputDate</name> + <classname>org.mycompany.taglib.InputDateTag</classname> + <superclass> + org.ajax4jsf.webapp.taglib.HtmlComponentTagBase + </superclass> + </tag> + + &ui_component_attributes; + &html_events; + &ui_input_attributes; + + <property> + <name>value</name> + <classname>java.lang.String</classname> + <description> + The value of the component + </description> + </property> + + <property> + <name>title</name> + <classname>java.lang.String</classname> + <description> + Defines a title of the component + </description> + <defaultvalue>&quot;inputDate&quot;</defaultvalue> + </property> + <property> + <name>styleClass</name> + <classname>java.lang.String</classname> + <description> + Corresponds to the HTML class attribute + </description> + </property> + <property> + <name>inputStyle</name> + <classname>java.lang.String</classname> + <description> + Style attribute for input field + </description> + </property> + <property> + <name>inputClass</name> + <classname>java.lang.String</classname> + <description> + Style Class attribute for the input field + </description> + </property> + <property> + <name>iconClass</name> + <classname>java.lang.String</classname> + <description> + Style Class attribute for the icon element + </description> + </property> + <property> + <name>iconStyle</name> + <classname>java.lang.String</classname> + <description> + Style attribute for the icon element + </description> + </property> + <property> + <name>captionClass</name> + <classname>java.lang.String</classname> + <description> + Style Class attribute for the Caption facet + </description> + </property> + </component> +</components> \ No newline at end of file Property changes on: trunk/docs/cdkguide/en/src/main/resources/examples/inputDate.xml ___________________________________________________________________ Name: svn:executable + *