JSF 2 adds the <f:ajax> tag that is very useful for creating the rich, interactive forms that users expect to see in a modern web application. ICEfaces 2 leverages and improves this new functionality with the <icecore:singleSubmit> tag. Single Submit is a replacement for the partialSubmit attribute common in ICEfaces 1.8.x applications. By using Single Submit we can send only some of the fields in a form to the server for processing, which can be handy as we can dynamically modify the form based on what was sent. For example in-line validation can be fired, different fields can be rendered depending on what the user has selected, and so on.
This tutorial will deal with using the <icecore:singleSubmit> tag in a simple form page. This tutorial assumes the reader has an understanding of JSF and ICEfaces and creating and working with projects related to those technologies. The focus is not to teach those basics, but instead to use Single Submit.
The goal of this tutorial is to create a basic ICEfaces 2 project and add Single Submit. The example will be a single page form with a few input components to demonstrate how Single Submit works.
The following tools were used to create the project.
- Eclipse IDE for Java EE Developers - Version Helios
- Tomcat 7.x Web Server
- Java 6.x
- ICEfaces 2.0 Beta 2 with ICEpush
- Using Eclipse create a new Dynamic Web Project called singleSubmit.
- Target runtime: Apache Tomcat v7.0
- Dynamic web module version: 3.0
- Configuration: JavaServer Faces v2.0 Project (Mojarra)
Add the icefaces.jar to your project from the ICEfaces 2 bundle. This can be added to the project through a custom User Library or by putting it into singleSubmit/WEB-INF/lib/. The approach doesn't matter as long as the jar is included in the deployed war file.
Create a new page called form.xhtml and paste the code below. Currently no Single Submit is used, but will be added below in Step 6.
Although slightly verbose, the form.xhtml page is a standard JSF form with a table for displaying what the user entered into each field. A variety of input types and validation are used to help demonstrate Single Submit. The table allows a user to enter Name, Age, Gender, and Favorite Food, and then submit those values to the server.
Create a new Java class file called PersonBean in the package org.icefaces.tutorial.singlesubmit.beans and paste the code below:
This bean model is a collection of variables to back the fields on our page. The submitButton method will output what was submitted, but otherwise the class is simple.
Once the application is built and deployed and running it will look like this screenshot:
In terms of functionality a user having to populate the form may find it tedious because no validation hints happen until they click the "Submit" button. So they won't know what the valid Age range is, or if Name is required, and so on.
Adding Single Submit will remedy that by enriching the form with immediate submissions as a user completes each field.
Now that we have seen the traditional JSF approach of form submission, we'll add <icecore:singleSubmit> to our form and test the differences.
First add the icecore namespace to our form.xhtml page (in the <html> tag), as such:
This will grant us the ability to use Single Submit. To add Single Submit to a page we want to put the <icecore:singleSubmit> tag inside any form that requires rich submissions.
Inside the opening <h:form> tag in form.xhtml, paste the <icecore:singleSubmit> tag as such:
Now all of the fields inside that form (Name, Age, etc.) will be handled with ICEfaces Single Submit, instead of the standard JSF approach. This means when we leave a field (either by clicking out of it or by tabbing through the fields) only that field will be submitted and processed on the server.
So if a user leaves the Name field without entering a value, the required="true" validation will display a message immediately, instead of the user needing to click the "Submit" button first.
This is achieved because each form field acts as if it had a nested <f:ajax> tag with the execute="@this" attribute.
Re-build and re-deploy the application with the new Single Submit functionality. Now when a user interacts with the form the entire experience is smoother because of the instant in-line validation and single field submission.
|Single Submit project||singleSubmit source code||Basic example project demonstrating how Single Submit functions and can be integrated on an ICEfaces 2 page.|