Chapter 1. Introducing PrimeFaces Extensions

PrimeFaces is a leading lightweight, open source User Interface (UI) component library for web applications based on JavaServer Faces (JSF). It provides a set of more than 100 UI components with a single JAR that requires zero configuration and no dependencies. Just as JSF (the Apache MyFaces implementation) has some extension packages, PrimeFaces has also come up with a community-driven extension and a new components set called PrimeFaces Extensions. It is a community-driven open source library that has been founded by Thomas Andraschko and Oleg Varaksin. This project aims to be a lightweight and fast JSF 2 component library in addition to PrimeFaces. It contains various components that are neither available in PrimeFaces nor in any other JSF UI library.

In this chapter, we will cover:

An introduction to PrimeFaces Extensions and its features
Installing and configuring PrimeFaces Extensions
Creating a simple HelloWorld application using PrimeFaces Extensions
Working with PrimeFaces Extensions project resources
Community support and a showcase for PrimeFaces Extensions

An introduction to PrimeFaces Extensions and its features

PrimeFaces Extensions is a lightweight, open source UI component library for applications based on JavaServer Faces 2.x. This project has been built on top of the PrimeFaces core library to allow users to create their own components. PrimeFaces Extensions consists of newly added components that don't exist in other JSF 2 based libraries as well as extended or improved component features missing in other popular JSF 2 libraries. Besides these components, it provides useful client behaviors, converters, validators, and other useful tools, such as a Maven plugin, for web resource optimization. It only uses standards and is highly compatible with existing JSF 2 frameworks.

Even though the earlier versions of component development with PrimeFaces started with the YUI API, in just a few days after getting negative results, the PrimeFaces team opted to go with the popular JavaScript framework jQuery to create their widgets and plugins. Because jQuery creates amazing widgets, custom plugins, themes, and Ajax-interactive features, considering these benefits, the PrimeFaces Extensions team also uses the jQuery framework behind the scenes to create its widgets. Hence, it is used instead of other JavaScript / UI frameworks available on the market.

The PrimeFaces Extensions library is a community-driven, open source project. This project has been licensed under Apache License Version 2 just as with many other open source projects, including the PrimeFaces library. You can use this library completely free for any open source or commercial project by following the terms and conditions of the Apache License Version 2.

PrimeFaces Extensions provides the following set of features as an extension UI component suite to the PrimeFaces core library:

More than 20 UI components
Support for common utility components, client behaviors, converters, and optimization tools, such as the Maven resource optimizer plugin
Built-in Ajax support using jQuery widgets
Zero configuration and no third-party library dependencies for majority components
Theme support to all components
Multibrowser support (IE8+, Chrome, Firefox, Safari, and Opera)

Installing and configuring PrimeFaces Extensions

The PrimeFaces Extensions library comes with a single JAR and does not require any mandatory third-party libraries. To use the PrimeFaces Extensions library in any web projects, just make sure to add the compatible PrimeFaces library and any JavaServer Faces implementations, such as Oracle Mojarra or Apache MyFaces.

At the time of writing this book, the latest version of PrimeFaces Extensions is 1.2.1, which is compatible with PrimeFaces 4.0.

Official releases

You can download the PrimeFaces Extensions library either manually or through a Maven download from the Maven central repository.

The Maven coordinates for the PrimeFaces Extensions library are as follows:

    <dependency>
      <groupId>org.primefaces.extensions</groupId>
      <artifactId>primefaces-extensions</artifactId>
      <version>1.2.1</version>
    </dependency>

Tip

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

All the projects or source code for this book are available in the GitHub repository. You can download it from the following link:

https://github.com/sudheerj/Learning-Primefaces-Extension-Development

Snapshot releases

If you are interested in using snapshot releases in your web project in order to get newly added components that do not exist in the recent major release or bug fixes, then add the Sonatype snapshot repository to your project configurations.

PrimeFaces Extensions uses the CloudBees platform and Jenkins as its continuous integration tool. It builds the PrimeFaces Extensions project resources on a daily basis.

Note

The snapshot releases are not recommended to be used in the applications directly because they are currently in the development stage due to possible bugs and are not production-ready.

Maven users should configure the following repository in the project's pom.xml file:

<repositories>
  <repository>
    <id>sonatype-oss-public</id>
    <url>https://oss.sonatype.org/content/groups/public/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

If you are not a Maven user, then download the PrimeFaces Extensions distribution directly from the following URL:

https://oss.sonatype.org/content/groups/public/org/primefaces/extensions/

Mandatory dependencies

Apart from the PrimeFaces Extensions library, we need to add the compatible PrimeFaces core library, apache.commons.lang3, and any JavaServer Faces implementations, such as Oracle's Mojarra or MyFaces.

In the following table, there is a list of mandatory dependencies to use the PrimeFaces Extensions library in your project:

Dependency	Version	Description
JSF Runtime	2.0, 2.1, or 2.2	Apache MyFaces or Oracle's Mojarra
PrimeFaces	4.0	The PrimeFaces library
apache.commons.lang3	3.1	Provides extra methods for the manipulation of its core classes

Based on the PrimeFaces Extensions library version, you have to add the compatible JSF and PrimeFaces versions.

Note

The dependency for PrimeFaces is defined as a transitive dependency, so there is no need to include it explicitly. But it is also possible to exclude the PrimeFaces core transitive dependency with the help of the dependencyManagement tag so that you can use other versions apart from the one defined by this transitive dependency.

Proceed with the following usage of the dependencyManagement tag to exclude the transitive dependency and use the other versions of PrimeFaces:

<dependencyManagement>  
    <dependency>
        <groupId>org.primefaces.extensions</groupId>
        <artifactId>primefaces-extensions</artifactId>
        <version>1.2.1</version>
    </dependency>
    <dependency>
        <groupId>org.primefaces</groupId>
        <artifactId>primefaces</artifactId>
        <version>4.0</version>
    </dependency>
</dependencyManagement>

Optional dependencies

Based on the PrimeFaces Extensions library's features that you want to use, you may need to use some third-party libraries. The following table describes the list of optional dependencies needed to use any particular feature:

Dependency	Version	Description
CKEditor	1.2.1	To use the CKEditor component.
CodeMirror	1.2.1	To use the CodeMirror component.
IText	2.1.7	Exporter (PDF).
Apache POI	3.9	Exporter (Excel).
Gson	2.2.4	To use the layout, timeline, and jsonConverter components. For Maven users, this library is available as a transitive dependency.

The list of maven coordinates for the preceding optional dependencies is shown as follows:

  <dependency>
      <groupId>org.primefaces.extensions</groupId>
      <artifactId>resources-ckeditor</artifactId>
      <version>1.2.1</version>
  </dependency>
  <dependency>
      <groupId>org.primefaces.extensions</groupId>
      <artifactId>resources-codemirror</artifactId>
      <version>1.2.1</version>
  </dependency>
  <dependency>
      <groupId>com.lowagie</groupId>
      <artifactId>itext</artifactId>
      <version>2.1.7</version>
  </dependency> 
  <dependency>
      <groupId>org.apache.poi</groupId>
      <artifactId>poi</artifactId>
      <version>3.9</version>
  </dependency>
  <dependency>
      <groupId>org.apache.poi</groupId>
      <artifactId>poi-ooxml</artifactId>
      <version>3.9</version>
  </dependency>

Note

Please refer to the JobHub application's pom.xml file in GitHub for the preceding configuration's details.

If you are using the iText library in your project, then don't forget to add the following exclusions in your iText Maven dependency (these APIs are not required for the PDF Exporter component):

  <exclusions>
  <exclusion>
      <groupId>bouncycastle</groupId>
      <artifactId>bcprov-jdk14</artifactId>
  </exclusion>
  <exclusion>
      <groupId>bouncycastle</groupId>
      <artifactId>bcmail-jdk14</artifactId>
  </exclusion>
  <exclusion>
      <groupId>org.bouncycastle</groupId>
      <artifactId>bctsp-jdk14</artifactId>
  </exclusion>
  </exclusions>

The following section shows the steps to install and configure PrimeFaces Extensions to your project. It has been split up into instructions for Maven users and non-Maven users.

If you are a Maven user, perform the following steps:

Add the following PrimeFaces Extensions library's Maven dependency to your pom.xml file; it will download the library from the Maven central repository as follows:

  <dependency>
      <groupId>org.primefaces.extensions</groupId>
      <artifactId>primefaces-extensions</artifactId>
      <version>1.2.1</version>
  </dependency>

Add the following PrimeFaces core Maven dependency to your pom.xml file; it will be downloaded to the library from the Maven central repository as follows:
```
  <dependency>
      <groupId>org.primefaces</groupId>
      <artifactId>primefaces</artifactId>
      <version>4.0</version>
  </dependency>
```
For the projects using lower versions of the PrimeFaces library, you have to add the PrimeFaces Maven repository to the repository list in pom.xml as follows:
```
  <repository>
      <id>prime-repo</id>
      <name>Prime Repo</name>
      <url>http://repository.primefaces.org</url>
  </repository>
```
The PrimeFaces core dependency is optional for Maven users because the PrimeFaces Extensions library has transitive dependency for the PrimeFaces core. This step is only required when you are going to use other PrimeFaces versions over the default PrimeFaces transitive dependency with the help of the dependencyManagement tag.

Configure the following code for either of the JSF dependencies in your project's pom.xml file:

  <dependency>
      <groupId>com.sun.faces</groupId>
      <artifactId>jsf-impl</artifactId>
      <version>2.2.4</version>
      <scope>compile</scope>
  </dependency>

The following is an equivalent block of code:

  <dependency>
      <groupId>org.apache.myfaces.core</groupId>
      <artifactId>myfaces-impl</artifactId>
      <version>2.2</version>
      <scope>compile</scope>
  </dependency>

If you are a non-Maven user, perform the following steps:

Download the PrimeFaces Extensions 1.2.1 library from the Maven central repository and add it to the classpath.
Download PrimeFaces-4.0.jar from http://www.primefaces.org/downloads.html and add it to the classpath.
Download either the Oracle Mojarra or Apache MyFaces JSF implementation from their official site and add it to the classpath.
Download the optional dependencies, such as POI, iText, CKEditor, and CodeMirror, and add them to the classpath based on your application requirement.

Creating a HelloWorld application using PrimeFaces Extensions

After installing and configuring the PrimeFaces Extensions environment, we have to add the PrimeFaces Extensions xmlns:pe="http://primefaces.org/ui/extensions" namespace in the web page to work with the extension components. You should have at least one PF Extensions component on the XHTML page, otherwise the core JavaScript with the namespace PrimeFacesExt will not be loaded.

Let us create a simple HelloWorld application to make sure PrimeFaces Extensions has been installed and configured properly.

First, we will create the layout.xhtml page, which will render the HelloWorld message in the center pane of the layout component as shown in the following code (this layout can be used to maintain the templating mechanism of the web pages):

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:f="http://java.sun.com/jsf/core"
      xmlns:h="http://java.sun.com/jsf/html"
      xmlns:ui="http://java.sun.com/jsf/facelets"
      xmlns:pe="http://primefaces.org/ui/extensions">
<f:view contentType="text/html" locale="en">
    <pe:head title="PrimeFaces Extensions HelloWorld" shortcutIcon="#{request.contextPath}/favicon.ico">
        <f:facet name="first">
            <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
            <meta http-equiv="pragma" content="no-cache"/>
            <meta http-equiv="cache-control" content="no-cache"/>
            <meta http-equiv="expires" content="0"/>
        </f:facet>
    </pe:head>
    <h:body>
        <pe:layout resizerTip="Resize Me" togglerTipClosed="Open Me" togglerTipOpen="Close Me">
            <pe:layoutPane position="north">
                North Block
            </pe:layoutPane>
            <pe:layoutPane position="east">
                East Block
            </pe:layoutPane>
            <pe:layoutPane position="center">
                <h1>Hello, Welcome to Primefaces Extensions world</h1>
            </pe:layoutPane>
            <pe:layoutPane position="west" size="200">  
                West Block
            </pe:layoutPane>
            <pe:layoutPane position="south">
                 South Block
            </pe:layoutPane>
        </pe:layout>
    </h:body>  
</f:view>
</html>

In the code section, we used pe:head instead of the standard JSF h:head. There is not much difference between these two tags, but pe:head only provides two additional properties named title and shortcutIcon.

Just build and run the HelloWorld application using Maven as your build tool. Then make a request to the browser using the following URL path:

http://localhost:8080/helloworld/layout.jsf

After you have made the browser request, you should see something like the following screenshot:

Now, the application will render or output the helloworld greeting message in the layout component.

Working with PrimeFaces Extensions project resources

You can also build the PrimeFaces Extensions project resources directly from the source repositories. First, you need to clone all the PrimeFaces project resources as follows:

git clone git://github.com/primefaces-extensions/master-pom.git
git clone git://github.com/primefaces-extensions/core.git
git clone git://github.com/primefaces-extensions/resources-ckeditor.git
git clone git://github.com/primefaces-extensions/resources-codemirror.git
git clone git://github.com/primefaces-extensions/showcase.git

The master-pom project should be built first as it contains the required dependencies for all the PrimeFaces Extensions projects. So, we have to build the projects in the order they are cloned in. All the projects are compiled and installed in the local repository with the help of the mvn clean install command.

Now, we can run the showcase on the Jetty 8 server for both the implementations as follows:

The Maven run command for Oracle Mojarra showcase is as follows:
```
mvn jetty:run
```
The Maven run command for Apache MyFaces showcase is as follows:
```
mvn jetty:run -Pmyfaces
```

Access the PrimeFaces Extensions showcase components through the following localhost URL:

http://localhost:8080/primeext-showcase/

Community support and a showcase for PrimeFaces Extensions

PrimeFaces Extensions has its own active forum, just like the PrimeFaces core, to discuss all the questions related to this Extensions library. Apart from this, the Extensions team provides an Issue Tracker for bug fixes and new component features to track or resolve these bugs for future releases. The PrimeFaces Extensions team accepts suggestions and patches in the form of pull requests.

The extensive documentation and examples of the PrimeFaces Extensions components and their features are available through the common showcase. The showcase has been deployed on the Jetty8 server for both the current JSF implementations—Mojarra and MyFaces.

Visit the following URLs to get help with PrimeFaces Extensions components and their features:

Home page: http://primefaces-extensions.github.io/
Forum URL: http://forum.primefaces.org/viewforum.php?f=14
Showcase URL: http://www.primefaces.org/showcase-ext/views/home.jsf
GitHub repositories: https://github.com/primefaces-extensions/
Issue Tracker: https://github.com/primefaces-extensions/primefaces-extensions.github.com/issues

Summary

In this chapter, you were introduced to the PrimeFaces Extensions library and its popular features. You also learned about installing and configuring the PrimeFaces Extensions suite, creating a simple HelloWorld application with a simple layout example, and working with PrimeFaces project resources.

In the next chapter, we will take a look at the form and editor components components of the PrimeFaces Extensions library, along with an introduction to a simple application named the JobHub application. The introduction to the JobHub application will then be used as our base to build upon in each chapter until we have finished acquiring knowledge on all the Extensions components and their features to create an enhanced PrimeFaces application.