Java Platform, Enterprise Edition 7: Creating HTML5 Pages in JavaServer Faces 2.2

Overview

Purpose

This tutorial shows you how to convert a static HTML5 page into a dynamic JavaServer Faces (JSF) page with HTML5-friendly markup.

Time to Complete

Approximately 1 hour

Introduction

JSF is a presentation technology that allows developers to create pages with component-oriented design. The design reduces development time and increases interactivity of applications. HTML5 is the new standard for writing web pages. Modern web applications require collaboration between web developers and enterprise developers to achieve great design and usability. Java Platform, Enterprise Edition 7 (Java EE 7) with JSF 2.2 bridges the gap for web developers: They can integrate their web designs by using HTML5 in JSF pages. This tutorial shows the conversion steps of an HTML5 page to a JSF-enabled page.

Please note that the pages are viable solutions that can be used in an application. The goal of this tutorial is to show you the different versions that you can use in Java EE 7 with JSF 2.2, as follows:

A pure HTML5 solution using JavaScript for interactivity and dynamic data
An HTML5 page with JSF attributes that adds dynamic data to a pure HTML5 page
An HTML5 page with JSF components that will be rendered as HTML5 elements adding passthrough parameters for extended HTML5 properties
A JSF component-oriented page that uses HTML5 elements when necessary

Scenario

In this tutorial, you modify the sticker story web application developed in the previous tutorial (Using WebSocket for Real-Time communication in Java Platform, Enterprise Edition 7) to use JSF with HTML5-friendly markup.

Software Requirements

The following are the software requirements:

Download and install the Java 7 development kit: http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Download and install the Java NetBeans 7.3.1 integrated development environment (IDE) for Java EE development with GlassFish 4.0: https://netbeans.org/downloads/index.html.
(Optional) Download and install the GlassFish Server Open Source Edition 4.0: http://glassfish.java.net/download.html.

Prerequisites

Before starting this tutorial, you should:

Have knowledge of the Java programming language.
Have basic knowledge of Java EE (JSF) and HTML.
Have completed the tutorial entitled Using WebSocket for Real-Time Communication in Java Platform, Enterprise Edition 7. If you prefer, you can download the completed project here.

Setting Up the Project

In this section, you set up the project. If you completed the tutorial entitled Using WebSocket for Real-Time Communication in Java Platform, Enterprise Edition 7, use the same project and skip to step 8.

Download the sticker-story.zip project and unzip it.

Open NetBeans IDE 7.3.1 and select File > Open Project.

Browse to the location where you unzipped the sticker-story project, select it, and click Open Project.

Right click the project and select Clean and Build.

Select GlassFish Server from the Server list and click OK.

Open the application in your browser and test it by dragging stickers from the left side to the space image on the right. By default it is available at http://localhost:8080/sticker-story/.

Select the index.html file and press F2 to rename it stickers-1.

Right-click the project and select New > Other.

Select the Web category, select the HTML file type, and then click Next.

Name the new file index, leave the Folder field empty, and click Finish.

Copy the content of the following code sample in the index.html file. This is a simple index page that links to the sticker pages.

Note: Some links are broken. As you progress through this tutorial, rerun the application and test this link again.

index.html file

<!DOCTYPE html>
<html>
  <head>
    <title>Stickers</title>
    <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
  </head>
  <body>
    <ul>
      <li><a href="stickers-1.html">HTML5 only page</a></li>
      <li><a href="faces/stickers-2.xhtml">JSF-HTML5-friendly page</a></li>
      <li><a href="faces/stickers-3.xhtml">JSF with HTML5 elements</a></li>
      <li><a href="faces/stickers-4.xhtml">JSF page</a></li>
    </ul>
  </body>
</html>

The following code sample shows what your stickers-1.html page should look like. It is here for reference only.

stickers-1.html page

<!DOCTYPE html>
<html>
  <head>
    <title>Sticker Story</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <link href="resources/styles.css" rel="stylesheet" type="text/css"/>
    <script src="resources/story-page.js" type="text/javascript"></script>
  </head>
  <body>
    <header><h1>Sticker Story Book</h1></header>
    <nav>Drag sticker from the left bar to the canvas.</nav>
    <aside>
      <h2>Stickers</h2>
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="alien.png" src="resources/stickers/alien.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="asteroid.png" src="resources/stickers/asteroid.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="astronaut.png" src="resources/stickers/astronaut.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="moon.png" src="resources/stickers/moon.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="planet.png" src="resources/stickers/planet.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="robot.png" src="resources/stickers/robot.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="ship.png" src="resources/stickers/ship.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="spacegun.png" src="resources/stickers/spacegun.png">
      <img style="float:left;" draggable="true" ondragstart="drag(event);" data-sticker="star.png" src="resources/stickers/star.png">
    </aside>
    <div id="content">
      <canvas id="board" width="1000" height="580" ondragover="allowDrop(event);" ondrop="drop(event);">
        Canvas Not Supported use HTML5 friendly browser.
      </canvas>
      <img src="resources/canvas2.png" id="background_img" style="display:none;"/>
    </div>
    <footer>
      <small>Made with HTML5 + WebSockets and JSON</small>
      <ol>
        <li onclick="toggleLog();">Log</li>
      </ol>
    </footer>    
    <div id="logContainer">
      <h2>log</h2>
      <div id="log"></div>
    </div>
  </body>
</html>

This concludes application setup. The application is now ready to add JSF pages.

Creating an HTML5 JSF

In this section, you create the JSF configuration and the first JSF page that uses HTML5 code with JSF attributes. First, you create the backing bean for the JSF page. This bean lists all stickers in the application.

Right-click the org.sticker.websocket package and select New > Java Class.

Name the class StickerSheet, set the package to org.sticker.jsf, and click Finish.

In the following code sample, copy the highlighted code to the StickerSheet class:

StickerSheet class

package org.sticker.jsf;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;
import java.util.ListIterator;
import javax.enterprise.context.ApplicationScoped;
import javax.faces.context.FacesContext;
import javax.inject.Named;
import javax.servlet.ServletContext;

@Named("stickerSheet")
@ApplicationScoped
public class StickerSheet implements Serializable {

  public List<String> getAllStickers() {
    ServletContext ctx = (ServletContext) FacesContext.getCurrentInstance()
            .getExternalContext().getContext();
    final String stickerPath = "/resources/stickers/";
    List<String> allStickers = new ArrayList<>(ctx.getResourcePaths(stickerPath));

    for (ListIterator<String> listIterator = allStickers.listIterator(); listIterator.hasNext();) {
      String value = listIterator.next();
      value = value.substring(stickerPath.length(), value.length());
      listIterator.set(value);
    }

    return allStickers;
  }
}

Now you create the JSF page and the JSF configuration in the application.

Perform the following steps:

Right-click the project and select New > Other to open the New File dialog box.

On the File Type page, select Web from Categories.

Select JSF Page from File Types.

Click Next.

On the Name and Location page, perform the following steps:

Enter stickers-2 for the file name.

Leave the Folder field empty.

Under Options, select Facelets.

Click Finish.

Open the Web Pages > WEB-INF > web.xml file.

Remove the welcome-file-list and the session-timeout elements.

Your web.xml file should look like the following code sample:

web.xml file

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">
  <context-param>
    <param-name>javax.faces.PROJECT_STAGE</param-name>
    <param-value>Development</param-value>
  </context-param>
  <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>
</web-app>

Perform the following steps:

Open the stickers-1.html file.
Select the content of the file and copy it.

Paste the content inside the stickers-2.xhtml file.

Modify the <html> element to add the namespace declarations for JSF.

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
      xmlns:jsf="http://xmlns.jcp.org/jsf">

Add jsf:id to the head and body elements.

<head jsf:id="head">

<body jsf:id="body">

Modify the <script> and <link> elements in the head to use the jsf:target and jsf:name attributes to locate resources in your application.

<script jsf:target="body" jsf:name="story-page.js"/>
<link jsf:name="styles.css" rel="stylesheet" type="text/css" />

Perform the following steps:

Locate the <div id="stickerContainer"> element.
Remove all but one of its <img> elements.
Add a <ui:repeat> JSF element to iterate the stickers inside the backing bean.
Modify the <img> element to use the jsf:name attribute to locate resources and to use the Expression Language to get the properties from the bean.

<ui:repeat var="imgName" value="${stickerSheet.allStickers}">
  <img jsf:name="stickers/${imgName}" style="float:left" draggable="true" ondragstart="drag(event);" data-sticker="${imgName}" />
</ui:repeat>

The following code sample shows what the stickers-2.xhtml file should look like:

stickers-2.xhtml page

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
      xmlns:jsf="http://xmlns.jcp.org/jsf">
  <head jsf:id="head">
    <title>Sticker Story</title>
    <script jsf:target="body" jsf:name="story-page.js"/>
    <link jsf:name="styles.css" rel="stylesheet" type="text/css" />
  </head>
  <body jsf:id="body">
    <header>
      <h1>Sticker Story Book</h1>
    </header>
    <nav>
      Drag stickers from the left bar to the canvas.
    </nav>
    <aside>
      <h2>Stickers</h2>
      <div id="stickerContainer">
        <ui:repeat var="imgName" value="${stickerSheet.allStickers}">
          <img jsf:name="stickers/${imgName}" style="float:left" draggable="true" ondragstart="drag(event);" data-sticker="${imgName}" />
        </ui:repeat>
      </div>
    </aside>
    <div id="content">
      <canvas id="board" width="1000" height="580" ondrop="drop(event);"
              ondragover="allowDrop(event);">
        Canvas Not Supported.
      </canvas>
      <img src="resources/canvas2.png" id="background_img" style="display:none;"/>
    </div>
    <footer>
      <small>Made with JSF 2.2 + HTML5 + WebSockets and JSON</small>
      <ol>
        <li onclick="toggleLog();">Log</li>
      </ol>
    </footer>
    <div id="logContainer">
      <h2>log</h2>
      <div id="log"></div>
    </div>
  </body>
</html>

Rerun the application and test the pages. You should have the same design and functionality in the stickers-1 and stickers-2 pages.

As you can see, the stickers-2 page has HTML5 code with JSF attributes that give dynamic data. This situation is ideal if your web designer creates HTML5 pages, and you must add JSF functionality on top.

Creating a JSF with HTML Markup

In this section, you incorporate JSF components inside an HTML5 page to add JSF functionality. For simplicity, you will use the stickers-2 page as the base for the new page.

Select the stickers-2.xhtml file, right-click, and select Copy.

Select the Web Pages node, right-click, and select Paste.

Enter stickers-3 for the name of the newly created file.

Open the stickers-3.xhtml file.

Add the following namespace declarations to enable JSF components (h) and JSF passthrough parameters (p) in the <html> element.

xmlns:h="http://xmlns.jcp.org/jsf/html"
xmlns:p="http://xmlns.jcp.org/jsf/passthrough"

Replace the <img> element below the canvas element with an h:graphicImage element.

    <div id="content">
      <canvas id="board" width="1000" height="580" ondrop="drop(event);"
              ondragover="allowDrop(event);">
        Canvas Not Supported.
      </canvas>
      <h:graphicImage name="canvas2.png" id="background_img" style="display:none;"/>
    </div>

Replace the <img> element between the ui:repeat element.

        <ui:repeat var="imgName" value="${stickerSheet.allStickers}">
          <h:graphicImage name="stickers/${imgName}" style="float:left" 
                          p:draggable="true" p:ondragstart="drag(event);" p:data-sticker="${imgName}"/>
        </ui:repeat>

Note: Because the draggable, ondragstart, and data-sticker attributes are not available out of the box in the graphicImage component, you use passthrough attributes to provide these attributes.

The following code sample shows the final version of the stickers-3 page:

stickers-3.xhtml page

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
      xmlns:jsf="http://xmlns.jcp.org/jsf"
      xmlns:h="http://xmlns.jcp.org/jsf/html"
      xmlns:p="http://xmlns.jcp.org/jsf/passthrough">
  <head jsf:id="head">
    <title>Sticker Story</title>
    <script jsf:target="body" jsf:name="story-page.js"/>
    <link jsf:name="styles.css" rel="stylesheet" type="text/css" />
  </head>
  <body jsf:id="body">
    <header>
      <h1>Sticker Story Book</h1>
    </header>
    <nav>
      Drag stickers from the left bar to the canvas.
    </nav>
    <aside>
      <h2>Stickers</h2>
      <div id="stickerContainer">
        <ui:repeat var="imgName" value="${stickerSheet.allStickers}">
          <h:graphicImage name="stickers/${imgName}" style="float:left" 
                          p:draggable="true" p:ondragstart="drag(event);" p:data-sticker="${imgName}"/>
        </ui:repeat>
      </div>
    </aside>
    <div id="content">
      <canvas id="board" width="1000" height="580" ondrop="drop(event);"
              ondragover="allowDrop(event);">
        Canvas Not Supported.
      </canvas>
      <h:graphicImage name="canvas2.png" id="background_img" style="display:none;"/>
    </div>
    <footer>
      <small>Made with JSF 2.2 + HTML5 + WebSockets and JSON</small>
      <ol>
        <li onclick="toggleLog();">Log</li>
      </ol>
    </footer>
    <div id="logContainer">
      <h2>log</h2>
      <div id="log"></div>
    </div>
  </body>
</html>

Rerun the application and test the newly created page.

Creating a JSF Page

In this section, you modify the page again to use JSF components.

Paste a copy of the stickers-3.xhtml file in the Web Pages node and name it stickers-4.

Remove the jsf: namespace declaration.

xmlns:jsf="http://xmlns.jcp.org/jsf"

Replace the following HTML elements with their JSF counterparts:

Use the following code sample for reference. The tags to replace are highlighted.

stickers-4.xhtml page

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:ui="http://xmlns.jcp.org/jsf/facelets"
      xmlns:h="http://xmlns.jcp.org/jsf/html"
      xmlns:p="http://xmlns.jcp.org/jsf/passthrough">
  <h:head>
    <title>Sticker Story</title>
    <h:outputStylesheet name="styles.css"/>
    <h:outputScript name="story-page.js"/>
  </h:head>
  <h:body>
    <header>
      <h1>Sticker Story Book</h1>
    </header>
    <nav>
      Drag stickers from the left bar to the canvas.
    </nav>
    <aside>
      <h2>Stickers</h2>
      <h:panelGroup layout="block" id="stickerContainer">
        <ui:repeat var="imgName" value="#{stickerSheet.allStickers}">
          <h:graphicImage name="stickers/${imgName}" style="float:left" 
                          p:draggable="true" p:ondragstart="drag(event)" 
                          p:data-sticker="${imgName}" />
        </ui:repeat>
      </h:panelGroup>
    </aside>
    <h:panelGroup layout="block" id="content">
      <canvas id="board" width="1000" height="580" ondrop="drop(event)"
              ondragover="allowDrop(event)">
        Canvas Not Supported.
      </canvas>
      <h:graphicImage name="canvas2.png" id="background_img" style="display:none;"/>
    </h:panelGroup>
    <footer>
      <small>Made with JSF 2.2 + HTML5 + WebSockets and JSON</small>
      <ol>
        <li onclick="toggleLog();">Log</li>
      </ol>
    </footer>
    <div id="logContainer">
      <h2>log</h2>
      <h:panelGroup layout="block" id="log"/>
    </div>
  </h:body>
</html>

Rerun the application and test the newly created page.

Summary

In this tutorial, you learned how to:

Use JSF attributes in HTML pages
Use JSF components in HTML pages
Use JSF passthrough parameters to create HTML5 markup

Resources

The Java EE 7 tutorial
The JSF 2.2 specification
The Java EE documentation
The HTML5 specification
To learn more about Java EE 7, refer to additional OBEs in the Oracle Learning Library.

Credits

Lead Curriculum Developer: Eduardo Moranchel
Other Contributors:
- Edgar Martinez
- Miguel Salazar

To help navigate this Oracle by Example, note the following:

Hiding Header Buttons:: Click the Title to hide the buttons in the header. To show the buttons again, simply click the Title again.
Topic List Button:: A list of all the topics. Click one of the topics to navigate to that section.
Expand/Collapse All Topics:: To show/hide all the detail for all the sections. By default, all topics are collapsed
Show/Hide All Images:: To show/hide all the screenshots. By default, all images are displayed.
Print:: To print the content. The content currently displayed or hidden will be printed.

To navigate to a particular section in this tutorial, select the topic from the list.