Tuesday, August 7, 2012

RichFaces 4.3.0.M1 Release Announcement

RichFaces

The first milestone release of RichFaces 4.3 (4.3.0.M1) is now available. This is a significant release, with primary focus on improving the RichFaces Component Development Kit (CDK) – the tool we use to author our JSF components. A second goal of the release was to improve our MyFaces support, which we accomplished by fixing a number of issues, and identifying some further issues to be addressed in a subsequent 4.3 milestone release.

To try out this release: You can download the distribution directly, or for maven users, increment the RichFaces version in your pom.xml to 4.3.0.20120802-M1. For more information on setting up a RichFaces 4 application, refer to our getting started guide.

CDK Improvements

RichFaces Component Development Kit (CDK) is a heavy-lifter in the RichFaces Framework. The CDK is the tool we use to author our JSF components. Improvements we make to the CDK improve our ability to deliver components, and will reduce our turnaround on delivering new features for developing web applications.

RichFaces developer Paul Dijou has written up a great summary of the recent CDK improvements. For further details on what has changed, you can refer to the list of individual issues addressed. While the bulk of CDK changes have landed in M1, we will undoubtedly introduce further improvements throughout the rest of the 4.3 release cycle as we push the boundaries on what’s possible with the CDK in our RichFaces Bootstrap sandbox project.

“Real” Tests

Testing of our components and framework has always been a primary concern of the RichFaces project. All our releases to date have been tested not only with unit tests, but also with a large battery of significant number of functional tests. However, functional tests treat the JSF servlet as a black box – we know what we put it and we can test what comes out. On the other hand, unit tests mock the environment where our implementation runs, hiding any issues that would occur only in a real environment. If you think about it, these tests operate in a blind-folded manner: what’s happening as the container executes our application logic?

To this end, the RichFaces project has co-ordinated with the Arquillian project in the development of a new extension: “Arquillian Warp”. With Warp, we can write tests that assert state simultaneously on both the client and the server. For JSF, this means our tests can assert state at arbitrary points throughout the JSF lifecycle. As you can imagine, this opens up a whole new category of tests we can write, as we can not only assert that our application logic has the desired effect, but also that it executes as we expect.

Warp reuses outstanding Arquillian integration with various containers, which allows us to test the integration of RichFaces with many application servers and servlet containers. Furthermore, Warp leverages the Arquillian Drone extension for running Selenium-based tests. Arquillian’s flexibility together with Drone’s ability to drive both real and mocked browsers (ie. HtmlUnit), allows us to run tests using minimal resources in continuous integration, and we can run those same tests in “real” environments to verify integration with many real containers.

Our integration tests makes heavy use of ShrinkWrap to create micro-deployments allowing us to separate the project into small testable pieces. ShrinkWrap Resolvers provides support for resolving various modules from our multi-module project, while ShrinkWrap Descriptors allows us to programatically describe configuration files (like faces-config.xml and web.xml), property files, and Facelet files – which enable us to write tests once and run them in many different configurations.

So far we’ve used this new capability within the framework to harden our RichFaces Push and Resource Mapping implementation, and we will continue to develop new cross-container integration tests of our components and frameworks to complement our already impressive test suite.

Issue highlights

This milestone release addresses a number of bugs as well as new features. For a full list of issues addressed, be sure to check out the Release Notes. However, there are a couple of issues I would like to call out in this blog.

The rich:jQuery function in EL to call a jQuery object from a JSF id as in:
#{rich:jquery('your-id']}

This is a convenience method introduced as a short-hand for the current:
$('##{rich:clientId('your-id')}')

The RichFaces a4j:push feature now has a max inactive timeout, that specifies the maximum amount of time a session is allowed to be inactive. This is an experimental feature, put in place as a workaround while we resolve the underlying issue RF-12219. Try it out, let us know what you think!

Component Upgrades

The RichFaces project is very much an open source project, and leverages other open source projects wherever possible. In this milestone release, we updated the version dependency of some of our upstream projects. These include:

  • RF-12176 – Upgrade to Atmosphere 1.0.0.beta4
  • RF-12334 – Upgrade Mojarra to 2.1.7
  • RF-12335 – Upgrade MyFaces to 2.1.8
  • RF-12336 – Upgrade jQuery to 1.7.2
  • RF-12371 – Upgrade Maven project dependency to 3.0.4

MyFaces Issues

With this release, we’ve also turned our attention to a number of MyFaces issues that we hadn’t addressed with our recent releases. In order to co-ordinate with the JBoss EAP 6 release, we focused predominantly on Mojarra compatibility. However RichFaces is a container agnostic project, and we’re making a concerted effort to improve our MyFaces compatibility with our 4.3 release.

This effort is being facilitated both by the Arquillian Warp project mentioned above, as well as by the TomEE project. TomEE gives us an excellent pre-bundled/pre-configured Tomcat and MyFaces environment against which we can both develop and debug our components – without requiring us to assemble the required jars, and “roll our own appserver”.

As with our CDK improvements, fixing MyFaces issues will continue throughout the 4.3 release. M1 is just a first step in this direction.

What’s Next?

In a recent RichFaces community meeting, we set some goals for the M2 release of RichFaces 4.3. These goals include:

  • Restructure the build (according to the requirements being collected in our wiki)
  • Proceed with further MyFaces fixes
  • Iteration/repeating issues
  • Critical/Popular bugs

Also, be sure to follow the RichFaces Bootstrap project:

In the RichFaces Bootstrap Sandbox project, we are developing our next-generation component set based on top of the Twitter bootstrap project. RichFaces developer Paul Dijou has an excellent write-up on the latest bootstrap updates. Also, check out JSF+LESS blog by RichFaces developer Lukas Fryc, showcasing the real-time CSS/LESS development going on in our Bootstrap project – JSF component styling at it’s best!

Friday, May 4, 2012

RichFaces Bootstrap

I’m happy to share the news that the RichFaces community has started an effort to wrap Twitter Bootstrap with the RichFaces CDK. If you haven’t yet heard, Twitter’s Bootstrap project is a set of HTML/CSS/js “widgets” that you can use for building a website/web application with an emphasis on a fluid layouts that adapt well to mobile devices. The RichFaces community effort centres around providing a set of first-class JSF components built using these Bootstrap widgets via the RichFaces CDK.

This is still early days for the effort, consider what we have so far as a Proof of Concept. The work is being done in the RichFaces Sandbox, where new ideas/components are explored and proven before migrating in the the framework core. We’ll explore how to bring these Bootstrap components into the framework proper when the effort is complete. The reason for this blog post is to let people know what the community is doing and invite people to get involved!

Take a look at the RichFaces bootstrap demo to see what the components look like. Keep in mind we used the RichFaces bootstrap JSF components to build the demo itself, (a dogfood demo if you will!). So far we’ve stubbed out a number of bootstrap components with the CDK, and we have a bootstrap “enabled” commandButton component (build on top of the robust a4j:commandButton).

Some example bootstrap components that I particularly like are:

b:buttonDropdown

The buttonDropdown can be used to provide alternate actions for a button on your page:

b:gridContainer

The bootstrap grid components (gridContainer/gridRow/gridColumn) provide a powerful means to layout your page. Being proper JSF components, they are also valid JSF execute/render targets.

I’ll blog more about the individual components as they get fleshed out. There’s a ton of blog material here!

RichFaces Bootstrap Roadmap

Our roadmap for these bootstrap components moving forward involves:

  1. RFSBOX-7 Finish wrapping the remaining bootstrap components
  2. RFSBOX-8 Flesh out the attributes of the already wrapped components
  3. RFSBOX-9 Couple the widget events into the RichFaces/JSF event subsytem (eg. for enabling JSF behaviours)
  4. Migrate/wrap (or re-implement if required) the existing RF 4 components

The task is big, and we could use your commits! So if you are interested in either RichFaces, Bootstrap, or both – be sure to drop by #richfaces on IRC (freenode.net) to discuss how you can get involved and influence how these components will shape up!

Concurrent to the work we do in our sandbox, we are still very much focused on improving the current set of RichFaces 4 components. We have another 4.2 micro release coming out soon, and are planning the Milestone releases for the 4.3 release train.

Lastly, I’d like to close with a big shoutout to Paul Dijou, a Richfaces community member who has been instrumental in getting this effort off the ground! Thanks Paul, and keep those pull request coming!


Tuesday, November 29, 2011

RichFaces 4 CDK | jQeury UI Tabs

Following on with another entry in my CDK series, this time we will look at at creating a pair of components to wrap the jQuery UI tabs plugin with the RichFaces CDK. It’ll take two components to accomplish this; one component to define the tab container, and another to define the tabs themselves. Let’s dive right in with a look at the Abstract component definitions.

As always, if you are interested in following along in your IDE, you can get the code below on github.

The Component Classes

AbstractTabs.java
package ca.bleathem.richfaces.jquery.component;
    import org.richfaces.cdk.annotations.*;
    
    import javax.faces.component.UIComponent;
    import java.util.ArrayList;
    import java.util.Collection;
    import java.util.HashSet;
    import java.util.List;
    import java.util.Set;
    
    @JsfComponent(
            type = "ca.bleathem.richfaces.jquery.Tabs",
            family = "ca.bleathem.Tabs",
            renderer = @JsfRenderer(type = "ca.bleathem.jquery.TabsRenderer"),
            tag = @Tag(name="tabs"))
    abstract public class AbstractTabs extends javax.faces.component.UIPanel {
    }
    

Here we have the component class for tor the tabs tag – this will be the container for the tab components that follow. This is strikingly similar to the earlier AbstractHello component we saw in our first CDK example. The component class is serving as a placeholder to define the component properties (type, family, tag) , and the renderer associations. Look back through the previous blogs in this series if you don’t recognize these properties.

AbstractTab.java
package ca.bleathem.richfaces.jquery.component;
    
    import org.richfaces.cdk.annotations.*;
    
    @JsfComponent(
            type = "ca.bleathem.richfaces.jquery.Tab",
            family = "ca.bleathem.Tab",
            renderer = @JsfRenderer(type = "ca.bleathem.jquery.TabRenderer"),
            tag = @Tag(name="tab"))
    abstract public class AbstractTab extends javax.faces.component.UIPanel {
        @Attribute
        public abstract String getTitle();
    }
    

The component class for the tab tag is similar to the one for the tabs tag, adding a definition for a title attribute, and with slightly different component properties. Let’s move on from these mundane component definitions and look at the Renderers, where things get more interesting.

The Renderers

Looking first at the simpler tab renderer:

tab.template.xhtml
<?xml version="1.0" encoding="UTF-8"?>
    
    <cdk:root xmlns="http://jboss.org/schema/richfaces/cdk/xhtml-el"
            xmlns:cdk="http://jboss.org/schema/richfaces/cdk/core"
            xmlns:c="http://jboss.org/schema/richfaces/cdk/jstl/core"
            xmlns:cc="http://jboss.org/schema/richfaces/cdk/jsf/composite">
    
        <cc:interface>
            <cdk:class>ca.bleathem.richfaces.jquery.renderkit.TabRenderer</cdk:class>
            <cdk:superclass>org.richfaces.renderkit.html.DivPanelRenderer</cdk:superclass>
            <cdk:renderer-type>ca.bleathem.jquery.TabRenderer</cdk:renderer-type>
        </cc:interface>
    
        <cc:implementation>
            <div id="#{clientId}" class="rf_jq_tab">
                <cdk:body />
            </div>
        </cc:implementation>
    
    </cdk:root>
    

This renderer is simple, again comparable to the hello.template.xml. The new piece we’ve introduced is the <cdk:body /> tag. This tag indicates where we want to render the contents of the component. So any content (or child components) we nest in out tab tag will be wrapped by the div tag.

We’ll see this <cdk:body /> tag again when we look as the (slightly more complex) tabs renderer:

tabs.template.xhtml
<?xml version="1.0" encoding="UTF-8"?>
    
    <cdk:root xmlns="http://jboss.org/schema/richfaces/cdk/xhtml-el"
            xmlns:cdk="http://jboss.org/schema/richfaces/cdk/core"
            xmlns:c="http://jboss.org/schema/richfaces/cdk/jstl/core"
            xmlns:cc="http://jboss.org/schema/richfaces/cdk/jsf/composite">
    
        <cc:interface>
            <cdk:class>ca.bleathem.richfaces.jquery.renderkit.TabsRenderer</cdk:class>
            <cdk:superclass>org.richfaces.renderkit.html.DivPanelRenderer</cdk:superclass>
            <cdk:renderer-type>ca.bleathem.jquery.TabsRenderer</cdk:renderer-type>
            <cdk:resource-dependency name="" />
            <cdk:resource-dependency library = "javax.faces" name = "jsf.js" />
            <cdk:resource-dependency name = "jquery.js" />
            <cdk:resource-dependency library = "com.jqueryui/css/ui-lightness" name = "jquery-ui-1.8.16.custom.css" />
            <cdk:resource-dependency library = "com.jqueryui/development-bundle/ui" name = "jquery.ui.core.js" />
            <cdk:resource-dependency library = "com.jqueryui/development-bundle/ui" name = "jquery.ui.tabs.js" />
        </cc:interface>
    
        <cc:implementation>
            <div id="#{clientId}" class="rf_jq_tabs">
                <ul>
                    <c:forEach items="#{component.children}" var="child">
                        <li><a href="##{child.clientId}">#{child.attributes['title']}</a></li>
                    </c:forEach>
                </ul>
                <cdk:body />
            </div>
    
            <script type="text/javascript">
                jQuery(function() {
                    $(document.getElementById('#{clientId}')).tabs();
                });
         </script>
        </cc:implementation>
    
    </cdk:root>
    

This renderer template introduces a number of new concepts. For one, you might have noticed I didn’t create a RenderBase class, like we did for the datepicker component. We could have, but I wanted to demonstrate that it’s not strictly necessary. The CDK allows one to replace the @ResourceDependency annotations we used in the DatepickerRenderBase, with a CDK tag: <cdk:resource-dependency />. This is a one-for-one replacement for the annotation, with matching attributes (in fact, the CDK creates actual @ResourcesDependency annotations in the generated java code). This allows us to define all the required javascript and css resources required by the component in the renderer template itself.

We’ve also made use of the jstl core EL expressions to execute some logic in our renderer. You can see we loop over each of the children of the tabs component, which will be our tab components. For each child tab, we create an entry in an unordered list with the title attribute of the tab. This isn’t just some arbitrary html, we are fulfilling the contract of the jQuery UI tabs plugin. The plugin is going to look for this specific markup to render the tab components, and attach the necessary behavior.

Following the unodered list, we see the <cdk:body /> tag. This renders the child components, delegating to the render associated with each child. In this case, the children are the tab components and will be rendered using the tab renderer from the above tab.template.xhtml template.

The last piece of this template is the javascript call, where we invoke the jQuery UI tabs plugin to enable the client-side behavior. We aren’t passing any options to the plugin in this example, but we could easily do so using the scriptOption CDK tag demonstrated with the datepicker component.

The Result

So what does it look like when we put it all together?

With this sample markup:

    <b:tabs>
        <b:tab title="Tab 1">
            Hello <b>Tab</b>!!
        </b:tab>
        <b:tab title="Tab 2">
            With nested components:
            <br />
            <b:datepicker value="#{myBean.value}" dateFormat="yy-mm-dd" showOn="both" buttonImageOnly="true" /> <br />
        </b:tab>
    </b:tabs>
    

We can see we have multiple tabs, and for kicks I nested the datepicker component from the previous CDK entry.

So here it is, the jQuery UI tabs plugin wrapped with the RichFaces CDK, providing us with a bare-bones tab component. A lot more work is required to get this to a point where it could replace the RichFaces tab component, but we have succeeded in creating a functional component leveraging existing javascript code, and without a lot of work on our part.


Friday, October 7, 2011

RichFaces 4 CDK | jQuery UI Calendar

Further incrementing the complexity over the input component we created previously, this time we will create a JSF calendar component. Being pragmatic OSS developers, we will leverage the existing javascript of the datepicker component from the jQuery UI project, and we’ll see how well the RichFaces CDK lends itself to mapping JSF component attributes into javascript configuration options.

As always, if you are interested in following along in your IDE, you can get the code below on github.

The Component Class

Starting again with the component class:

AbstractDatepicker.java
package ca.bleathem.richfaces.jquery.component;
    
    import org.richfaces.cdk.annotations.*;
    
    @JsfComponent(
            type = "ca.bleathem.richfaces.jquery.Datepicker",
            family = "ca.bleathem.Datepicker",
            renderer = @JsfRenderer(type = "ca.bleathem.jquery.DatepickerRenderer"),
            tag = @Tag(name="datepicker"))
    abstract public class AbstractDatepicker extends javax.faces.component.UIInput {
    
        @Attribute
        public abstract String getDateFormat();
    
        @Attribute
        public abstract String getShowOn();
    
        @Attribute
        public abstract String getButtonImageOnly();
    
    }

Here we see we are again extending the UIInput class, as we did with the Input component. What’s new is the introduction of some additional attributes. The @Attribute annotation instructs the CDK that these abstract getter methods map to component attributes, and the CDK then takes care of wiring the attributes into the JSF state saving mechanism for us.

The naming convention of the attribute is alligned with jQeury UI datepicker options. This allows us to transparently pass the JSF component attributes through to the jQuery plugin, as we see in the Renderer below.

The Renderer

The renderer is again an xml file:

datepicker.template.xml
<?xml version="1.0" encoding="UTF-8"?>
    
    <cdk:root xmlns="http://jboss.org/schema/richfaces/cdk/xhtml-el" xmlns:cdk="http://jboss.org/schema/richfaces/cdk/core"
        xmlns:c="http://jboss.org/schema/richfaces/cdk/jstl/core" xmlns:cc="http://jboss.org/schema/richfaces/cdk/jsf/composite"
        xmlns:javaee="http://java.sun.com/xml/ns/javaee">
    
        <cc:interface>
            <cdk:class>ca.bleathem.richfaces.jquery.renderkit.DatepickerRenderer</cdk:class>
            <cdk:superclass>ca.bleathem.richfaces.jquery.renderkit.DatepickerRendererBase</cdk:superclass>
            <cdk:renderer-type>ca.bleathem.jquery.DatepickerRenderer</cdk:renderer-type>
        </cc:interface>
    
        <cc:implementation>
            <input type="text" id="#{clientId}" name="#{clientId}" class="rf_jq_cal" value="#{getInputValue(facesContext, component)}" />
            <script type="text/javascript">
                <cdk:scriptObject name="pluginOptions">
                    <cdk:scriptOption name="buttonImage" value="#{getResourcePath(facesContext, 'ca.bleathem', 'calendar.gif')}" />
                    <cdk:scriptOption attributes="showOn dateFormat buttonImageOnly" />
                </cdk:scriptObject>
                jQuery(function() {
                    $(document.getElementById('#{clientId}')).datepicker(#{toScriptArgs(pluginOptions)});
                });
    	    </script>
        </cc:implementation>
    
    </cdk:root>
    

Diving first into the cc:implementation of this renderer template, we see again an input element. What’s new is the script tag following the input. This script tag get’s compiled into javascript when the component renders. Using CDK xml markup, we build up the javascript object pluginOptions which we pass as a parameter to the call to the jQueryUI plugin.

The document.getElementById(‘#{clientId}’) is a workaround for JSF’s use of the “:” character in javascript IDs – this doesn’t play well with jQuery. By first calling document.getElementById, we end up with an argument that is acceptible to jQuery. Notice the #{toScriptArgs(pluginOptions)} argument to the datepicker jQuery UI plugin. This initializes the datepicker plugin, with the JSF component attributes specified by the application developer.

From the cc:interface of this renderer template, we see that we are extending the class DatepickerRendererBase. This class is included below:

DatepickerRendererBase.java
package ca.bleathem.richfaces.jquery.renderkit;
    
    import org.richfaces.renderkit.InputRendererBase;
    
    import javax.faces.application.ResourceDependencies;
    import javax.faces.application.ResourceDependency;
    
    @ResourceDependencies({
            @ResourceDependency(library = "javax.faces", name = "jsf.js"),
            @ResourceDependency(name = "jquery.js"),
            @ResourceDependency(library = "com.jqueryui/css/ui-lightness", name = "jquery-ui-1.8.16.custom.css"),
            @ResourceDependency(library = "com.jqueryui/development-bundle/ui", name = "jquery.ui.core.js"),
            @ResourceDependency(library = "com.jqueryui/development-bundle/ui", name = "jquery.ui.widget.js"),
            @ResourceDependency(library = "com.jqueryui/development-bundle/ui", name = "jquery.ui.datepicker.js"),
            @ResourceDependency(library = "ca.bleathem", name = "calendar.gif")
    })
    public class DatepickerRendererBase extends InputRendererBase {
    }
    

The DatepickerRendererBase class is again extending the InputRendererBase, and it is holding a number of @ResourceDependency annotations. These annotations ensure the appropriate resources are included on the page when we reference this JSF component. For us, these resources are the jQuery UI plugins necessary to get the datepicker component working.

Introducing an entire new class merely to hold the @ResourceDependency annotations may seem like overkill, but in any reasonably complex component, we will end up putting some renderer helper logic into this class file. There are times when the expressivity of Java works better than the declarativity of xml. We’ll see some of this later in our blog series.

Finally, let’s look at en example use of this component:

sample.xhtml
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:ui="http://java.sun.com/jsf/facelets"
          xmlns:b="http://bleathem.ca/test"
          >
    
    <body>
    <ui:composition template="/templates/template-jqueryui.xhtml">
    
        <ui:define name="title">Datepicker Sample</ui:define>
    
        <ui:define name="body">
            <h:form>
                <b:datepicker value="#{myBean.value}" dateFormat="yy-mm-dd" showOn="both" buttonImageOnly="true" /> <br />
                Input value: <h:outputText value="#{myBean.value}" /> <br />
                <h:commandButton value="Submit" action="null"/>
            </h:form>
        </ui:define>
    </ui:composition>
    </body>
    </html>
    

When rendered, this looks like:

Screen shot

While this has certainly grown in complexity over our initial HelloWorld component, we’ve managed to keep our JSF component development DRY. We’ve leveraged existing, high-quality javascript components. We’ve also made use of the RichFaces CDK to wire the JSF configured component to the javascript object. Some additional work is required to continue mapping the jQuery UI datepicker plugin options into JSF component attributes, but the mechanism for this has been laid out, and completing the component will be quite straight forward (pull requests welcome!).

In my next CDK installment, we’ll look at creating a layout based component, rather than an input component. Stay tuned!


Wednesday, September 21, 2011

RichFaces 4 CDK | Input Component

With our last component, we saw how we could output some simple text with a custom JSF component created with the RichFaces CDK. Let’s increment the complexity, and see how we can create a component that accepts input. Again, the goal here is to highlight how the important features fit together, and to leverage as much of the plumbing work as possible from the RichFaces CDK.

If you are interested in following along in your IDE, you can get the code below on github.

The Component Class

In a similar approach to our Hello World component, we’ll start with the component class for our Input component:

AbstractInput.java
package ca.bleathem.richfaces.input.component;
    
    import org.richfaces.cdk.annotations.*;
    
    @JsfComponent(
            type = "ca.bleathem.richfaces.input.Input",
            family = "ca.bleathem.input",
            renderer = @JsfRenderer(type = "ca.bleathem.input"),
            tag = @Tag(name="input"))
    abstract public class AbstractInput extends javax.faces.component.UIInput {
    
    }
    

This looks pretty similar to the component class for the Hello World component, with an appropriate changing or type, family, renderer and tag. One significant change to take note of is the base class for the component. Notice how we are extending the UIInput class. This allows us to leverage the value holding and state saving that has already been built into this component. No matter what kind of UI you want to build for your component, you will almost always want to store a single value (we’ll discuss select many components in another post). So extending UIInput is generally a good idea.

The Renderer

The corresponding renderer template for our input component is:

input.template.xml
<?xml version="1.0" encoding="UTF-8"?>
    
    <cdk:root xmlns="http://jboss.org/schema/richfaces/cdk/xhtml-el" xmlns:cdk="http://jboss.org/schema/richfaces/cdk/core"
        xmlns:c="http://jboss.org/schema/richfaces/cdk/jstl/core" xmlns:cc="http://jboss.org/schema/richfaces/cdk/jsf/composite"
        xmlns:javaee="http://java.sun.com/xml/ns/javaee">
    
        <cc:interface>
            <cdk:class>ca.bleathem.richfaces.input.renderkit.InputRenderer</cdk:class>
            <cdk:superclass>org.richfaces.renderkit.InputRendererBase</cdk:superclass>
            <cdk:renderer-type>ca.bleathem.input</cdk:renderer-type>
        </cc:interface>
    
        <cc:implementation>
            <input type="text" name="#{clientId}" value="#{getInputValue(facesContext, component)}" />
        </cc:implementation>
    
    </cdk:root>
    

Again, this looks pretty similar to the template for the Hello World component. The key difference being the Renderer superclass, and the html markup in the cc:implementation. By extending the RichFaces InputRendererBase class, we save ourselves from having to write the logic to decode and invoke the validators for our component. Again, this is something we will want to do for many of the components we write.

The html markup is also rather simple. By giving the input element the name of our component ID, we are indicating which form component should be decoded when the component is processed. When authoring a component with a complex UI, you will often make this input element a hidden input type, to store and submit your value while not interfering with your UI. We’ll see more of this in later entries of this CDK series.

I’ll also add that the package-info.java file described in the Hello World entry is still required, if you don’t already have one included in your jar.

And that’s our input component – again done as simply as possible. The next entry will wrap an existing jQuery UI component, showing how the CDK is an effective means to leverage the work others have already put in to authoring complex javascript components.


Saturday, September 10, 2011

RichFaces 4 CDK | Hello World

This is the first technical post of my CDK series. Starting real simple, we’ll create a component that produces a hello world output. “Why start with a hello world? Isn’t that a little cliche?”. Well indeed it is, but it is by far the best way to point out the fundamental pieces of the CDK, and how they together. We’ll build a strong foundation in our understanding of the CDK, on which we can build more interesting components in future posts.

If you are interested in following along in your IDE, you can get the code below on github.

The Component Class

To start, we need a component class. The component class itself will be generated by theRichFaces CDK. However we do define a base class from which the generated class will extend. We’ll see why this is the case when we get to more complex components. But for now, let’s start with this base class:

AbstractHello.java
package ca.bleathem.richfaces.hello.component;
    
    import org.richfaces.cdk.annotations.*;
    
    @JsfComponent(
            type = "ca.bleathem.richfaces.hello.Hello", 
            family = "ca.bleathem.text", 
            renderer = @JsfRenderer(type = "ca.bleathem.hello"), 
            tag = @Tag(name="hello"))
    abstract public class AbstractHello extends javax.faces.component.UIComponentBase {
    
    }
    

Here we have an abstract class annotated with @JsfComponent. This annotation marks the class as a CDK class, and will be consumed by the CDK pre-processor. The CDK uses the attributes of the annotation to construct the necessary classes, and the necessary xml configuration. Creating JSF components is verbose, but we don’t have to worry about the verbosity – the CDK takes care of it for us!

Let’s look more closely at the @JsfComponent annotation, and the meaning of each of it’s attributes. I’ll start by pointing out that the annotation supports many more attributes, but we are only covering here the bare minimum required to get a simple hello world component created.

type
the value of the type attribute is how JSF identifies out component. It will be used in the generated faces-config file, and in the generated xml taglib file.
family
the value of the family attribute is used by JSF to recognize “like” components. We’ll get into details of this in future posts. This attribute is in fact optional, and the value can be generated by naming conventions. However, I prefer to specify it explicitly.
renderer
the value of the renderer attribute is used to match our component to an appropriate renderer. We’ll create the renderer next!
tag
the value of the tag attribute will be the actual facelet tag that we use in our facelet files.

The last aspect of out component class that I want to point out is the “extends UIComponentBase” part. Every JSF UI component must extend this class, or one of it’s descendants. We’ll be able to save ourselves alot of work when we get to more complex components, by judiciously choosing the right class to extend.

The Renderer

Next, let’s look at the JSF Renderer:

hello.template.xml
<?xml version="1.0" encoding="UTF-8"?>
    
    <cdk:root xmlns="http://jboss.org/schema/richfaces/cdk/xhtml-el" xmlns:cdk="http://jboss.org/schema/richfaces/cdk/core"
        xmlns:c="http://jboss.org/schema/richfaces/cdk/jstl/core" xmlns:cc="http://jboss.org/schema/richfaces/cdk/jsf/composite"
        xmlns:javaee="http://java.sun.com/xml/ns/javaee">
    
        <cc:interface>
            <cdk:class>ca.bleathem.richfaces.hello.renderkit.HelloRenderer</cdk:class>
            <cdk:superclass>javax.faces.render.Renderer</cdk:superclass>
            <cdk:renderer-type>ca.bleathem.hello</cdk:renderer-type>
        </cc:interface>
    
        <cc:implementation>
            Hello World! (from a RichFaces CDK component)
        </cc:implementation>
    
    </cdk:root>
    

If you are familiar with JSF Component development, you may be surprised to see that our Renderer is not a java class. On the other hand, you may find that it looks quite similar to a JSF 2 composite component. It has a <cc:interface> section, and cc:implementation> section, both of which are analogous to the facelet file of a composite component. In fact, you can prototype your components as composite components, then migrate to CDK components when you find you need the extra flexibility the CDK provides.

As we did for the component class, let’s dissect the cdk tags found in our renderer template.

<cdk:class>
this is the name of the JSF Renderer class that will be generated.
<cdk:superclass>
the class that will be extended by our generated JSF Renderer class. Here we are explicitly stating the default for reference when we get into more complex components.
<cdk:renderer-type>
this is how JSF identifies our Renderer. It will be used in the generated faces-config file, and in the generated xml taglib file.

And there we have it, a JSF Component, and it’s associated Renderer! — err almost. There is one final piece missing. We need to specify a name space for our component – the namespace that will be used on facelet pages that refer to our components. Fortunately, the CDK also makes this easy for us. All we need is a package-info.java in the java package of our component:

package-info.java
    @TagLibrary(uri="http://bleathem.ca/test",shortName="testLib")
    package ca.bleathem.richfaces.hello.component;
    import org.richfaces.cdk.annotations.TagLibrary;
    

Here you can see the @TagLibrary annotation that specifies the namespace of our component.

Now we can build a jar, include it in our application, and use our hello world component! Go ahead and run the build. If you are curious, take a look in the target/generated-sources folder. There you’ll see all the JSF classes and xml files that the CDK generated for us. Those are all classes and xml files we would have had to write ourselves if we weren’t using the CDK.

Well, a hello world JSF component – not really useful… but there is more coming! The next entry in this series will use the CDK to create an input component, and from there we’ll get into some more sophisticated components!

In closing, I want to add that the CDK is incredibly flexible, and there all multiple ways the above component could have been put together. I’m sticking to what I think is simplest, most clear, and most extensible.