Skip to content

Styling

Themes

When you have chosen a template for your web application, you can fine tune the appearance of your web application by choosing a so-called ‘theme’. Themes determine things like colors and fonts. The available themes depend on the chosen template. PrimeFaces provides premium and community themes.

Normally, the theme is statically configured in a web-fragment.xml or web.xml file. PrimeFaces comes with functionality to dynamically determine a theme at runtime. This functionality is made use of in the generated web applications, in the web-fragment.xml file of the runtime components:

<context-param>
    <param-name>primefaces.THEME</param-name>
    <param-value>#{layoutCustomizationBean.themeDynamically}</param-value>
</context-param>

The Developer Support section describes how you can use the developer bar to dynamically switch themes in order to be able to quickly find out what theme suites your customer best.

All web applications use a common set of CSS files that define the look of the applications. The set of CSS files depends on the template being chosen. The following table shows the relationship between the chosen template and the set of CSS files being used. The principal mechanism is to include an XHTML file in the template file by means of <ui:include>. That XHTML file in turn uses the <h:outputStylesheet> tag. This mechanism allows you to adapt styles in three ways:

  • make changes to .css files in your web application project
  • make changes in the default XHTML files in your web project
  • use different XHTML files and implement String getStylesheet(String key, Template template) in AppLayoutCustomization.java.

All mentioned CSS files are located under the folder resources/css.

Template DESKTOP

Note

Please note that we do not enourage you to use the template DESKTOP. DESKTOP is deprecated since it uses PrimeFaces <p:layout> which itself is deprecated.

XHTML File CSS Files
/template/stylesheet-empty.xhtml empty-style.css
/template/stylesheet-common.xhtml common-style.css
/template/stylesheet-application.xhtml application-style.css

Template RESPONSIVE

XHTML File CSS Files
/template/stylesheet-empty.xhtml empty-style.css
/template/stylesheet-grid.xhtml grid-style.css
/template/responsive/stylesheet-common.xhtml custom-repsonsive-style.css
/template/responsive/stylesheet-application.xhtml responsive-application-style.css

Template PRIMEFACES CALIFORNIA

XHTML File CSS Files
/template/stylesheet-empty.xhtml empty-style.css
/template/stylesheet-grid.xhtml grid-style.css
/template/primefaces/california/custom-stylesheet.xhtml custom-responsive-style.css
/template/primefaces/california/stylesheet-application.xhtml responsive-application-style.css

In AppLayoutCustomizationBean.java (generated for the web application component) there is a method String getStylesheet(String key, Template template) that allows you to change the names of the XHTML files to be used. This is the mapping of keys to XHTML files:

XHTML File Key
/template/stylesheet-empty.xhtml template.stylesheet.empty
/template/stylesheet-grid.xhtml template.stylesheet.grid
/template/stylesheet-common.xhtml template.stylesheet.common
/template/stylesheet-application.xhtml template.stylesheet.application
/template/responsive/stylesheet-common.xhtml template.stylesheet.responsive.common
/template/responsive/stylesheet-application.xhtml template.stylesheet.responsive.application
/template/primefaces/california/custom-stylesheet.xhtml template.stylesheet.primefaces.california
/template/primefaces/california/stylesheet-application.xhtml template.stylesheet.primefaces.california.application

There are enumerations provided for templates (LayoutCustomizationBean.Template) and stylesheets (LayoutCustomizationBean.Stylesheet). This code snippet shows an implementation of getStylesheet() that completeley disables the usage of certain XHTML files by replacing them with an empty stylesheet:

public String getStylesheet(String key, LayoutCustomizationBean.Template template) {
    String result = null;
    Stylesheet stylesheet = LayoutCustomizationBean.Stylesheet.get(key);

    if (stylesheet != null) {
        switch (stylesheet) {
        case APPLICATION:
            if (template == Template.PRIMEFACES_CALIFORNIA) {
                result = Stylesheet.EMPTY.getDefaultFile();
            }
            break;
        case COMMON:
            if (template == Template.PRIMEFACES_CALIFORNIA) {
                result = Stylesheet.EMPTY.getDefaultFile();
            }
            break;
        case EMPTY:
            break;
        default:
            break;
        }
    }

    return result;
}

You can style web pages in many different ways: color, margin, padding, font, widths, heights, just to name a few. Web pages created with the JSF generators lets you provide a default styling that is defined in the common web fragment component. That styling is applied to all web pages. You can completely customize/overwrite this styling by css files that you add to a web application component. The following table shows the files that are created by the JSF generators and that are related to css styling.

Generator File, Class Description
Web Fragment [layout-name]_generated.xhtml
[layout-Name]Bean.java
[layout‑Name]BeanExtendedCustomization.java
With these beans and XHTML files, individual styles can be added to a specific page and inline styles can be set for individual XHTML tags.
Web Application stylesheet-application.xhtml
application-style.css
Styles can be added here, that are to be used for one single web application only.
Web Application AppLayoutCustomizationBean.java This bean provides a means to dynamically add styling to all web pages by reading the styling information from external resources.

Apply your own Styles by modifying generated Files

The following table shows you how you can style your web pages by writing Java or XHTML code. The order of the entries has a significance: Any styling further down in the table overwrites styles being defined further above.

File, Class, Method Description
AppLayoutCustomizationBean.java
String getStyles()
The styling information that is going to be returned by this method is applied to all web pages by adding them to the page’s style tag in the web page <head> section. The styles overwrite styles in commons-style.css and application-style.css. The purpose of this mechanism is to be able to dynamically get additional style information from an external resource like for instance a database or a web service.
AppLayoutCustomizationBean.java
String getStylesheet(String key, Template template)
This method allows you to overwrite the names of XHTML files to be used to provide styling configuration through CSS files. The XHTML files that are nominated by the returned string include entries like this:
<h:outputStylesheet library="css" name="abc.css"/>.
From here one, the styles being defined are inline styles that are specific to the given page only.
[layout-Name]Bean.java
String getPageStyles()
You can let this method dynamically return styling information that is going to be applied to this page only, by adding the styling information to the <style> tag in the page’s <header> section. Note that this method will not be called again when AJAX calls are being made for the page. By design the <head>section of a web page cannot be handled by a partial update.
[layout-name]_generated.xhtml Inline styles are set here, e.g. directly through the style attribute and indirectly through the styleClass attribute.
[layout-Name]BeanExtendedCustomization.java In this bean you find several inner classes, one per modeled display that is used within a modeled layout. Each of these classes has methods for some of an XHTML tag’s attributes. Amongst them are methods like
String getHinweisPanelGrid_style(); to provide the style information for the style attribute of the UI component HinweisPanelGrid.
App[layout‑Name]BeanExtendedCustomization.java By default this generated class is empty. In the JavaDoc of this class you find information on what has to be manually implemented in this class in order to customize the default functionality in
[layout-Name]BeanExtendedCustomization.java.

Guidelines for Styling

The styling mechanism allows you to customize virtually everything. However, for your day-to-day work you only need a minor subset of that functionality.

Styling ALL pages, for ALL Web Application

To change the standard styling for all pages in all web applications you have to change the content of the common CSS files. These CSS files are located in the common web fragment component.

Styling an INDIVIDUAL Page, for ALL Web Applications

  • Make changes in [layout-name]_generated.xhtml, [layout-Name]BeanExtendedCustomization.java and [layout-Name]Bean.java (getPageStyle()) to change the standard style of a web page.
  • limit the number of changes in [layout-name]_generated.xhtml, wherever possible, use [layout-Name]BeanExtendedCustomization.java instead

Styling ALL pages, for a SINGLE Web Application

  • Add styles to the file application-style.css that got generated for a web application project.
  • If you want to use another, seperate CSS file in your web application project, add it to the /webapp/resources directory, where you can also find the file application-style.css. You then need to configure that file in the developer area in the generated file /webapp/template/stylesheet-application.xhtml.

Styling an INDIVIDUAL Page, for a SINGLE Web Application

You can add HTML tag specific styles in application-style.css with the help of CSS selectors that use the ids of HTML tags. Apart from that you can also add Java code to App[layout‑Name]BeanExtendedCustomization.java to directly add styles to the style attribute of XHTML tags. To use the file application-style.css normally is the easier way to make such changes since you don’t need to write any Java code and you can simply copy & paste the styles that you tried out with the developer tools of your web browser. App[layout‑Name]BeanExtendedCustomization.java is rather being used for the customization of attributes of XHTML tags. Those are not only for styles but also for attributes that have a different purpose, e.g. to display a <p:calendar> component with or without a button next to it or to define the year range for the date selection.