MVCPortlet^TM User Guide Documentation

Current release of MVCPortlet provides ActionProcessor and RenderProcessor implementations that perform database operations used in a typical data-driven application. In future we will add the ability to work with Java Beans and Enterprise Java Beans. In any case, larger applications should have their own business objects that implement the model independent of any external framework. In such cases, the processor classes would simply delegate the real work to these business objects.

Association between request type and a processor is defined in portlet-config.xml file typically located at the top level in the portlet base directory. In addition, users can specify a form attached to a action request type along with validators for validating user input. If configured properly, MVCPortlet can generate Javascript code for client side validation and also perform server side validation.

Processors return a logical name indicating the result of their execution. The configuration file maps the names to actual paths that are used to generate the display. This helps in separating the view generation from your processor classes.

4.2.1. RenderConfig Lookup

ControllerPortlet looks up the RenderConfig for the request type within the current portlet mode. Note that a RenderConfig object corresponds to a request type AND the portlet mode. The portlet mode is specified via "portletMode" attribute of "render-type" element in portlet configuration file. If ControllerPortlet cannot find a RenderConfig, it throws PortletException.

4.2.2. Permission Check

4.2.3. Navigation Path Manipulation

4.2.4. Pre-Processing

4.2.5. Business Logic Execution

4.2.6. View Generation

4.3.1. ActionConfig Lookup

ControllerPortlet looks up the ActionConfig for the request type within the current portlet mode. Note that a ActionConfig object corresponds to a request type AND the portlet mode. The portlet mode is specified via "portletMode" attribute of "action-type" element in portlet configuration file. If ControllerPortlet cannot find a ActionConfig, it throws PortletException.

4.3.2. Permission Check

4.3.3. Pre-Processing

4.3.4. Render Parameter Setup

You can turn parameter transfer off by setting "setRenderParameters" attribute of "action-type" element to "false". This behavior is also turned off if you specify a "redirect" "processor-result-mapping" for this action. This is necessary since JSR 168 standard prohibits setting render parameters if processAction results in a request redirect.

4.3.5. Form Validation

4.3.6. Business Logic Excecution

5.1.1. Configuration

  <forms>
    <form name="category">
      <field name="cat_id" />
      <field name="cat_title" validators="required,maxNameLength" />
      <field name="cat_rank" validators="int" default="0" />
    </form>
    <form name="question">
      <field name="cat_id" />
      <field name="q_id" />
      <field name="q_title" validators="required,maxNameLength" />
      <field name="q_answer" validators="required,maxDescrLength" />
      <field name="q_rank" validators="int" default="0" />
    </form>
  </forms>

  <validators>
    <validator name="required"
      class="com.nabhinc.portlet.mvcportlet.validator.RequiredValidator" />
    <validator name="int"
      class="com.nabhinc.portlet.mvcportlet.validator.IntegerValidator" />
    <validator name="maxNameLength"
      class="com.nabhinc.portlet.mvcportlet.validator.MaxLengthValidator"
      maxLength="100" />
    <validator name="maxDescrLength"
     class="com.nabhinc.portlet.mvcportlet.validator.MaxLengthValidator"
      maxLength="4000" />
  </validators>

Each validator has a name used to identify the validator in the form. A "validator" element also has a "class" attribute which is used create an instance of that validator. It may have additional attributes and sub-elements. Please refer to JavaDoc documentation of validator classes for the details.

The last component in validation configuration is the association between action types and forms. This is done via the "form" attribute of "action-type" as shown in the following fragment:

    <action-type name="CreateCategory" form="category" preCondition="admin" >
      <processor-result-mapping key="success" value="AdminIndex" message="faq.create_category_success_message" />
      <processor-result-mapping key="cancel" value="AdminIndex" />
      <processor-result-mapping key="validation-error" value="CreateCategory" />
    </action-type>
    

5.1.2. Validation Process

• It sets the render parameter "mvcportlet.form_error_message<portlet mode>" is to string "mvcportlet.form_error_message", where <portlet mode> is the portlet mode (e.g., edit, view, etc.).
• It sets the portlet session attribute "mvcportlet.form_errors" to a "FormErrors" object. This object allows looking up "FormError" objects representing all validation errors detected during validation. Each "FormError" object provides the name of the invalid form field and the validator name. The display JSPs can make use of this information in displaying the errors to the user.
• Finally, Controller portlet looks up the action corresponding to "validation-error" result string and executes it.

5.2.1. Javascript Configuration

<javascript-mappings>
  <javascript-mapping class="common">
    <javascript><![CDATA[
                // whitespace characters
  :
  :
  ]]>
    </javascript>
  </javascript-mapping>
  <javascript-mapping class="com.nabhinc.portlet.mvcportlet.validator.RequiredValidator"
        methodName="validateRequired">
    <javascript><![CDATA[
        function validateRequired (theField) {
  :
  :
  ]]>
    </javascript>
  </javascript-mapping>

</javascript-mapping>

As seen in the above XML fragment, the file specifies a mapping between a validator class and client side validation Javascript code. A special keyword "common" (which is not really a class) is used to indicate common Javascript functions that need to be included with any class.

5.2.2. Validation Process

<mp:form name="category" validationMethod="validateCreateCategory">
  <input type="hidden" name="request_type" value="CreateCategory" />
<tr>
  <td class="portlet-font"><b><mp:formLabel key="faq.title_label" name="cat_title" /></b></td>
  <td class="portlet-font"><mp:input name="cat_title" /></td>
</tr>
  :
  :

</mp:form>

• It writes all Javascript corresponding to the class "common".
• It collects a set of all validators associated with the specified form, looks up javascript functions associated with each class and writes them to the output.
• The form validation function is dynamically generated such that it invokes one validation funtion corresponding to a validator function associated with the form. The function name is retrieved from the configuration. Function argument list is constructed by invoking "getJavascriptFunctionArgs" method on the validator.

var bCancel = false;
function validateCreateCategory(form) {
    var elem;
    var errs=0;
    var errorMsg = "";
    if (bCancel) {
       return true;
    } else {
        if (!validateRequired(form.elements["cat_title"])) {
            errs += 1;
            errorMsg += "Category title cannot be blank.";
            errorMsg += "\n";
        }
        else if (!validateMaxLength(form.elements["cat_title"], 100)) {
            errs += 1;
            errorMsg += "Category title cannot be more than 100 characters.";
            errorMsg += "\n";
        }
        if (!validateInteger(form.elements["cat_rank"])) {
            errs += 1;
            errorMsg += "Category rank must be a number.";
            errorMsg += "\n";
        }
    }
    if (errs > 0) {
        alert(errorMsg);
        return false;
    } else {
        return true;
    }
}