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.

Wednesday, November 23, 2011

RichFaces 4.1.0.CR1 Release Announcement

I’m excited to announce the availability of RichFaces 4.1.0.CR1, the first release candidate for RichFaces 4.1.0. Stability of the platform has been a strong focus for all the RichFaces 4.1.0 milestone releases, and has been even more so of a focus for our CR1 release.

We really appreciate the community feedback we’ve received throughout the 4.1 development cycle, with each of the milestone releases. The bugs found and the suggestions provided from the community have really helped us nail down this release. As such, we are encouraging everyone to download this release candidate, and help us flush out any regressions or other potential blocker issues. Let us not forget, "given enough eyeballs, all bugs are shallow"!

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.1.0.20111111-CR1. For more information on setting up a RichFaces 4 application, refer to our getting started guide.

With that “call to arms” out of the way, let’s take a look at what’s changed in this release.

Mobile Compatibility
We have been working on the RichFaces mobile guide, and will have it available shortly - watch for it the RichFaces wiki. Refer to this guide to take advantage of the mobile compatibility of the RichFaces components in our mobile showcase as we presented at a recent JBoss webinar (video of the webinar is available). The CSS and javascript we used in our mobile showcase has been cleaned-up and refactored, and ready for public consumption, with details of how to do so in the mobile guide.

We've also improved the mobile compatibility of some individual components, such as the calendar component (specifically the time picker), and the rendering of the pickList buttons. Thanks to the community members who pointed these deficiencies out!

Documentation
The Component Reference and Developer Guide have been updated for this release candidate, in preparation for the upcoming final release. In addition, a bug in the automatic generation of the VDL-DOC (tag library docs) has been addressed, once again providing a complete listing of all RichFaces components’ attributes. The latest javadoc has also been published.

Many of the attribute descriptions themselves in the VDL-DOC still need to be filled out (pull requests here would be very welcome!) - so be sure to refer to the Component Reference to supplement the VDL-DOC.

Framework upgrades
We upgraded our client-side bean validation extension to use Hibernate Validator 4.2, aligning with what is currently shipped in JBoss AS 7, and with what developers will be using with their applications. We also changed the project compiler compatibility to Java SE 6.0, reflecting in reality what has been true for the project for some time. We also started verification of the RichFaces platform against the upcoming JBoss AS 7.1 release, aiming for a smooth transition for RichFaces applications when AS 7.1 is released.

Individual improvements
Individual components have seen some improvements with this release. Ajax rendering of drag sources and drop targets has been improved, tab panel switching across the client/server has been cleaned up, and the tooltip was changed to better respect the value attribute for delivering the tooltip message. In addtion to these individual fixes, we addressed a number of IE8 compatibility issues.

Onward to Final
Unfortunately, we’ve have introduced some regressions with this release, namely with the calendar component and table sorting/filtering. These issues have already been addressed in our development branch, and will be ready for the upcoming final release.

Be sure to give this release a spin, and help us make 4.1.0.Final a top-notch release!

Wednesday, November 9, 2011

RichFaces 4.1.0.M4 Release Announcement

The RichFaces 4.1 Milestone 4 release is now available for download! With this M4 release we focused on stabilizing the features we introduced in the earlier 4.1 release-train milestones (M1, M2, M3). The release following M4 will be our 4.1 release candidate, so we want to make sure we achieve maximum stability with M4. Some of the key areas we touched are listed below.

If your keen and want to get started right away, you can download the distribution directly, or for maven users, increment the RichFaces version in your pom.xml to 4.1.0.20111101-M4. For more information on setting up a RichFaces 4 application, refer to our getting started guide.

Mobile showcase improvements
The CSS 3 overlay was improved to provide better mobile compatibility of the components. We also added an ajax status indicator to the mobile showcase. Since it is entirely an ajax driven application, the status indicator improves the user experience dramatically.

Resource mapping
The resource mapping feature introduced in M3 has been made more usable, adopting a consistent naming convention, with reasonable defaults. Additionally the ability to completely disable the feature was introduced, should you want to handle resources yourself in your applications.

Client Side validation
Improvements to the client-side validation (CSV) involved better aligning the client-side regexp with the Bean Validation specification. The CSV mechanism for discerning component values on the client (using javascript) was enhanced to improve the CSV interop with other JSF component providers.

Individual component fixes
The file upload component has some new attributes, allowing for more fine-grained control over what the user is able to upload to the server. The pickList saw the switchByClick and switchByDblClick functionality from RichFaces 3 ported to RichFaces 4, further improving the RF 3 to RF 4 migration story.

Misc. Fixes
Some additional issues resolved include a jQuery update (to version 1.6.4), and improvements to both the simpleapp and GAE RichFaces archetypes. Many more fixes and improvements were checked, feel free to browse the issues fixed to see what else has been improved.

Forward: CR1 & Further Stabilisation
The CR1 development is currently ongoing, with a focus on providing documentation for all the new 4.1 features, and further stabilisation. So give M4 a spin, and let us know what you think! Drop a note in the forums, or join us for our weekly community/team meetings in IRC.