Leverage the jQuery plugin ecosystem

to create highly-interactive JSF Components

  • Brian Leathem
  • Senior Software Engineer, Red Hat
  • JAX - San Francisco
  • 2012-07-10
  • Welcome to the session "Leverage the jQuery plugin ecosystem to create highly-interactive 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 outcome="/component/heroUnit/index.xhtml" value="heroUnit"/>
              <h:link outcome="/component/tabbable/index.xhtml" value="tabbable"/>
              <h:link outcome="/component/buttonGroup/index.xhtml" value="buttonGroup"/>
              <h:link outcome="/component/navbar/index.xhtml" value="navbar"/>