Sunday, January 24, 2021

OmniFaces 3.10 released!

OmniFaces 3.10 has been released!

It introduces among others the new ViewResourceHandler which enables using JSF components and EL expressions in non-Facelets files, such as /sitemap.xml and /robots.txt, a new <o:sitemapUrl> component, and a new lazy="true" attribute for the <o:graphicImage.

You can find the complete list of additions, changes and fixes at What's new in OmniFaces 3.10? list in showcase.

Installation

Non-Maven users: download OmniFaces 3.10.1 JAR and drop it in /WEB-INF/lib the usual way, replacing the older version if any.

Maven users: use <version>3.10.1</version>.

<dependency>
    <groupId>org.omnifaces</groupId>
    <artifactId>omnifaces</artifactId>
    <version>3.10.1</version>
</dependency>

If you're already on Jakarta EE 9 (e.g. WildFly 22, OpenLiberty 21, etc), then use 4.0-M7 instead. It's the Jakartified version of 3.10.1.

Using JSF components and EL expressions in non-Facelets files

The ViewResourceHandler allows you to register a specific set of non-Facelets files as JSF views. This will allow you to use JSF components and EL expressions in among others /sitemap.xml and /robots.txt.

In order to install it, add it as resource handler in faces-config.xml:

<application>
    <resource-handler>org.omnifaces.resourcehandler.ViewResourceHandler</resource-handler>
</application>

The specific set of non-Facelets files can in turn be defined as the value of a web.xml context parameter with the name org.omnifaces.VIEW_RESOURCE_HANDLER_URIS which accepts a comma separated string:

<context-param>
    <param-name>org.omnifaces.VIEW_RESOURCE_HANDLER_URIS</param-name>
    <param-value>/robots.txt, /sitemap.xml</param-value>
</context-param>

A live demo can be seen on the ViewResourceHandler showcase page.

New component specifically for sitemap.xml

The <o:sitemapUrl> component is designed specifically for the /sitemap.xml. The prerequisite is that the above mentioned ViewResourceHandler is installed and configured for /sitemap.xml. It basically generates a sitemap-specific <url> element, whereby a given JSF view ID will be automatically converted to a bookmarkable URL in <loc>. Optionally the lastModified, changeFrequency and priority attributes can also be specified which then generate the associated <lastmod>, <changefreq> and <priority> elements.

A live demo can be seen on the ViewResourceHandler showcase page.

Lazy images

The existing <o:graphicImage> component has been enhanced to support the new lazy="true" attribute.

<o:graphicImage ... lazy="true" />

You can use it with any type of image and image source, as long as the dataURI is not set, else the lazy attribute is simply ignored.

When set, then the image will only be actually loaded when the window is finished loading, and the image is visible in the viewport. The trick is done by initially rendering an empty SVG image as data URI in src attribute and rendering the actual URL in the data-src attribute, along with a data-lazy="true" flag. Something like below (taken from the <o:graphicImage> showcase page):

<img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'/%3E" 
     data-src="/javax.faces.resource/Images_getSvgLogo.svg.xhtml?ln=omnifaces.graphic&v=1611510995216"
     data-lazy="true" />

The actual lazy loading work is done by the automatically included graphicimage.js script.

How about OmniFaces 2.x and 1.1x?

The 2.x got the same bugfixes as 3.10.1 and has been released as 2.7.10. This version is for JSF 2.2 users with CDI. In case you've already migrated to JSF 2.3, use 3.x instead.

The 1.1x is basically already since 2.5 in maintenance mode. I.e. only critical bugfix versions will be released. It's currently still at 1.14.1 (May 2017), featuring the same features as OmniFaces 2.4, but without any JSF 2.2 and CDI things and therefore compatible with CDI-less JSF 2.0/2.1.