Leverage jQuery plugins

to create JSF Components

  • Brian Leathem
  • Senior Software Engineer, Red Hat
  • JavaOne 2012 - San Francisco
  • 2012-09-02
  • Welcome to the session "Leverage jQuery plugins to create JSF Components"
  • JSF - Standardized Component Model

    web framework

    • Today we are going to talk about building JSF components,
    • demonstrating how quickly you can build custom components specifically tailored to your use cases,
    • leveraging one of JSF's most significant features: the standardized component model.
    • This component model provides us with a blueprint for building portable components we can then "plug" into any JSF application
    • providing us with a means to re-use our components across projects and teams,
    • Thus empowering our JSF developers with customized rich functionality, without requiring them to code to arbitrary javascript APIs

    Component Providers

    • You may probably asking yourself "why mess with building your own components when there are so many component providers out there?"
    • providing us with a wide variety of rich JSF components?
    • Odds are that no JSF component set provides all the components needed to meet your specific use case requirements
    • You are either faced with compromising your requirements to better align with the provided components
    • Mixing and matching component providers if you are lucky enough to find another provider with the specific feature you need
    • Or developing the component yourself
    • By the end of this talk you'll be in a position to explore this 3rd option to it's fullest

    Building JSF Components

    • Server-side code
      • Components
      • Renderers
      • taglib xml
      • faces-config.xml

    • Client-side code
      • HTML
      • CSS
      • javascript
    • This is all well and good, but JSF components are notoriously verbose to create
    • Traditionally Tricky business
    • Split code-base
    • For starters, we're dealing with a split code base.
    • We not only have to create the server side code: Components, Renderers, and xml config
    • We also have to create the client side pieces: the html, javascript, and CSS responsible for the component's behaviour and user-interactions

    Lots of browsers

    + mobile!

    • All this client-code then has to be tested in a in a multitude of browsers
    • and don't forget to test on mobile devices too

    The solution

    • Re-use existing javascript "widgets"
    • There is a huge potential for code re-use

    • Google search comparison:
      • JSF Component:
        •   ~ 3 Million hits
      • Javascript Component:
        • ~ 416 Million hits
    • But I'm not here to complain, I'm here to share a solution
    • You should be, and can easily be building JSF components using existing javascript "widgets"
    • By widgets, I mean self-contained free standing javscript code that encapsulates a user interaction
    • The important piece here is that these are self-contained components, framework independent, and not requiring any back-end nor framework code to operate

    Polyglot web apps

    • Polyglot JVM
    • Web frameworks in many languages/environments
    • Consistent L&F throughout a heterogeneous application
    • A Final motivation for building components on top of standalone javascript widgets - even when creating brand-new widgets
    • In this world of ployglot on the JVM, and hetergenous server environments, it's not uncommon to have a single application spread accross multiple frameworks
    • By using a consistent set of HTML markup, CSS, and javascript to enrich your application
    • you can achieve a consistent L&F for your users irrespective of the back-end technology

    Image Gallery

    • For example, look at this jQuery UI imagegallery widget
    • It's a trivial widget, with a rich usr interface.
    • To use it, you point the jQuery plugin at some correctly formatted html markup, and you end up with a fully functional, single-purpose image gallery
    • click on an thumbnail to get a zoomed-in popup of the photo, with controls to navigate through the provided collection of photos

    jQuery UI

    • jQuery plugins can also be fairly non-trivial
    • here we have the jQuery UI widget set, providing more complex functionality with tabs, datepickers, modal alerts, etc.


    • Another widget set generating a lot of excitement right now is the twitter Bootstrap project.
    • Bootstrap takes a stronger focus on HTML and CSS for widget behaviour, but does incorporate some javascript as well

    Image Gallery

    • A jQuery UI imagegallery plugin
    • An output only component
    • For example, look at this jQuery UI imagegallery widget
    • It's a trivial widget, with a rich usr interface.
    • To use it, you point the jQuery plugin at some correctly formatted html markup, and you end up with a fully functional, single-purpose image gallery
    • click on an thumbnail to get a zoomed-in popup of the photo, with controls to navigate through the provided collection of photos

    Image Gallery - Component

    <!DOCTYPE html>
    <html lang="en-US"
      <cc:attribute name="photos" />
      <!-- plugin configuration -->
      <cc:attribute name="selector" />
      [ ... snip ... ]
      <cc:attribute name="dialogClass" />
      <div id="#{cc.clientId}:div">
          <ui:repeat value="#{cc.attrs.photos}" var="photo">
              <a rel="gallery" href="#{photo.full}" title="#{photo.title}">
                  <img src="#{photo.thumb}" alt="#{photo.title}" />
      <h:outputScript library="javax.faces" name="jsf.js"/>
      <h:outputScript library="composite/com.jquery" name="jquery-1.7.2.min.js"/>
      <h:outputScript library="composite/com.jqueryui/js" name="jquery-ui-1.8.19.custom.min.js"/>
      <h:outputScript library="composite/com.github.blueimp/js" name="load-image.js"/>
      <h:outputScript library="composite/com.github.blueimp/js" name="jquery.image-gallery.js"/>
      <h:outputStylesheet library="composite/com.jqueryui/css/ui-lightness" name="jquery-ui.custom.css"/>
      <h:outputStylesheet library="composite/com.github.blueimp/css" name="jquery.image-gallery.css"/>
          var pluginOptions = {};
          ! '#{cc.attrs.selector}' || (pluginOptions.selector = '#{cc.attrs.selector}');
          [ ... snip ... ]
          ! '#{cc.attrs.dialogClass}' || (pluginOptions.dialogClass = '#{cc.attrs.dialogClass}');
          jQuery(function() {
    • Let's take a look at the code required to make a JSF 2 component out of these javascript widgets
      1. Here we have a JSF 2 composite component, and starts like any other JSF facelet file
        • The composite component has 2 sections, and interface and an implementation
        • In the interface we specify the attributes of the facelet tag
        • The attributes consist of the list of photos we want to include in our gallery
        • and all the options available to configure the jQuery plugin (which I've cut out for brevity)
      2. Next we have the html to generate: we loop of the photos list, and output an anchor tag for each photo
      3. We then map the component attributes into a javascript object
      4. which we then pass as an parameter when we invoke the jQuery plugin

    Packaging the cc

    • Package your composite components in a jar file to share across teams/apps

    Using the imagegallery component

    <!DOCTYPE html>
    <html lang="en-US">
    <ui:composition template="/resources/template.xhtml"
        <ui:define name="body">
            <h:form id="form">
                Some sample of the component:
                <s:imagegallery photos="#{galleryBean.photos}"/>


    public class GalleryBean {
      private List<FlickrPhoto> photos;
      public GalleryBean() {
        photos = new ArrayList<FlickrPhoto>();
        photos.add(new FlickrPhoto("title a", "http://flickr.com/a..."));
        photos.add(new FlickrPhoto("title c", "http://flickr.com/c..."));
        photos.add(new FlickrPhoto("title d", "http://flickr.com/d..."));
      public List<FlickrPhoto> getPhotos() {
        return photos;
    • This component gives a rich looking interface demo-time it is in fact a simple "output-only" component

    jQuery UI Datepicker component

    • The jQuery UI datepicker plugin
    • An input component, bound to a backing bean

    Datepicker composite component

        <cc:attribute name="value" />
        <cc:attribute name="showOn" />
        <cc:attribute name="dateFormat" />
        <cc:attribute name="buttonImageOnly" />
        <h:inputText id="input" value="#{cc.attrs.value}" />
        <h:outputScript library="javax.faces" name="jsf.js"/>
        <h:outputScript library="composite/com.jquery" name="jquery-1.7.2.min.js"/>
        <h:outputScript library="composite/com.jqueryui/development-bundle/ui" name="jquery.ui.core.js"/>
        <h:outputScript library="composite/com.jqueryui/development-bundle/ui" name="jquery.ui.widget.js"/>
        <h:outputScript library="composite/com.jqueryui/development-bundle/ui" name="jquery.ui.datepicker.js"/>
        <h:outputStylesheet library="composite/com.jqueryui/css/ui-lightness" name="jquery-ui.custom.css"/>
            var pluginOptions = {
                buttonImage: "#{request.contextPath}/javax.faces.resource/calendar.gif.jsf?ln=composite/org.richfaces",
                buttonImageOnly: "#{"true" eq cc.attrs.buttonImageOnly}"
            ! '#{cc.attrs.showOn}' || (pluginOptions.showOn = '#{cc.attrs.showOn}');
            ! '#{cc.attrs.dateFormat}' || (pluginOptions.dateFormat = '#{cc.attrs.dateFormat}');
            jQuery(function() {
    • let's look at the implementation of a component that accept user input - the datepicker
    • This composite component follows nearly the same pattern as previous except for one difference:
    • We are delegate to the JSF input component to return the widget data back to the JSF servlet
    • The point I want to make is that so long as you can find a JSF component to delegate to you can write a JSF component leveraging any

    datepicker usage

    <s:datepicker buttonImageOnly="true"

    generated markup

    <input class="hasDatepicker" id="form:j_idt16:input" name="form:j_idt16:input" type="text">
    <img src="/composite-demo/javax.faces.resource/calendar.gif.jsf?ln=composite/org.richfaces" class="ui-datepicker-trigger">
    <script type="text/javascript" src="/composite-demo/javax.faces.resource/jsf.js.jsf?ln=javax.faces"></script>
    <script type="text/javascript"
    <script type="text/javascript"
    <script type="text/javascript"
    <script type="text/javascript"
    <script type="text/javascript">
      var pluginOptions = {
      !'both' || (pluginOptions.showOn = 'both');
      !'yy-mm-dd' || (pluginOptions.dateFormat = 'yy-mm-dd');
      jQuery(function () {

    jQuery UI tabs

    • The jQuery UI tabs plugin
    • A stateful component

    tabs composite component

    <cc:interface componentType="org.richfaces.sandbox.composite.UITabs">
        <div id="#{cc.clientId}">
          <h:inputHidden id="selected" value="#{cc.selected}" />
            <ui:repeat var="tab" value="#{cc.tabChildren}"> <!-- #{cc.children} broken see: JAVASERVERFACES-2099 -->
                <a href="##{tab.clientId}">#{tab.attributes['title']}</a>
          <cc:insertChildren />
        <h:outputScript library="javax.faces" name="jsf.js"/>
        <h:outputScript library="composite/com.jquery" name="jquery-1.7.2.min.js"/>
        <h:outputScript library="composite/com.jqueryui/development-bundle/ui" name="jquery.ui.core.js"/>
        <h:outputScript library="composite/com.jqueryui/development-bundle/ui" name="jquery.ui.widget.js"/>
        <h:outputScript library="composite/com.jqueryui/development-bundle/ui" name="jquery.ui.tabs.js"/>
        <h:outputStylesheet library="composite/com.jqueryui/css/ui-lightness" name="jquery-ui.custom.css"/>
            var pluginOptions = { selected: '#{cc.selected}' }
            $(function() {
                var widget = $(document.getElementById('#{cc.clientId}'));
                // initialize the plugin
                // register a tabselect change listener
                widget.bind("tabsselect", function(event, ui) {
                    var selected_input = '#{cc.clientId}' + ':selected';
                    // trigger an ajax update, executing the hiddn input element to update the component state
                    var options = { execute: selected_input }
                    jsf.ajax.request(selected_input, null, options);


    public class UITabs extends UINamingContainer {
        enum PropertyKeys {selected}
        public int getSelected() {
            return (Integer) getStateHelper().eval(PropertyKeys.selected, 0);
        public void setSelected(int selected) {
            getStateHelper().put(PropertyKeys.selected, selected);
        public List<UIComponent> getTabChildren() {
            List<UIComponent> children = this.getFacet("javax.faces.component.COMPOSITE_FACET_NAME").getChildren();
            List<UIComponent> tabChildren = new ArrayList<UIComponent>();
            for (UIComponent child : children) {
                if (child instanceof UITab) {
            return tabChildren;

    jQuery UI tab

    <cc:interface componentType="org.richfaces.sandbox.composite.UITab">
      <cc:attribute name="title" />
        <div id="#{cc.clientId}">
          <cc:insertChildren />

    tabs usage

    <s:tabs id="tabs">
      <s:tab title="Tab 1">
        Hello <b>Tab</b>!!
      <s:tab title="Tab 2">
        With nested components:
        <s:datepicker dateFormat="yy-mm-dd"

    JSF 2 CC limitations

    • When pushing the limits of composite components you often run up against either incomplete implementations or bugs
    • Examples: using composite components with includes, cc.children we saw earlier, and others
    • Additionally, sometimes we need to fallback on the greater expressivity of java
    • For instance when we need to wrap our child components with new html
    • In short composite components work well when you're requirements align well with an existing component to which you can delegate

    RichFaces CDK

    Use the RichFaces CDK to build "full-fledged" JSF components with the ease and syntax of JSF 2 composite components

    • The RichFaces CDK templating language is modeled after JSF 2 composite components
    • However when you use the RichFaces CDK, the template is rendererd into Java code at runtime
    • You end up with "full-fledged" jsf components, free of any limitations of the composite component way of building components
    • Bootstrap Dropdown Button

      • Group child buttons into a dropdown
      • Dropdown renders it's children

      Dropdown - CDK template

          <cdk:root xmlns="http://jboss.org/schema/richfaces/cdk/xhtml-el"
                <div class="btn-group #{component.vertical ne null ? component.vertical.buttonClass : ''}">
                    <a data-toggle="dropdown" href="#" cdk:passThrough="on*"
                       class="btn #{component.severity ne null ? component.severity.buttonClass : ''}
                              #{component.scale ne null ? component.scale.buttonStyleClass : ''}
                              #{component.buttonStyle} dropdown-toggle">
                        #{component.title.concat(' ')}
                        <span class="caret"></span>
                    <ul class="dropdown-menu #{component.horizontal ne null ? component.horizontal.buttonClass : ''}">
                        <c:forEach var="child" items="#{component.getChildren()}">
                                <cdk:call expression="child.encodeAll(facesContext)" />
      • not delegating to JSF components

      Dropdown Button - Component

              type = AbstractButtonDropdown.COMPONENT_TYPE,
              family = AbstractButtonDropdown.COMPONENT_FAMILY,
              renderer = @JsfRenderer(type = ButtonDropdownRendererBase.RENDERER_TYPE),
              tag = @Tag(name = "buttonDropdown"))
      public abstract class AbstractButtonDropdown extends UIPanel implements EventsMouseProps {
          public static final String COMPONENT_FAMILY = "org.richfaces.bootstrap.ButtonDropdown";
          public static final String COMPONENT_TYPE = "org.richfaces.bootstrap.ButtonDropdown";
          public abstract String getTitle();
          public abstract String getButtonStyle();
          public abstract BootstrapSeverity getSeverity();
          public abstract BootstrapSize getScale();
          public abstract HorizontalPosition getHorizontal();
          public abstract VerticalPosition getVertical();

      Dropdown - usage

      <b:buttonDropdown title="Primary" severity="primary">
          <h:link value="heroUnit"
              outcome="/component/heroUnit/index.xhtml" />
          <h:link value="tabbable"
          <h:link value="buttonGroup"
          <h:link value="navbar"