Get Started

Overview

PrimeFaces Designer API is SASS based theme engine for creating PrimeFaces themes easily.

SASS Installation

Designer requires SASS to be installed at the command line, refer to the SASS documentation for installing instructions.

Designer Application

This demo application featuring various components is created to test your components while designing your theme. It is a maven application with a built-in jetty server so to run the application locally, extract the contents of the designer zip file and run the following command.

mvn clean jetty:run

Then navigate to http://localhost:8080/designer to access the application in your local environment, now it is time to create your own theme.

Create Your Own Theme

A built-in base theme named "primefaces-mytheme" is available to get started with your own theme using 500+ variables. To begin with navigate to the src/main/webapp/resources/primefaces-mytheme folder that includes the following artifacts;

  • /fonts: Folder of the font files
  • _fonts.scss: Definition of the @font-face of the theme
  • _variables.scss: List of variables to create your own theme
  • _extensions.scss: Customizations to the theme
  • theme.scss: Main theme file that imports the scss files required for the theme

A theme.css file needs to be generated whenever a file imported by the theme.scss is changed, this is done by the following SASS command.

sass --update src/main/webapp/resources/

Watch mode is handy so that sass listens to your changes and generates the css automatically.

sass -w src/main/webapp/resources/

You may now start designing your own theme by changing the variables such as $primaryColor, once the theme.css file is generated, use the components menu at the sidebar to view your theme.

Video Tutorial

A video tutorial is available to demonstrate how a theme can be created with the capabilities of the Designer API.

Customization

Designer API is located inside the resources/designer folder and an actual theme imports _fonts, _extensions, _variables and the main _core.scss from the designer folder. In case you need to make structural changes to the design system, add these changes to the _extensions.scss files instead of editing the .scss files inside the designer folder to avoid any maintenance issues. Designer is updated periodically for improvements and updating is done by replacing the designer folder only. For seamless updates, never edit the designer folder as _extensions.scss file is created for this purpose.

Font Family

Default font of the designer is "Open Sans" and it can be changed in three steps.

  • Placing the font artifacts such as eot, woff files inside the fonts.
  • Define the font-face and import the font files using the JSF resource el expression.
  • Change the $fontFamily at _variables.scss.

Following example uses Roboto font for the theme.

_fonts.scss 
/* roboto-300 - latin */
@font-face {
font-family: 'Roboto';
font-style: normal;
font-weight: 300;
src: url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-300.eot']}"); /* IE9 Compat Modes */
src: local('Roboto Light'), local('Roboto-Light'),
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-300.eot']}#iefix") format('embedded-opentype'), /* IE6-IE8 */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-300.woff2']}") format('woff2'), /* Super Modern Browsers */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-300.woff']}") format('woff'), /* Modern Browsers */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-300.ttf']}") format('truetype'), /* Safari, Android, iOS */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-300.svg']}#Roboto") format('svg'); /* Legacy iOS */
}

/* roboto-regular - latin */
@font-face {
font-family: 'Roboto';
font-style: normal;
font-weight: 400;
src: url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-regular.eot']}"); /* IE9 Compat Modes */
src: local('Roboto'), local('Roboto-Regular'),
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-regular.eot']}#iefix") format('embedded-opentype'), /* IE6-IE8 */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-regular.woff2']}") format('woff2'), /* Super Modern Browsers */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-regular.woff']}") format('woff'), /* Modern Browsers */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-regular.ttf']}") format('truetype'), /* Safari, Android, iOS */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-regular.svg']}#Roboto") format('svg'); /* Legacy iOS */
}

/* roboto-700 - latin */
@font-face {
font-family: 'Roboto';
font-style: normal;
font-weight: 700;
src: url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-700.eot']}"); /* IE9 Compat Modes */
src: local('Roboto Bold'), local('Roboto-Bold'),
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-700.eot']}#iefix") format('embedded-opentype'), /* IE6-IE8 */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-700.woff2']}") format('woff2'), /* Super Modern Browsers */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-700.woff']}") format('woff'), /* Modern Browsers */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-700.ttf']}") format('truetype'), /* Safari, Android, iOS */
    url("#{resource['primefaces-mytheme:fonts/roboto-v15-latin-700.svg']}#Roboto") format('svg'); /* Legacy iOS */
}
_variables.scss 
$fontFamily:"Roboto","Helvetica Neue",sans-serif;

Theme Size

Component sizes including the font-sizes, margins and paddings are defined using em units which allows changing the overall size, as a result changing the $fontSize variable is enough to scale the components. Default is 14px and example below creates a bigger theme based on a scale of 16px.

$fontSize:16px;

Build

Once the theme is ready for use, run the following maven command to generate a jar file to use in your actual application.

mvn clean install -P build

This command generates a file called primefaces-mytheme-{version}.jar under the target folder. You may now use this theme by including the jar file to the classpath of your application and configure it as your theme of choice with a context parameter.

<context-param>
    <param-name>primefaces.THEME</param-name>
    <param-value>mytheme</param-value>
</context-param>
Copyright 2009-2018 PrimeTek - All rights reserved