Wednesday, November 19, 2014

Don't repeat expressions in facelets

Have you ever seen repeated EL expressions in JSF like this one?
<h:inputText value="#{oneBean.name}" rendered="#{anotherBean.showPerson}"/>
<h:inputText value="#{oneBean.birthday}" rendered="#{anotherBean.showPerson}"/>
<h:selectOneMenu value="#{oneBean.children}" style="#{anotherBean.showPerson ? 'display:block' : 'display:none'}"/>
usw. Another example:
<ui:include src="/include/somesnippet.xhtml">
    <ui:param name="age" value="#{someBean.isMan(person) ? 63 : 60}"/>
    <ui:param name="money" value="#{someBean.isMan(person) and someBean.getCountry(person) eq 'de' ? 1000 : 900}"/>
    <ui:param name="big" value="#{someBean.getCountry(person) eq 'zh' or someBean.getCountry(person) eq 'ru' ? true : false}"/>
</ui:include>
Expressions #{anotherBean.showPerson}, #{someBean.isMan(person)}, #{someBean.getCountry(person)} are repeated multiple times. How to optimize them? Well, you can use JSTL's c:set like this code snippet
<c:set var="showPerson" value="#{anotherBean.showPerson}"/>

<h:inputText value="#{oneBean.name}" rendered="#{showPerson}"/>
<h:inputText value="#{oneBean.birthday}" rendered="#{showPerson}"/>
<h:selectOneMenu value="#{oneBean.children}" style="#{showPerson ? 'display:block' : 'display:none'}"/>

<c:set var="man" value="#{someBean.isMan(person)}"/>
<c:set var="country" value="#{someBean.getCountry(person)}"/>

<ui:include src="/include/somesnippet.xhtml">
    <ui:param name="age" value="#{man ? 63 : 60}"/>
    <ui:param name="money" value="#{man and country eq 'de' ? 1000 : 900}"/>
    <ui:param name="big" value="#{country eq 'zh' or country eq 'ru' ? true : false}"/>
</ui:include>
If you are scared about JSTL pitfalls (because you have heard that JSTL is not always JSF friendly :-)), there is an alternative and simple approach - ui:param. TagHandler ui:param uses JSF's VariableMapper to save EL expressions in a map. This map maps EL variables on a page and the EL expressions they are associated with. And here you go:
<ui:param name="showPerson" value="#{anotherBean.showPerson}"/>

<h:inputText value="#{oneBean.name}" rendered="#{showPerson}"/>
<h:inputText value="#{oneBean.birthday}" rendered="#{showPerson}"/>
<h:selectOneMenu value="#{oneBean.children}" style="#{showPerson ? 'display:block' : 'display:none'}"/>

<ui:param name="man" value="#{someBean.isMan(person)}"/>
<ui:param name="country" value="#{someBean.getCountry(person)}"/>

<ui:include src="/include/somesnippet.xhtml">
    <ui:param name="age" value="#{man ? 63 : 60}"/>
    <ui:param name="money" value="#{man and country eq 'de' ? 1000 : 900}"/>
    <ui:param name="big" value="#{country eq 'zh' or country eq 'ru' ? true : false}"/>
</ui:include>
The code is more readable, especially if you have very complex and long expressions. Note: we're speaking here about readable code and not about performance optimization because JSF TagHandlers don't evaluate EL expressions.

Thursday, November 6, 2014

Dynamic aria-live for better accessibility experience

Every web developer working with the web accessibility (WAI ARIA) knows or heard about aria-live. This is an attribute, which indicates a live region - any updatable HTML element - and describes the types of updates the user agents, assistive technologies (screen readers), and user can expect from the live region. The default value of the aria-live is off. That means, updates to the region will not be presented to the user unless the assistive technology is currently focused on that region. The value polite means, assistive technologies should announce updates at the next graceful opportunity, such as at the end of speaking the current sentence or when the user pauses typing. There is also the value assertive, which forces assistive technologies to notify the user immediately. In additional, the aria-relevant attribute can specify if the updates on the live region should only be spoken when the corresponding DOM node is added or removed or both.

Most time you need to set the value once and don't care about it. E.g. markup for error messages can contain aria-live="polite".
<div class="messages" aria-live="polite">
    ... some messages ...
</div>
Every time when the content of the div container with class="messages" is updated, it will be spoken by screen readers. That's good, but sometimes you only would like to notify a sightless user when the new (after update) and old (before update) contents are not equal. Imagine a railway ticket shop where users can choose fare class, number of traveler, book places, etc. The total buy price is permanently updated. We can write
<span aria-live="polite">
    <div id="pricetotal">
        <span class="hiddenOfScreen">Total price </span>
        #{price}
    </div>
</span>
and update the div by AJAX. #{price} is a current price as EL expression calculated on the server-side (coming from the JSF world, but JavaScript templating has similar expressions). Whenever the div gets updated, screen readers speak the total price regardless if the amount was changed or not. A more clever approach sets aria-live dynamically at runtime. If the amount was changed, the aria-live on the div should have the value polite. If the old and new prices are equal, the div should have the value off. The off value prevents speaking by screen readers.

The idea is to save the last updated price in the data-price attribute of the parent element and compare the old and new prices on every AJAX update. In the code snippet below, the div with id="pricetotal" gets updated. The JavaScript block inside is being executed on every update. We read and compare old and new prices and manipulate the aria-live attribute at runtime. Whenever the aria-live is set to polite, screen readers speak "Total price" and the amount.
<span data-price="#{price}">
    <div id="pricetotal">
        <span class="hiddenOfScreen">Total price </span>
        <span class="priceoutput">#{price}</span>
        <script type="text/javascript">
            $(document).ready(function () {
                $pricetotal = $('#pricetotal');
                var oldPrice = $pricetotal.parent().data('price');
                var newPrice = $pricetotal.find('.priceoutput').text();
                if (oldPrice != newPrice) {
                    $pricetotal.attr('aria-live', 'polite');
                    $pricetotal.parent().data('price', newPrice);
                } else {
                    $pricetotal.attr('aria-live', 'off');
                }
            });
        </script>
    </div>
</span>
If prices are not equal, the new price is saved in the data-price to make it available in the next update.

Sunday, November 2, 2014

PrimeFaces Extensions 3.0.0 released

Today, we released the PrimeFaces Extensions 3.0.0. It is built on top of PrimeFaces 5.1 and is fully compatible with PrimeFaces 5.1.x.

There are new components: pe:countDown, pe:knob, pe:gravatar, pe:documentViewer, pe:analogClock, pe:gChart. I have blogged about them.

The new deployet showcase will be available soon as usually here. The next release will be a maintenance release. It is time for bugfixing.

Have fun!

Saturday, October 11, 2014

WAI-ARIA support for AutoComplete widget

In this post I would like to discuss the accessibility for an AutoComplete widget. A typically AutoComplete widget provides suggestions while you type into the field. On my current work I implemented an JSF component on basis of Twitter's Typeahead - a flexible JavaScript library that provides a strong foundation for building robust typeaheads. The Typeahead widget has a solid specification in form of pseudocode that details how the UI reacts to events. The Typeahed can show a hint in the corresponsing input field, like the google's search field shows it, highlight matches, deal with custom datasets and precompiled template. Furthermore, the Bloodhound suggestion engine offers prefetching, intelligent caching, fast lookups, and backfilling with remote data.


Despite many features, one big shortcoming of the Typeahead is an insufficient WAI-ARIA support (I would say it was completely missing until now). An AutoComplete widget should be designed to be accessible out of the box to users of screen readers and other assistive tools. I have decided to add a fully WAI-ARIA support, done this taks and sent my pull request to the GitHub. Below is the new "WAI-ARIA aware" markup with an explanaition (not relevant HTML attributes are omitted).
<input class="typeahead tt-hint" aria-hidden="true">

<input class="typeahead tt-input" role="combobox"
    aria-autocomplete="list/both"
    aria-owns="someUniqueID"
    aria-activedescendant="set dynamically to someUniqueID-1, etc."
    aria-expanded="false/true">
  
<span id="someUniqueID" class="tt-dropdown-menu" role="listbox">
    <div class="tt-dataset-somename" role="presentation">
        ...
        <span class="tt-suggestions" role="presentation">
            <div id="someUniqueID-1" class="tt-suggestion" role="option">
                ... single suggestion ...
            </div>
            ...
        </span>
        ...
    </div>
</span>

<span class="tt-status" role="status" aria-live="polite" style="border:0 none; clip:rect(0, 0, 0, 0); height:1px;
      width:1px; margin:-1px; overflow:hidden; padding:0; position:absolute;">
      ... HTML string or a precompiled template ...
</span>
The first input field with the class tt-hint simulates a visual hint (s. the picture above). The hint completes the input query to the matched suggestion visually. The query can be completed to the suggestion (hint) by pressing either right arrow or tab key. The hint is not relevant for the screen readers, hence we can apply the aria-hidden="true" to that field. The hint is ignored by screen readers then. Why is it not important? Because we will force reading the matched suggestion more intelligent by the "status" area with aria-live="polite" (will be explained below).

The next input field is the main element where the user inputs query. It should have a role="combobox". This is a recommended role for an AutoComplete. See the official WAI-ARIA docu for more details. In fact, the docu also shows a rough markup structure of an AutoComplete!

The main input field should have various ARIA states and properties. aria-autocomplete="list" indicates that the input provides autocomplete suggestions in the form of a list as the user types. aria-autocomplete="both" indicates that suggestions are also provided by a hint (additional to a list). The property aria-owns indicates that there is a parent / child relationship between the input field and the list with suggestions. This property should be always set when the DOM hierarchy cannot be used to represent the relationship. Otherwise, screen readers will get a problem to find a list with suggestions. In our case, it points to the ID of the list. The most interesting property is aria-activedescendant. A sightless user navigates through the list via arrow keys. The property aria-activedescendant propagates changes in focus to assistive technology - it is adjusted to reflect the ID attribute of the current child element which has been navigated to. In the picture above, the item "Lawrence of Arabia" is selected (highlighted). aria-activedescendant is set to the ID of this item and screen readers read to blind users "Lawrence of Arabia". Note: the focus stays on the input field, so that you can still edit the input value. I suggest to read more about this property in the Google's Introduction to Web Accessibility.


The property aria-expanded indicates whether the list with suggestions is expanded (true) or collapsed (false). This property will be updated automatically when the list's state changes.

The list with suggestions itself should have a role "listbox". That means, the widget allows the user to select one or more items from a list of choices. role="option" should be applied to individual result item nodes within the list. There is an interesting article "Use "listbox" and "option" roles when constructing AutoComplete lists", which I suggest to read. Not important for the screen readers parts should be marked with role="presentation". This role says "My markup is only for non sightless users". You probably ask, what is about the role="application"? Is it important for us? Not really. I skipped it after reading "Not All ARIA Widgets Deserve role="application"".

The last element in the markup is a span with the role="status" and the property aria-live="polite". What it is good for? You can spice up your widget by letting the user know that autocomplete results are available via a text that gets automatically spoken. The text to be spoken should be added by the widget to an element that is moved outside the viewport. This is the mentioned span element with applied styles. The styles are exactly the same as the jQuery CSS class ui-helper-hidden-accessible, which hides content visually, but leaves it available to assistive technologies. The property aria-live="polite" on the span element means – updates within this element should be announced at the next graceful interval, such as when the user stops typing. Generally, The aria-live property indicates a section within the content that is live and the verbosity in which changes shall be announced. I defined the spoken text for the AutoComplete in my project as an JavaScript template compiled by Handlebars (any other templating engine such as Hogan can be used too).
Handlebars.compile(
    '{{#unless isEmpty}}{{count}} suggestions available.' +
    '{{#if withHint}}Top suggestion {{hint}} can be chosen by right arrow or tab key.' +
    '{{/if}}{{/unless}}')
When user stops to type and suggestions are shown, a screen reader reads the count of available suggestions and the top suggestion. Really nice.

Last but not least is the testing. If you do not already have a screen reader installed, install the Google Chrome extensions ChromeVox and Accessibility Developer Tools. These are good tools for the development. Please watch a short ChromeVox demo and a demo for Accessibility Developer Tools too. Alternative, you can also try a free standalone screen reader NVDA. Simple give the tools a try.

Thursday, September 18, 2014

Brand new JSF components in PrimeFaces Extensions

The PrimeFaces Extensions team is glad to announce several new components for the upcoming 3.0.0 main release. Our new committer Francesco Strazzullo gave a "Turbo Boost" for the project and brought at least 6 JSF components which have been successfully intergrated! The current development state is deployet on OpenShift - please look the showcase Below is a short overview about added components with screenshots.

Analog Clock. This is a component similar to digital PrimeFaces Clock, but as an analog variant, enhanced with advanced settings.


Countdown. It simulates a countdown and fires an JSF listener after an customizable interval. You can start, stop and pause the countdown.


DocumentViewer. This is JSF wrapper of Mozilla Foundation project PDF.js - a full HTML PDF reader.


GChart. This is a JSF wrapper of Google Charts API. It's the same chart library used by Google Analytics and other Google services. Please look at Organizational Chart and Geo Chart.


A small note from me: charts can be built completely by model in Java. There is only one GChartModel which allows to add any options you want programmatically. I have used the same approach for my Chart library based on Flotcharts (thinking right now about adding it to the PF Extensions). There is only one generic model with generic setters to set options (options are serialized to JSON then). Advantage: you can export a chart on the server-side, e.g. with PhantomJS. This is a different approach to PrimeFaces' charts where each chart type has a separate model class and hard-coded fix methods for options settings.

Gravatar. This is a component for Gravatar services.


Knob. This is a nice theme-aware component to insert numeric values in a range. It has many settings for visual customization, AJAX listener and more.


Last but not least: we plan to deploy current SNAPSHOTs on the OpenShift in the future. More new components are coming soon. I intend to bring a component called pe:typeahead to the 3.0.0 too. It is based on Twitter's Typeahed. In the next post, I will explain how I have added an excellent WAI ARIA support to this great autocomplete widget. Stay tuned!