Ajax4jsf CDK. Getting Started. Creating outputBlock Component

This short tutorial shows how to create a simple component using Ajax4jsf CDK.

As an example, we use a outputBlock component that surrounds any textual context with div tag. Developer will be able to define the content with 'value' attribute. Style attributes and events-oriented onxxxx attributes should work as well additional to the standard set of JSF attributes

Step 1. Configuration. Creating Library

Configure the Maven environment and create your library like it is shown at:  Getting Started with the JBoss Ajax4jsf CDK

Step 2. Creating Component

Go to 'mylib' directory and perform the following command:

mvn cdk:create -Dname=outputBlock

You should see the "BUILD SUCCESSFUL" message in the console. The following files are created:

Step 3. Defining Component Meta-Data

Open src/main/config/component/outputBlock.xml for edit.

You can define all attributes you need there like it is shown at the end of the file. Let's define the "value" likewise. We can define other attributes as well. However, CDK comes with number of XML entities that defines most common set of attributes. Additional to the &ui_component_attributes that is in the template already, we will add:

• &html_events;

• &html_style_attributes;

• &ui_output_attributes;

I hope, the name of each entity says for itself. The following attached document shows what are the attribute will be included.

This is like the meta-data file might look like after the editing:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE components PUBLIC "-//AJAX4JSF//CDK Generator config/EN"
  "https://ajax4jsf.dev.java.net/nonav/dtds/component-config.dtd" >
<components>
 <component>
  <name>org.mycompany.OutputBlock</name>
  <family>org.mycompany.OutputBlock</family>
  <classname>org.mycompany.component.html.HtmlOutputBlock</classname>
  <superclass>org.mycompany.component.UIOutputBlock</superclass>
  <description>
   <![CDATA[Puts the DIV around the content defined with 'value' attribute  \]\]\>
  </description>
  <renderer generate="true" override="true">
   <name>org.mycompany.OutputBlockRenderer</name>
   <template>org/mycompany/htmlOutputBlock.jspx</template>
  </renderer>
  <tag>
   <name>outputBlock</name>
   <classname>org.mycompany.taglib.OutputBlockTag</classname>
   <superclass>
    org.ajax4jsf.webapp.taglib.HtmlComponentTagBase
   </superclass>
  </tag>
  &ui_component_attributes;
  &html_events;
  &html_style_attributes;
  <property>
   <name>value</name>
   <classname>java.lang.String</classname>
   <description>output text</description>
   <defaultvalue>""</defaultvalue>
  </property>
 </component>
</components>

Save the file.

Step 4. Defining the component layout

Open src/main/templates/org/mycompany/htmlOutputBlock.jspx for editing.

This file contains the design-time definition of the component rendering. By the end of the code-generation process, it will be converted to the Component Rendered class. The class name for renderer is defined with class="org.mycompany.renderkit.html.OutputBlockRenderer" defined at the top of the file.

Ajax4jsf provides utility base class org.ajax4jsf.framework.renderer.AjaxComponentRendererBase. However, we are not going to use extra features of the Ajax4jsf framework in our outputBlock component. So, just remove baseclass attribute for now.

The template already shows how to use div. So, we need just correct it a little bit. The final version will be the following:

<?xml version="1.0" encoding="UTF-8"?>
<f:root 
 xmlns:f="http://ajax4jsf.org/cdk/template" 
 xmlns:x=" http://ajax4jsf.org/cdk/x"
 class="org.mycompany.renderkit.html.OutputBlockRenderer"
 component="org.mycompany.component.UIOutputBlock" 
 >
 <f:clientid var="clientId"></f:clientid>
 <div id="#{clientId}" x:passThruWithExclusions="value,id">
  #{component.attributes['value']}
 </div>
</f:root>

We put the value of 'value' attribute inside the div tag. Special x:passThruWithExclusions attbibute helps as to avoid declaring the all possible attribute explicitly. As soon as we mentioned id and value attributes already, that are marked as exclusions for  x:passThruWithExclusions

Save the file

Step 5. Generating Library

We are done with component. The final step is generating the library jar file. Go to the root directory of the library ('mylib' directory like it mentioned on Step 2) and perform the following command:

mvn clean install

'clean' is optional in you build library at the first time. However, it is helpful if you already did it and want to rebuild.

You should see the "BUILD SUCCESSFUL" on the console. If so, you did not make any mistake and the final jar is created. You can see the target directory created beside the 'src' directory. It contains mylib-1.0.-SNAPSHOT.jar. You can put this jar to your own project WEB-INF/lib directory and the new component will be available for use.

The jar file contains:

All files except UIOutputBlock are code-generated.

Step 6. Deployment and Using

Put the jar file to your existing project into WEB-INF/lib folder. After that you can put in the beginning of the page:

In case of JSP:

<%@ taglib uri="http://mycompany.org/mylib" prefix="mylib"%>

In case of XHTML:

xmlns:mylib="http://mycompany.org/mylib"

Then put anywhere on the page:

<mylib:outputBlock value="The content of the block element" ></mylib:outputBlock>

It will output the text inside the div.

Put:

    <mylib:outputBlock style="color:red;border:1px solid blue" 
     onclick="alert('you clicked at me')"
    value="The content of the block element" ></mylib:outputBlock>

This will show the red text inside the blue border. The alert will be shown it you click on it.

Note: In the current version of CDK, a couple of utility classes are referenced from the generated classes. So, ajax4jsf.jar is required to be in the classpath in run-time. We are going to avoid this dependency if no other feature of Ajax4jsf framework used in the developed library.

Conclusion

This document presents the common approach, but does not show all features Ajax4jsf CDK has. As examples of components created by CDK you can look at RichFaces repository. All of them are created using this technique.