Updating a page with a refresh request

The refresh type of AJAX request prompts the servlet to update the values of the controls in a specified area of the page. However, the refresh request does not update the variables in the JSF Handler to match the controls on the page. In this way, this type of request is intended to be modular and efficient.

With this type of request, you specify an area of the page to be updated, an event to trigger the request, and optionally any parameters to be passed along with the request. Then, you configure the JSF Handler's onPreRenderFunction to update the specified part of the page.

Follow these steps to add an AJAX refresh request to a web page. The following steps assume that you have a JSF Handler with variables bound to controls on a web page:
  1. On the web page, indicate the area of the page that you want to update with the AJAX request by creating a JSF panel control on the page.

    AJAX requests in EGL can update only the parts of the page within a JSF panel control. JSF panel controls serve mainly as containers and organizers for other JSF controls. The Panel - Group Box control, found in the Enhanced Faces Components drawer of the Palette view, is a good control to use because it is only a container and is not visible on the page.

  2. Set the ID attribute of the panel control to a value that is unique on the page. You will need to specify this ID in the AJAX request.
  3. Place the JSF controls that you want to update inside the panel control and make sure that the controls are bound to EGL variables.
    The code of the panel control might look like the following example. In this case, only a single output control is within the panel.
    <h:panelGrid id="updatablePanel" styleclass="panelGrid">
      <h:outputText id="textToUpdate" value="#{myPage.message}"
        binding="#{myPage.message_Ref}" styleClass="outputText" />
    </h:panelGrid>
  4. Set the ID attributes of any controls on the page that you want to pass as parameters in the request. These controls do not need to be within the panel control, but their ID attributes must be unique on the page, and they must be input controls.
  5. Specify the user event that will trigger the AJAX request.

    Do this by adding a JSF behavior to an input control on the page and then selecting an event to trigger the request. The control containing the behavior does not need to be within the panel control, but only input controls can trigger requests.

    For example, you can make the AJAX request occur when the user moves the focus into a particular control. In this case, you use the onFocus event. To perform the request when the user moves focus away from a particular control, you use the onBlur event. Other commonly used events include onClick, onMouseOver, and onSelect.

    1. On the web page, select the input control that you want to use as the trigger.
    2. With the control selected, open the Quick Edit view.
    3. In the Quick Edit view, select the event, such as onBlur, from the left side of the view.
    4. Select the Use pre-defined behavior check box.
    5. In the Action list, select Invoke Ajax behavior on the specified tag.
    6. In the Target list, select the ID of the panel you want to update.
    Now the behavior to trigger the AJAX request is attached to the control. For example, if you attach a behavior to an input text control and set it to use the onBlur event, the code on the page might look like this:
    <h:inputText id="nameText" value="#{myPage.name}" 
      binding="#{myPage.name_Ref}" styleClass="inputText" >
      <hx:behavior event="onblur" id="behavior1" 
        behaviorAction="get" targetAction="updatablePanel">
      </hx:behavior>
    </h:inputText>
    The behavior might look like this example:
    Picture of the behavior in the Quick Edit view
  6. Create the request by specifying the panel to update and the parameters for the request:
    1. On the web page, select the panel control.
    2. With the panel selected, open the Properties view.
    3. On the properties view, go to the Ajax tab under the type of panel control.
    4. On the Ajax tab, select the Allow Ajax updates check box.
    5. Click Refresh as the type of request.
    6. Under the types of requests, click the button labeled Click to edit Ajax request properties.
    7. In the Target list, select the ID attribute of the panel you want to update.
    8. Add parameters to the request by clicking one of the Add Parameter buttons:

      The parameters in the table labeled Parameter values sent from the browser refer to the value of input controls on the page. For example, if you want to pass the current value of an input control on the page as a parameter, add that input control's ID here.

      The parameters in the table labeled Parameter values calculated on the server refer either to literal values you type here or to the value of variables in the JSF Handler.

    For example, if you choose to pass the value of an input control on the page, the new request might look like this:
    <hx:ajaxRefreshRequest id="ajaxRefreshRequest1" 
      target="updatablePanel" params="nameText">
    </hx:ajaxRefreshRequest>
    In the editor, the AJAX request might look like this example:
    Picture of the AJAX request in the Properties view
  7. In the JSF Handler for the page, configure the onPreRenderFunction to accept the request.

    Because the onPreRenderFunction runs when the page first loads as well as on every AJAX request, you might want to detect which case has caused the function to run. You can do this by testing for the value of the parameter $$ajaxmode. When the function runs as the result of a normal page loading operation, this parameter has a null value; when the function runs as the result of an AJAX request, the parameter will contain a value.

    function onPreRender()
      
      if (J2EELib.getQueryParameter("$$ajaxmode") == NULL)
        //The page is loading for the first time.
        //Perform page loading operations here.
      else
        //The page is loading as the result of an AJAX request.
        //Perform AJAX updating operations here.
      end
    
    end
  8. Once you have determined that the onPreRenderFunction has been invoked as the result of an AJAX request, you can update the controls on the page by setting the values of the variables bound to those controls. You can update only the controls within the panel in the request.
    You can retrieve the parameters passed with the request by using the J2EELib.getQueryParameter() system function. For example, if you passed the value of a text control with the ID nameText, you can retrieve the value of that parameter with the following code:
    outputText = "Hello "::J2EELib.GetQueryParameter("nameText")::"!";

For an example of an AJAX refresh request, see Updating portions of a web page with AJAX requests.


Feedback