Skip to content

Tutorial02

Jump to bottom
Vítor E. Silva Souza edited this page Apr 18, 2022 · 8 revisions

JButler has moved!

The new version of JButler is now hosted at Labes/UFES and there is a new tutorial as well. This repository contains an older version, if you're interested.

JButler Tutorial, Part 02: apply a ready-to-use layout

Before we actually develop features in our Web application, we will apply a ready-to-use layout to our webpages. In this tutorial, we will use AdminFaces, an open source project that integrates the PrimeFaces UI Suite for JSF, the Bootstrap HTML/CSS/JavaScript component library and the Admin LTE responsive Web template.

Here's how we can use it:

  1. Open pom.xml and add the following dependencies under the <dependencies></dependencies> tag (this tells Maven to obtain AdminFaces from the online repository):

    <dependency>
    <groupId>com.github.adminfaces</groupId>
    <artifactId>admin-template</artifactId>
    <version>1.1.0</version>
</dependency>

  2. Save pom.xml and check that the dependencies have been included in Java Resources/Libraries/Maven Dependencies;

  3. Open Deployed Resources/webapp/WEB-INF/web.xml and add the following under the <web-app></web-app> tag (this adds a default welcome file and some useful configuration that will be explained later):

    <welcome-file-list>
    <welcome-file>index.xhtml</welcome-file>
</welcome-file-list>
<context-param>
    <param-name>primefaces.FONT_AWESOME</param-name>
    <param-value>true</param-value>
</context-param>
<context-param>
    <param-name>primefaces.THEME</param-name>
    <param-value>admin</param-value>
</context-param>
<context-param>
	<param-name>javax.faces.PROJECT_STAGE</param-name>
	<param-value>Development</param-value>
</context-param>
<context-param>
	<param-name>javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL</param-name>
	<param-value>true</param-value>
</context-param>
<context-param>
	<param-name>javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE</param-name>
	<param-value>true</param-value>
</context-param>
<filter>
	<filter-name>Character Encoding Filter</filter-name>
	<filter-class>org.omnifaces.filter.CharacterEncodingFilter</filter-class>
</filter>
<filter-mapping>
	<filter-name>Character Encoding Filter</filter-name>
	<servlet-name>Faces Servlet</servlet-name>
</filter-mapping>
<context-param>
	<param-name>com.sun.faces.allowTextChildren</param-name>
	<param-value>true</param-value>
</context-param>
<session-config>
	<session-timeout>30</session-timeout>
</session-config>

  4. Based on the Admin Faces documentation, create the template file Deployed Resources/webapp/WEB-INF/templates/template.xhtml:

    <?xml version="1.0" encoding="UTF-8"?>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:p="http://primefaces.org/ui" template="/admin.xhtml">

    <ui:define name="head">
        <title>Oldenburg Workshop Simulator</title>
    </ui:define>

    <ui:define name="logo-lg">
        Oldenburg
    </ui:define>

    <ui:define name="logo-mini">
        OWS
    </ui:define>

    <ui:define name="menu">
        <ul class="sidebar-menu">
            <li><p:link outcome="/index" onclick="clearBreadCrumbs()">
                    <i class="fa fa-home"></i>
                    <span>Home</span>
                </p:link></li>
            <li class="header">Header</li>
            <li><p:link outcome="/index" onclick="clearBreadCrumbs()">
                    <i class="fa fa-calendar"></i>
                    <span>Blank Link</span>
                </p:link></li>
        </ul>
    </ui:define>

    <ui:define name="top-menu">

    </ui:define>

    <ui:define name="footer">
        Developed by <a href="http://www.inf.ufes.br/~vitorsouza/">Prof. Vítor E. Silva Souza</a>
        for <a href="http://informatica.ufes.br/">PPGI/UFES</a>
        <div class="pull-right hidden-xs" style="color: gray"><i>1.0.0</i></div>
    </ui:define>
</ui:composition>

  5. Then the home page Deployed Resources/webapp/index.xhtml:

    <?xml version="1.0" encoding="UTF-8"?>
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
    xmlns:ui="http://java.sun.com/jsf/facelets"
    xmlns:f="http://java.sun.com/jsf/core"
    xmlns:h="http://java.sun.com/jsf/html"
    xmlns:p="http://primefaces.org/ui"
    xmlns:adm="http://github.com/adminfaces"
    template="/WEB-INF/templates/template.xhtml">

    <ui:define name="title">
        Home
    </ui:define>

    <ui:define name="description">
        Welcome to Oldenburg, the Workshop Simulator
    </ui:define>

    <ui:define name="body">
        <p>This Web application allows professors teaching teaching Research Methodology courses to simulate a workshop 
        in which the students will submit papers and perform peer review.</p>
        
        <p>The application is named after <a href="https://en.wikipedia.org/wiki/Henry_Oldenburg">Henry
            Oldenburg</a> which, according to Wikipedia, is the creator of scientific peer review.</p>
    </ui:define>
</ui:composition>

  6. Finally, under Java Resources/src/main/resources/, create an empty file called admin-config.properties. It's the configuration file for Admin Faces and it used to be required for it to work (didn't check this for the latest version of AdminFaces, but it's a good idea to have this file, in case you want to change any configuration). If you can't find the Java Resources/src folder, right-click on the src/main folder and create a New > Folder called resources. Then right-click on the newly-created folder and select Build Path > Use as source folder.

Deploy the Web application again and check out your home page with a responsive layout (try resizing the browser window!).

The web.xml configuration explained

The steps above included many context parameters and a filter in the web.xml file in order to configure our Web application. If you're interested, here's what they mean/do:

  • primefaces.FONT_AWESOME = true: this activates the usage of Font Awesome by PrimeFaces, so we can place icons on buttons, links, menus, etc.;

  • primefaces.THEME = admin: this selects the Admin Faces theme for PrimeFaces, so the UI components have the same look & feel as the general template;

  • javax.faces.PROJECT_STAGE = Development: when under development, error messages are more informative, but at the cost of performance. When you're ready to put your WIS under production, change it to Production to emphasize performance and have some of those error messages turned off. See this blog;

  • javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL = true: does exactly what is says, sending null values to String parameters when their respective form fields are empty. This is required for Bean Validation to enforce the @NotNull validation for Strings;

  • javax.faces.DATETIMECONVERTER_DEFAULT_TIMEZONE_IS_SYSTEM_TIMEZONE = true: this changes the default time zone of JSF date/time converters from UTC to the time zone of the machine that runs the application server. In practice, this solves a bug that adjusts all date/time values you send to such converters to UTC before setting them at their destination objects, which depending on where you are in the World might not be a good thing! For instance, in Brazil the converters subtract 3 hours and all dates end up being saved as the day before (for when you want just the date, the time part is sent as 00:00);

  • The org.omnifaces.filter.CharacterEncodingFilter filter: this is a Servlet filter that forces Unicode (UTF-8) character encoding to all requests. It's implemented by OmniFaces, which is one of Admin Faces's transitive dependencies (therefore, already included in the project by Maven);

  • com.sun.faces.allowTextChildren = true: this configuration allows children of <h:inputText /> and <h:outputText /> to be rendered in JSF 2.0. It's required by PrimeFaces 2.x. Checking if this is still required is on our TO-DO list.

Next: internationalize the application

Clone this wiki locally