FormView use case

FormView is enable to update HTML generated by JSP to add, replace new HTML content, in order to manage state (CREATE, UPDATE, READ...) of form and fields characteristics (DATE, MAXLENGTH, REQUIRED). With FormView you can :

• render fields of form according to state by developing just ONE JSP.
• render fields of form according to fields characteristics (Date, Required, Maxlength) by developing just ONE JSP.
• customize HTML render which you want generate according to state and fields characteristics.
• manage your HTML field swith user role. In according to user role, some HTML fields can be READ-ONLY, READ-WRITE, INVISIBLE....
• test your HTML rendered without WEB Application. You can develop class FormViewTest and test HTML rendered with simple HTML String.

To use FormView in your WEB application, you must follow three steps :

• step 1 : Configure FormView with XML form-view file. It consist to describe :
  • all states that you want use. See section XML States description.
  • all displayers that you want use. Displayers are used for update HTML according to HTML element (input, select, radio...). See section XML Displayers description
  • manage each fields of form :
    • manage fields characteristics and default behaviour.
    • manage fields behaviour for each states.
    • manage fields behaviour in according to user role. See section Manage role.
• step 2 : Initialize FormView with Struts or without Struts :
• step 3 : Use FormView with Struts or without Struts :

Configure FormView

Configure FormView consist to describes states, displayers, fields characteristcs and fields states into XML Form view file. A state is associated with a behaviour. A behaviour is the mode of your form. By default, FormView has three behaviours :

• READ-WRITE behaviour to display field with READ-WRITE (eg : input type="text").
• READ-ONLY behaviour to display field with READ-ONLY (eg : input type="text" readonly="readonly" ).
• INVISIBLE behaviour to NOT display field.

You can manage behaviour for fields with different level :

• global behaviour level : all your fields of your form will have the behaviour of state. You are not forced to define behaviour for each fields. See section XML States description
• form behaviour level : you define a behaviour for fields that you want fix a behaviour. So state of form was ignored while HTML render. This case is usable when you want that several fields depends on with sate (not define behaviour for this fields), and fix a behaviour for particular field. (For instance, when you want that this particular field is READ-ONLY whatever form state). See section XML Form description.
• field behaviour level : you define several states in your form and for each state, you define the behaviour of your field. See section XML Form description.

  ....
        <!-- Describe CRU (CREATE, READ and UPDATE) states and INVISIBLE state -->
        <states>
                <state name="CREATE" behaviour="READ-WRITE" />
                <state name="READ" behaviour="READ-ONLY" />
                <state name="UPDATE" behaviour="READ-WRITE" />
                <state name="INVISIBLE" behaviour="INVISIBLE" />
        </states>
  ....

<?xml version="1.0" encoding="UTF-8"?>
<form-view>
        <!-- Describe CRU (CREATE, READ and UPDATE) states and INVISIBLE state -->
        <states>
                <state name="CREATE" behaviour="READ-WRITE" />
                <state name="READ" behaviour="READ-ONLY" />
                <state name="UPDATE" behaviour="READ-WRITE" />
                <state name="INVISIBLE" behaviour="INVISIBLE" />
        </states>
        
        <!-- Form with name of path (see mapping.getPath() Struts) -->
        <form name="/project" >
                <!-- developersName field is READ-ONLY whatever the form state -->
                <field property="developersName" behaviour="READ-ONLY" />
                <state name="READ" >
                        <!-- buttonSave field is INVISIBLE when form state is READ -->
                        <field property="buttonSave" behaviour="INVISIBLE" />
                        ... Other Field configuration for the state READ
                </state>        
        </form> 
        
</form-view>  

Initialize FormView

Initialize FormView consist to :

• Register form-view.xml to use.
• Register validation.xml to use, if you want use information about Struts Validator.
• Register displayers-config.xml to use, if you want customize displayers.

If you use FormView with Struts, use FormView Plugin into struts-config, like this :

      <!-- FormView Plugin -->
      <plug-in className="net.sourceforge.formview.struts.plugin.FormViewPlugIn">
              <set-property property="formViewConfig" value="/WEB-INF/form-view.xml"/>
              <set-property property="validatorConfig" value="/WEB-INF/validation.xml"/>
              <set-property property="displayerConfig" value="/WEB-INF/displayers-config.xml"/>
      </plug-in>  

It's possible to split your form view config to several files, Here an example of config, wich use two XML config file form-view1.xml and form-view2.xml :

      <!-- FormView Plugin -->
      <plug-in className="net.sourceforge.formview.struts.plugin.FormViewPlugIn">
              <set-property property="formViewConfig" value="/WEB-INF/form-view1.xml,/WEB-INF/form-view2.xml"/>
              ....
      </plug-in>  

Use FormView

Using FormView consist to :

• add formview:page taglib between JSP content which me be managed by FormView :

    <%@ taglib uri="/WEB-INF/form-view.tld" prefix="formview" %>
    ...
    
    <formview:page>
      <html:form action="/project" >
        <html:text property="projectName" />
        <html:text property="projectDate" />
        <html:select property="managerId" >      
          <html:options collection="managerList" property="id" labelProperty="name"/>
        </html:select>
      </html:form> 
     </formview:page>     

  Pay attention to not forget to insert tld.

• implement your Action for manage state and form. To do that, you can :
  • use WEBFormViewUtil class in your Action :

      public final ActionForward loadRead(ActionMapping mapping, ActionForm form,
                            HttpServletRequest request, HttpServletResponse response)
                            throws Exception {
        // Set state to CREATE
        WEBFormViewUtil.saveState(request, getServlet().getServletContext(), FormViewConstants.STATE_READ);
        // Save characteristics fields of form 
        WEBFormViewUtil.saveFormView(request, getServlet().getServletContext(), mapping.getPath());
        return mapping.getInputForward();
      } 

  • OR implement load and display dispatch of class FormViewDispatchAction and after call ActionForward loadRead to set state to read, loadCreate to set state to create and loadUpdate to set state to update.

It is possible to manage field in your action with method saveFieldView of WEBFormViewUtil. For instance, You have list of fields (with the same name) and with behaviour=READ-ONLY. If you want that one field with particular index, was READ-WRITE, you can do it, like this :

    Integer index = new Integer(1); 

    // Save state and formview
    WEBFormViewUtil.saveState(request, getServlet().getServletContext(), FormViewConstants.STATE_UPDATE);
    WEBFormViewUtil.saveFormView(request, getServlet().getServletContext(), mapping.getPath());
    
    // Set field name=developersName with index=index to READ-WRITE
    // And Save it into request
    FieldView fieldView = new FieldView("developersName");
    fieldView.setIndex(index);
    fieldView.setBehaviour(FormViewConstants.BEHAVIOUR_READWRITE);
    WEBFormViewUtil.saveFieldView(request, getServlet().getServletContext(),  mapping.getPath(), fieldView);