JavaScript API Reference

This section contains information for the following:

• Partial and Full Submit
• View Removal

Partial and Full Submit

The ICEfaces Ajax bridge provides a couple of JavaScript functions that developers may find useful in certain situations. The functions are:

• iceSubmit(form, component, event)
• iceSubmitPartial(form, component, event)

The parameters for each are:

form: The form that is being submitted.

component: The component that is triggering the submit.

event: The event that is being handled by the component.

In most cases, the components provided with ICEfaces render out and use these functions appropriately for the common use cases. For example, if you use the commandButton component, the rendered output from the component binds the iceSubmit function to the button's onClick() handler. For components that support the partialSubmit attribute, like the commandButton, setting the partialSubmit attribute to true causes the renderer to bind the iceSubmitPartial function instead. See Table 5, ICEfaces Component Attributes for a list of components that support the partialSubmit attribute.

However, there may be situations where the common usage does not apply or where you would simply like to customize the behavior of the component. In those cases, you can use the bridge functions yourself to change how or when the form submission is done.

For example, suppose you have a login page where you have a couple of input fields and a login button. Perhaps you would like the login button to stay disabled until you have values for both the username and the password. However, the default partial submit behavior is bound to onBlur, so the button cannot be enabled until the user tabs out of the password field. It is more intuitive to have the login button enabled after any text is typed in. This can be done like this:

 
<h:inputSecret id="password" 
 
						value="#{login.password}"
 
						onkeyup="setFocus('');iceSubmitPartial(form,this,event); return false;"
 
						redisplay="true" /> 
 
                
 

Rather than set the partialSubmit attribute to true, which would cause the component to call iceSubmitPartial in onBlur, you can directly call the iceSubmitPartial function in the handler that best suits your application design.

View Removal

Under normal circumstances ICEfaces automatically handles disposal of server-side state associated with a view when that view is closed in the browser. However, in certain portal environments portlets can be removed dynamically from the page without triggering a full page refresh. In this situation, ICEfaces needs to be notified about the portlet removal to properly dispose the view corresponding to the portlet instance. Failure to do so could result in the view being retained until the user session expires or is terminated.

To facilitate timely view disposal in these cases, ICEfaces provides the disposeOnViewRemoval public Javascript function that should be invoked by the portal container before it removes the portlet instance from the page. The function takes only one parameter which has to be a Javascript string representing the ID of an element that is the parent of the HTML fragment rendered by ICEfaces.

For example, if the the element with id="A" is the parent element rendered by the portal and the element with id="B" is the ice:portlet container (div) rendered by ICEfaces, the portal container will have to render a script tag that will wire-up the listener that will invoke ICEfaces' public function disposeOnViewRemoval when the view is closed by the user. In this example, onPortletRemove is just a fictitious function that registers the callback invoked on portlet removal, which is invoked by the portal container when the user closes the view (this function should be replaced with portal specific code by the implementor).

<div id="A">
 
  <script type="text/javascript">
 
onPortletRemove(function() {
 
          disposeOnViewRemoval('A');
 
});
 
  </script>
 
  ....
 
  ....
 
  <div id="B">
 
      ....
 
      ....
 
  </div>
 
  ....
 
  ....
 
</div>
 

Bridge Connection Status Events

The ICEfaces Ajax bridge supports a set of callback APIs that can be used to implement custom JavaScript behaviors in response to bridge connection management events. These functions are:

• Ice.onSendReceive(id, sendCallback, receiveCallback)
• Ice.onAsynchronousReceive(id, callback)
• Ice.onServerError(id, callback)
  Note: The onServerError callback function must provide an argument to receive the body of the error page content.
• Ice.onSessionExpired(id, callback)
• Ice.onConnectionTrouble(id, callback)
• Ice.onConnectionLost(id, callback)

The parameters used are described in the following table:

Parameter	Description
id	the identifier of an element that is the parent or the child of the element owning the bridge instance (most of the time is the `body' element)
callback	callback invoked when event occurs
sendCallback	callback invoked when the request is initiated
receiveCallback	callback invoked when response is received

By implementing these JavaScript callbacks application developers can create custom indicators and reactions for these events. For example, to show a JavaScript alert popup on session expiry this is what is needed:

 
<body id="document:body">
 
    <script type="text/javascript">
 
        Ice.onSessionExpired('document:body', function() {
 
            alert('Session has expired!');
 
        });
 
    </script>
 

Copyright 2005-2009. ICEsoft Technologies, Inc.