Using Single Submit

Version 1 by Carlo Guglielmin
on Nov 26, 2010 15:33.


 
compared with
Current by Deryk Sinotte
on Mar 16, 2011 15:08.


 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 8 changes. View first change.

 h1. Using Single Submit Tutorial
  
 JSF 2.0 added the {{<f:ajax>}} tag that was very useful for creating the rich, interactive forms that users expect to see in a modern web application. ICEfaces 2.0 leverages and improves this new functionality with the {{<icecore:singleSubmit>}} tag. Single Submit is a replacement for the {{partialSubmit}} attribute common on 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.
  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.0 project and add Single Submit. The example will be a single page form with a few input components to demonstrate how Single Submit works.
  This tutorial assumes the reader has an understanding of JSF and ICEfaces. The goal of this tutorial is to create a basic ICEfaces 2 project and add Single Submit using the {{<icecore:singleSubmit>}} tag in a simple form page.
 \\
 \\
 ----
{panel}Here is the entire list of steps worked through during this tutorial:
  {panel}Steps in this tutorial:
  
# [Make the easyAjaxPush Project|#step1]
 # [Add ICEfaces and ICEpush|#step2]
 # [Create color.xhtml|#step3]
 # [Create MessageBean.java|#step4]
 # [Create ColorBean.java|#step5]
 # [Create TextModel.java|#step6]
 # [Deploy the Application|#step7]
 # [Adding Ajax Push|#step8]
 ** [ColorBean Setup|#step8a]
 ** [PushRenderer.addCurrentSession|#step8b]
 ** [PushRenderer.render|#step8c]
 # [Re-Deploy the Application|#step9]
  # [Make the singleSubmit Project|#step1]
 # [Add ICEfaces|#step2]
 # [Create form.xhtml|#step3]
 # [Create PersonBean.java|#step4]
 # [Deploy the Application|#step5]
 # [Add Single Submit|#step6]
 # [Re-Deploy the Application|#step7]
  
 * [Tutorial Source Code Downloads|#downloads]
 {panel}
 ----
 
 h3. Development Tools Used
  
 The following tools were used to create the project.
 * [Eclipse|http://eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/heliossr1] IDE for Java EE Developers - Version Helios
 * [Tomcat 7.x|http://tomcat.apache.org/download-70.cgi] Web Server
 * [Java 6.x|http://www.oracle.com/technetwork/java/javase/downloads/]
* [ICEfaces 2.0 Beta 2|http://www.icefaces.org/JForum/posts/list/17890.page] with ICEpush
  * ICEfaces 2
  
 h3. {anchor:step1}1. Make the {{singleSubmit}} Project
  
 * 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)
  
 h3. {anchor:step2}2. Add ICEfaces
  
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 {{windowScope/WEB-INF/lib/}}. The approach doesn't matter as long as the jar is included in the deployed {{war}} file.
  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.
  
 h3. {anchor:step3}3. Create {{form.xhtml}}
  
 Create a new page called {{form.xhtml}} and paste the code below:
  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.
  
 {code:title=form.xhtml}<!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:h="http://java.sun.com/jsf/html"
  xmlns:f="http://java.sun.com/jsf/core">
 <h:head>
  <title>Single Submit - Form</title>
 </h:head>
 <h:body>
  <h:form>
  <h:panelGrid columns="3">
  <h:outputLabel for="name" value="Name:"/>
  <h:inputText id="name" value="#{personBean.name}" required="true" maxlength="50"/>
  <h:message for="name"/>
  
  <h:outputLabel for="age" value="Age:"/>
  <h:inputText id="age" value="#{personBean.age}" required="true"
  size="2" maxlength="2">
  <f:validateLongRange minimum="1" maximum="99"/>
  </h:inputText>
  <h:message for="age"/>
  
  <h:outputLabel for="gender" value="Gender:"/>
  <h:selectOneMenu id="gender" value="#{personBean.gender}" required="true">
  <f:selectItem noSelectionOption="true" itemValue="" itemLabel="--Select--"/>
  <f:selectItem itemValue="Male"/>
  <f:selectItem itemValue="Female"/>
  </h:selectOneMenu>
  <h:message for="gender"/>
  
  <h:outputLabel for="favorite" value="Favorite Food:"/>
  <h:inputText id="favorite" value="#{personBean.favorite}" maxlength="225"/>
  <h:message for="favorite"/>
  </h:panelGrid>
  
  <h:commandButton value="Submit" actionListener="#{personBean.submitButton}"/>
  </h:form>
  
  <br/>
  
  <h:panelGrid columns="2" border="1">
  <f:facet name="header">
  Person Information
  </f:facet>
  
  <h:outputLabel for="nameOut" value="Name:"/>
  <h:outputText id="nameOut" value="#{personBean.name}"/>
  
  <h:outputLabel for="ageOut" value="Age:"/>
  <h:outputText id="ageOut" value="#{personBean.age}"/>
  
  <h:outputLabel for="genderOut" value="Gender:"/>
  <h:outputText id="genderOut" value="#{personBean.gender}"/>
  
  <h:outputLabel for="favoriteOut" value="Favorite:"/>
  <h:outputText id="favoriteOut" value="#{personBean.favorite}"/>
  </h:panelGrid>
 </h:body>
 </html>
 {code}
 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.
  
 h3. {anchor:step4}4. Create {{PersonBean.java}}
  
 Create a new Java class file called {{PersonBean}} in the package {{org.icefaces.tutorial.singlesubmit.beans}} and paste the code below:
  
 {code:title=PersonBean.java}package org.icefaces.tutorial.singlesubmit.beans;
  
 import java.io.Serializable;
 import java.util.Date;
  
 import javax.faces.bean.ManagedBean;
 import javax.faces.bean.ViewScoped;
 import javax.faces.event.ActionEvent;
  
 @ManagedBean(name="personBean")
 @ViewScoped
 public class PersonBean implements Serializable {
  private String name;
  private int age;
  private String gender;
  private String favorite;
  
  public PersonBean() {
  }
  
  public String getName() {
  return name;
  }
  public void setName(String name) {
  this.name = name;
  }
  public int getAge() {
  return age;
  }
  public void setAge(int age) {
  this.age = age;
  }
  public String getGender() {
  return gender;
  }
  public void setGender(String gender) {
  this.gender = gender;
  }
  public String getFavorite() {
  return favorite;
  }
  public void setFavorite(String favorite) {
  this.favorite = favorite;
  }
  
  public void submitButton(ActionEvent event) {
  System.out.println("Submit Clicked: " + name + ", " + age + ", " + gender + ", " + favorite);
  }
 }
 {code}
 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.
  
 h3. {anchor:step5}5. Deploy the Application
  
 Once the application is running it will look like this screenshot:
 !singlesubmit-tutorial-screenshot.png!
  
 The user experience with this form could be tedious because validation is not performed until they click the "Submit" button. The user will not know what the valid Age range is, if Name is required, and so on, until the entire form is submitted.
 Adding Single Submit will enrich the form with immediate feedback as a user visits each field.
  
 h3. {anchor:step6}6. Add Single Submit
  
 Now that we have seen the traditional approach to 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):
  
 {code:title=Adding Namespace}<html xmlns="http://www.w3.org/1999/xhtml"
  xmlns:h="http://java.sun.com/jsf/html"
  xmlns:f="http://java.sun.com/jsf/core"
  xmlns:icecore="http://www.icefaces.org/icefaces/core">
 ...
 {code}
 This will grant us the ability to use Single Submit. To use Single Submit in a page we 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. Ensure the tag is self terminating and not used as a container for the rest of the components in the form:
  
 {code:title=Adding Tag}...
 <h:body>
  <h:form>
  <icecore:singleSubmit/>
  <h:panelGrid columns="3">
  ...
 {code}
 Now all of the fields inside that form (Name, Age, etc.) will be handled with ICEfaces Single Submit. 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.
 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.
  
 h3. {anchor:step7}7. Re-Deploy the Application
  
 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.
  
 ----
 h3. {anchor:downloads}Tutorial Source Code Downloads
  
 || Example || Source || Notes ||
 | Single Submit project | [singleSubmit source code |^singleSubmit.zip|Download Source Code] | Basic example project demonstrating how Single Submit functions and can be integrated on an ICEfaces 2 page. |

© Copyright 2018 ICEsoft Technologies Canada Corp.