Getting Started

• Dependencies
• Maven users
• Other users
• Build from source
• Prerequisites
• Clone and run it
• Using in facelets
• Configuration
• Compressed vs. uncompressed resources

Dependencies

Maven users

No extra repositories are needed to be configured in pom.xml. PrimeFaces Extensions project is available in the Maven Central repository. The last released version can be determined by searching in the Maven Central repository. Add this dependency to your pom.xml.

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

Dependency to the PrimeFaces is defined as a transitive dependency, so that there isn't need to include it explicitly. But make sure that you have the PrimeFaces repository in your pom.xml as described here if you use an old version of PrimeFaces.

It is also possible to exclude the transitive dependency to the PrimeFaces core project and use another version than version defined by this transitive dependency. This can be done with dependencyManagement tag. Example:

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

To see current project's dependency tree, execute this Maven command in the project's root folder.

mvn dependency:tree

If you plan to use CKEditor component, add necessary dependencies to CKEditor's resources please.

<dependency>
    <groupId>org.primefaces.extensions</groupId>
    <artifactId>resources-ckeditor</artifactId>
    <version>8.0</version>
</dependency>

Such resources are placed in separate JAR files because they are really big and optional. We have decided to keep the core JAR file for PrimeFaces Extensions lightweight.

For the Exporter component, the following additional dependencies are required.Also we need to add few exclusions which are not required for PDF Exporter.

<dependency>
    <groupId>com.github.librepdf</groupId>
    <artifactId>openpdf</artifactId>
    <version>1.3.14</version>
</dependency>
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>4.1.2</version>
</dependency>
<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>4.1.2</version>
</dependency>

For the InputPhone component, the following additional dependencies are required.

<dependency>
    <groupId>com.googlecode.libphonenumber</groupId>
    <artifactId>libphonenumber</artifactId>
    <version>8.12.1</version>
</dependency>

Other users

• Add current PrimeFaces JAR file to your project from this download section.
• Add the last PrimeFaces Extensions JAR file to your project from the Maven Central repository.
• Add Apache Commons Lang3 to your project if it's not in classpath.
• Add Gson JAR file to your project from the Gson homepage (optional).
• Add the last JAR file for CKEditor if you need from the Maven Central repository (optional).
• Add the last JAR file for CodeMirror if you need from the Maven Central repository (optional).
• Add Exporter dependencies Apache POI and iText if you use the Exporter component.

New snapshots and releases are uploaded to the public Sonatype's repository so that everybody can download them from there. Maven users should configure this repository in a project's pom.xml to be able to use SNAPSHOTs.

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

Build from source

Prerequisites

• Install Git as described in the Pro Git book.
• Install Maven 2 or 3 if you don't have it as this project is a Maven based project.

Clone and run it

All available repositories with sub-projects are listed on the start page. Open your console / terminal window and clone one or many repositories you need with

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/showcase.git

The master-pom (in the master-pom folder) should be built at first because it contains required dependencies across all sub-projects. After that every sub-project can be compiled and installed into local repository. Open your console / terminal window, go to the root folder of a project you need and type the following command

mvn install

Showcase is prepared to run with Jetty server. To run it with JSF Mojarra implementation, go to the cloned showcase project (in the showcase folder) and type in the console / terminal window

mvn jetty:run

To run it with JSF MyFaces implementation, type

mvn jetty:run -Pmyfaces

This starts Jetty server and the showcase is available under the following URL in a web browser:

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

Jetty will continue to run until you stop it with a <Ctrl+C> in the console / terminal window where it is running.

Using in facelets

Add the following namespace to your facelets pages.

xmlns:pe="http://primefaces.org/ui/extensions"

You are done. You can use PrimeFaces Extensions as follows:

<!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 - ShowCase">
        <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 options="#{layoutController.layoutOptions}">
            <pe:layoutPane position="north">
                <ui:insert name="header"/>
            </pe:layoutPane>
            <h:form>
                <ui:insert name="center"/>
                <pe:layoutPane position="south">
                    <ui:insert name="footer"/>
                </pe:layoutPane>
            </h:form>
        </pe:layout>
    </h:body>
</f:view>
</html>

Configuration

Compressed vs. uncompressed resources

Before 3.2.0 release

Resources (CSS, JavaScript files) in the delivered JAR files are compressed and uncompressed. PrimeFaces Extensions streams down compressed resources for the JSF ProjectStage "Production" and it streams down uncompressed resources for the ProjectStage "Development". This allows to debug resources and report issues more efficient. JSF ProjectStage can be configured in web.xml by context parameter javax.faces.PROJECT_STAGE. It's also possible to use compressed resources with the ProjectStage "Development". In this case you need to have a special configuration parameter in web.xml.

<context-param>
    <param-name>
        org.primefaces.extensions.DELIVER_UNCOMPRESSED_RESOURCES
    </param-name>
    <param-value>false</param-value>
</context-param>

Default value of the parameter org.primefaces.extensions.DELIVER_UNCOMPRESSED_RESOURCES is true.

Release 3.2.0 or higher

Uncompressed resources are not delivered within the JAR file anymore. We use the source map approach for debug purpose described on this page.