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 general styles in different ways:

make changes to .css files in your web application project
make changes in the XHTML file stylesheet-application.xhtml in your web application project to include different or additional .css files
use different XHTML files and implement String getStylesheet(String key, Template template) in AppLayoutCustomization.java.

All CSS files that are going to be mentioned in the following are located under the folder resources/css in the runtime libs. application-style.css and responsive-application-style.css are empty in the runtime libs. Empty versions of these files, including a developer area, are getting generated in the web application component. Those generated .css files are picked up at runtime since they reside in the same subdirectory as the ones in the runtime libs.

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	[view-Name].css [view-name]_generated.xhtml [view-Name]Bean.java [view‑Name]BeanExtendedCustomization.java	With these CSS files, 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 responsive-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 (`getStyles()`) to dynamically add styling to all web pages by reading the styling information from external resources, e.g. from a web service.

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, application-style.css and responsive-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.
[view-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.
[view-name]_generated.xhtml	Inline styles are set here, e.g. directly through the `style` attribute and indirectly through the `styleClass` attribute.
[view-Name]BeanExtendedCustomization.java	In this bean you find several inner classes, one per modeled display that is used within a modeled view. 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[view‑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 [view-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 can change the content of the common CSS files. These CSS files are located in the runtime libs. You have to fork the runtime lib repository to be able to do this.

If you don’t want to fork the runtime libs repository to make such changes, you have to make changes in every web application project. See Styling ALL pages, for a SINGLE Web Application for more information.

Styling an INDIVIDUAL Page, for ALL Web Applications¶

Make changes in [view-name]_generated.xhtml, [view-Name]BeanExtendedCustomization.java or [view-Name]Bean.java (getPageStyle()) to change the style of a web page. Limit the number of changes in [view-name]_generated.xhtml. Wherever possible, use [view-Name]BeanExtendedCustomization.java instead.
Make changes in the developer area of [view-Name].css. That .css file is loaded in exactly one web page.

Styling ALL pages, for a SINGLE Web Application¶

Add styles to the file application-style.css or the file responsive-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 files application-style.css and responsive-application-style.css. You then need to configure that .css file in the developer area in the generated file stylesheet-application.xhtml.

Styling an INDIVIDUAL Page, for a SINGLE Web Application¶

You can add HTML tag specific styles in application-style.css or responsive-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[view‑Name]BeanExtendedCustomization.java to directly add styles to the style attribute of XHTML tags.

To use the file application-style.css or responsive-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[view‑Name]BeanExtendedCustomization.java is rather being used for the customization of attributes of XHTML tags, 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.