Sarah Miller
off
on

Layout Template

Apollo utilizes JSF templating APIs and provides a main template.xhtml along with additional topbar, menu and footer fragments for the base layout. These xhtml files must be placed under WEB-INF folder and client pages should reference the template.xhtml as their template. Provided empty.xhtml is a sample content page using the main template.xhtml that defines "content" as the main ui:define placeholder. By default template defines 4 placeholders (page title, head content, breadcrumb path and actual content) to insert content and you can add more per your requirements.

<h:body>
    
    <div class="layout-wrapper layout-#{guestPreferences.layoutMode}">
        
        <ui:include src="topbar.xhtml" />
        <ui:include src="menu.xhtml" />
        
        <div class="layout-content">
            <div class="layout-breadcrumb">
                <ul>
                    <li>
                        <p:link outcome="/dashboard">
                            <i class="fa fa-home" />
                        </p:link>
                    </li>
                    <li>/</li>
                    <ui:insert name="breadcrumb" />
                </ul>
                
                <div class="layout-breadcrumb-options">
                    <a href="#" title="Backup"><i class="fa fa-cloud-upload"></i></a>
                    <a href="#" title="Bookmark"><i class="fa fa-bookmark"></i></a>
                    <a href="#" title="Logout"><i class="fa fa-sign-out"></i></a>
                </div>
            </div>
            
            <div class="layout-content-container">
                <ui:insert name="content"/>
            </div>
        </div>
        
        <ui:include src="footer.xhtml" />
        
        <div class="layout-mask"></div>
    </div>
</h:body>

Sample page below uses the main template from Apollo.

<ui:composition xmlns="http://www.w3.org/1999/xhtml"
                xmlns:h="http://java.sun.com/jsf/html"
                xmlns:f="http://java.sun.com/jsf/core"
                xmlns:ui="http://java.sun.com/jsf/facelets"
                xmlns:p="http://primefaces.org/ui"
                template="/WEB-INF/template.xhtml">
                
    <ui:define name="title">Test Page</ui:define>

    <ui:define name="content">
        Content goes here
    </ui:define>
</ui:composition>

Other required resources of the layout are the css, js and images that are located inside resources/apollo-layout folder, simply copy the apollo-layout folder to your %WEB-APP-FOLDER%/resources folder so that final path would be %WEB-APP-FOLDER%/resources/apollo-layout/. Please refer to demo app or maven project of the demo app as the reference.

GuestPreferences Bean

GuestPreferences is a simple session scoped bean to keep the user customizations of the layout and template xhtml files refer to this bean to dynamically change their behavior such as menu mode or theme. This bean is not necessary to run the Apollo and only used for demo purposes however in your application we suggest using a similar bean so that each user can define their own UI experience by customizing the layout. For example template.xhtml includes layout color depending on a user preference using an EL expression.

<h:outputStylesheet name="css/layout-#{guestPreferences.theme}.css" library="apollo-layout" />   

In your application, you may also need a similar bean to make the template dynamic or choose a static color with;

<h:outputStylesheet name="css/layout-blue.css" library="apollo-layout" />   

Source code of GuestPreferences.

package org.primefaces.apollo.view;

import java.io.Serializable;
import javax.faces.bean.ManagedBean;
import javax.faces.bean.SessionScoped;

@ManagedBean
@SessionScoped
public class GuestPreferences implements Serializable {
    
    private String color = "blue";
    
    private boolean dark = false;
        
    private String layoutMode = "horizontal";

	public void updateTheme(String color, boolean dark) {
		this.color = color;
        this.dark = dark;
	}
    
    public String getTheme() {
        return this.color + "-" + (this.dark ? "dark" : "light");
    }
    
    public void changeScheme() {
        this.dark = !this.dark;
        this.updateTheme(this.color, this.dark);
    }
        
    public String getLayoutMode() {
        return this.layoutMode;
    }
    
    public void setLayoutMode(String value) {
        this.layoutMode = value;
    }
    
    public boolean isDark() {
        return this.dark;
    }
    
    public void setDark(boolean value) {
        this.dark = dark;
    }
}

Theme

Apollo provides 16 PrimeFaces themes out of the box, setup of a theme simple as including the theme jar in your classpath and defining primefaces.THEME context parameter in web.xml such as "apollo-blue-light". Full list of available themes are;

  • apollo-blue-light
  • apollo-blue-dark
  • apollo-cyan-light
  • apollo-cyan-dark
  • apollo-green-light
  • apollo-green-dark
  • apollo-indigo-light
  • apollo-indigo-dark
  • apollo-orange-light
  • apollo-orange-dark
  • apollo-pink-light
  • apollo-pink-dark
  • apollo-purple-light
  • apollo-purple-dark
  • apollo-yellow-light
  • apollo-yellow-dark

A custom theme can be developed by the following steps.

  • Create a custom theme folder such as primefaces-apollo-myown-light under webapp/resources and place an empty theme.scss inside.
  • Copy the sass folder from the distribution to webapp/resources.
  • Define the variables listed below and import the /sass/theme/_theme.scss file.
  • Build the scss to generate css.
  • Set primefaces.THEME context parameter as apollo-myown
  • Either bundle the css in a jar file or serve from webapp/resources/primefaces-apollo-myown folder

Here are the variables required to create a theme.

$primaryColor: #7E57C2;
$primaryTextColor: #ffffff;

@import '../sass/theme/_theme_light.scss';

If you are building a dark theme, import the _theme_dark.scss instead of _theme_light.scss so dark version would be;

$primaryColor: #7E57C2;
$primaryTextColor: #ffffff;

@import '../sass/theme/_theme_dark.scss';

An example sass command to compile the css would be;

sass src/main/webapp/resources/primefaces-apollo-myown-light/theme.scss src/main/webapp/resources/primefaces-apollo-myown-light/theme.css  --sourcemap=none

Watch mode is handy to avoid compiling everytime when a change is made, instead use the following command so that sass generates the file whenever you make a customization. This builds all css files whenever a change is made to any scss file.

sass -w src/main/webapp/resources/ --sourcemap=none

Layout

Layout customization is similar to theme method.

  • Choose a layout name such as layout-myown.
  • Create an empty file named layout-myown.scss inside resources/apollo-layout/css folder.
  • Copy the sass folder from the distribution to webapp/resources.
  • Define the variables listed below and import the /sass/layout/_layout.scss file.
  • Build the scss to generate css
  • Serve the css by importing it using a link tag or h:outputStylesheet.

Here are the variables required to create a layout.

$primaryColor:#39a3f4;
$primaryTextColor:#ffffff;
$menuBgColor:#ffffff;
$menuitemTextColor:#424242;
$submenuActiveBgColor:#ffffff;
$menuItemHoverTextColor:#39a3f4;
$menuItemActiveTextColor:#39a3f4;

$bodyBgColor:#EEF2F6;
$textColor:#424242;
$textSecondaryColor:#7a7a7a;
$placeholderColor:#a0a0a0;
$dividerColor:#dddddd;

@import '../../sass/layout/_layout.scss';

SASS Variables

In case you'd like to customize common variables, the _common.scss under sass variables folder is where the core variables (e.g. font size, paddings) for the layout are defined.

$fontFamily:"Source Sans Pro",Arial,sans-serif;
$fontSize:14px;
$borderRadius:2px;
$transitionDuration:.3s;

/* Predefined Colors */
$blue:#39a3f4;
$green:#6ebc3b;
$purple:#7E57C2;
$cyan:#26C6DA;
$pink:#EC407A;
$indigo:#5C6BC0;
$orange:#f6a821;
$yellow:#ffc800;
$red:#EF5350;
$white:#ffffff;
$black:#000000;

_theme.scss files contains the shared variables of the PrimeFaces theme, there are two versions this file, one is for light themes and other is for dark themes. Here is the dark version;

@import './common';

$textColor:#d8d8d8;
$textSecondaryColor:#acacac;
$dividerColor:#121213;

/* Icons */
$iconFontSize:13px;
$iconWidth:16px;

/* Error */
$errorColor:#EF5350;

/* Header */
$headerPadding:6px 12px;
$headerBgColor:#1b3548;
$headerBorderColor:#121213;
$headerTextColor:#9fadb7;
$headerHoverBgColor:#485d6c;
$headerHoverTextColor:#ffffff;
$headerIconColor:#9fadb7;
$headerIconHoverColor:#ffffff;

/* Contents */
$contentPadding:6px 12px;
$contentBorderColor:#121213;
$contentBgColor:#1c2937;

/* Forms */
$inputBgColor:#141e27;
$inputPadding:6px;
$inputBorderColor:#121213;
$inputHoverBorderColor:$primaryColor;

/* Buttons */
$toggleButtonBgColor:#323e4b;

/* List Items */
$listItemPadding:6px 12px;

/* Messages */
$infoMessageBgColor:#39A3F4;
$infoMessageTextColor:#ffffff;
$warnMessageBgColor:#FFC800;
$warnMessageTextColor:#141d26;
$errorMessageBgColor:#EF5350;
$errorMessageTextColor:#ffffff;
$fatalMessageBgColor:#E73E51;
$fatalMessageTextColor:#ffffff;

/* Data */
$datatableCellBorderColor:#121213;
$datableEvenRowBgColor:#15222F;

/* TabView */
$tabHeaderPadding:8px 12px;

/* Menus */
$menuBgColor:#243447;

Menu

Menu is a regular JSF component that supports PrimeFaces MenuModel API allowing both declarative and programmatic approaches.

xmlns:pa="http://primefaces.org/apollo"

<pa:menu>
</pa:menu>

Menu has 4 modes; static, overlay, horizontal and slim. Layout wrapper element in template.xhtml is used to define which mode to use by adding specific classes.

  • "layout-wrapper layout-static": Static Menu
  • "layout-wrapper layout-overlay": Overlay Menu
  • "layout-wrapper layout-slim": Slim Menu
  • "layout-wrapper layout-horizontal": Horizontal Menu

Layout mode can be dynamic using an EL expression as well using an example bean called userPreferences.

<div class="layout-wrapper #{userPreferences.layout}">
...
</div>

Icons

Apollo Layout uses font awesome icons for layout so enable font awesome support in PrimeFaces by setting primefaces.FONT_AWESOME context parameter in web.xml as true. If your PrimeFaces version does not have the font awesome integration, include the font-awesome manually in your application.

Card

Card is a section to group content and layout provides a built-in css for it. Apply .card style class to your container to use it. If the card has a title defined with h1 tag, add card-w-title to adjust paddings.

<div class="card">
    Content here
</div>

<div class="card card-w-title">
    <h1>Card with Title<h1>
    Content here
</div>

Grid CSS

Apollo uses new PrimeFaces Grid CSS (ui-g-*) throughout the samples, we strongly suggest using Grid CSS as your layout framework as it is well tested and supported by PrimeFaces. Grid CSS is automatically included on newer versions however if your PrimeFaces version is older than 5.3.14, add the provided grid.css file under /apollo-layout/css/ folder to your template manually.

Tips

  • Familiarity with SASS is required to make customizations to the layout and theme.
  • Demo application war and the maven project tag are included in distribution however you don't necessarily need them to install Apollo, the actual artifacts required are the layout zip file and the theme jar.
  • Sample demo application war includes the JSF libraries so it is suggested to remove them from the war file when you deploy to an appserver.
  • When running the maven project, you need to build the sass with (sass --update src/main/webapp/resources/ --sourcemap=none) command.