About HGridDataProxy

Use the HGridDataProxy interface to make the hGrid interactive. This proxy is responsible for handling the expand, collapse, focus, and breadcrumb links of the hGrid.

To animate the hGrid, the proxy needs to maintain the hGrid state across requests. oracle.cabo.ui.data.tree.ClientStateHGridDataProxy is an instance of such a proxy that maintains the state on the client side by encoding the URL.

Here is an example of creating a ClientStateHGridDataProxy in a UIX Servlet event handler, and storing the proxy on the EventResult:


Example:

package oracle.cabo.doc.demo;
public class HGridDemo
{
  public static EventResult doHGridEvent(BajaContext bc, Page page, PageEvent event)
    {
      HGridDataProxy hGridProxy = new ClientStateHGridDataProxy();
      EventResult result = new EventResult(page);
      result.setProperty("hGridProxy", hGridProxy);
      return result;
    }
}

To call the above code, register the above method as the default event handler in the UIX XML file, as shown in the following code snippet:


Example:

<handlers>
  <event name="*">
    <method class="oracle.cabo.doc.demo.HGridDemo"
            method="doHGridEvent"/>
  </event>
</handlers>

The proxy created in the event handler and stored on the EventResult must be data bound to the proxy attribute of the hGrid. The following code snippet is an example of this process:


Example:

<hGrid id="hg1" 
       treeData="${uix.data.treeData.nodes}"
       proxy="${uix.eventResult.hGridProxy}">

The ClientStateHGridDataProxy generates certain UIX Servlet events that must be handled on the server side. In addition, four event parameters may be generated, as shown in the following:

source or SOURCE_PARAM - Specifies the ID of the hGrid that generated this event
state or STATE_PARAM - Specifies the current expand/collapse state of the hGrid
root or ROOT_PARAM - Identifies the current focus root of the hGrid
node or NODE_PARAM - Identifies a tree node that must be expanded/collapsed

The following describes the events triggered by the ClientStateHGridDataProxy, and lists the event parameters accompanying each event:

focus or FOCUS_EVENT - Change the focus of the hGrid. (source, state, root)
expand or EXPAND_EVENT - A tree node must be expanded/collapsed. (source, state, root, node)
expandAll or EXPAND_ALL_EVENT - Recursively expand all the tree nodes beneath the current focus root. (source, state, root)
collapseAll or COLLAPSE_ALL_EVENT - Recursively collapse all the tree nodes beneath the current focus root. (source, state, root)

Each of these four events must be handled on the server. A ClientStateHGridDataProxy needs to be created in each case; it is just a question of which constructor to call. The following code is used to handle each of the hGrid events (for more information about the constructors, see the ClientStateHGridDataProxy JavaDoc):


Example:

public static EventResult doHGridEvent(BajaContext bc, Page page,
                                       PageEvent event)
{
  HGridDataProxy hGridProxy;

  if (event!=null)
  {
    String state = event.getParameter(UIConstants.STATE_PARAM);
    String root = event.getParameter(UIConstants.ROOT_PARAM);
    String node = event.getParameter(UIConstants.NODE_PARAM);

    String eventName = event.getName();
    if (eventName.equals(UIConstants.COLLAPSE_ALL_EVENT))
    {
      hGridProxy = new ClientStateHGridDataProxy(state, root, false);
    }
    else if (eventName.equals(UIConstants.EXPAND_ALL_EVENT))
    {
      hGridProxy = new ClientStateHGridDataProxy(state, root, true);
    }
    else if (eventName.equals(UIConstants.FOCUS_EVENT))
    {
      hGridProxy = new ClientStateHGridDataProxy(state, root);
    }
    else // eventName.equals(UIConstants.EXPAND_EVENT)
    {
      hGridProxy = new ClientStateHGridDataProxy(state, root, node);
    }
  }
  else // there is no event. This is the initial state.
  {
    hGridProxy = new ClientStateHGridDataProxy();
  }
  // create an EventResult such that the current page is rendered again, in
  // response to the event
  EventResult result = new EventResult(page);
  // set the HGrid proxy as a property on the EventResult
  result.setProperty("hGridProxy", hGridProxy);
  return result;
}

Initial focus

Use the ClientStateHGridDataProxy(int[ ] focusPath) constructor to create an hGrid that is initially focused on some subnode (including a leaf node). The array of ints is a path to the subnode that is the focus. Each element is a (zero based) child index of the next node, on the path from root to focus node. The first element is a child index of the root node; it produces the next node, A, on the path. The next element is a child index of node A, and it produces node B, and so on. For example, to focus in on the 3rd child of the 1st child of the root use:


Example:

// Starting from the root, follow the first child (ie: index zero)
 // and then follow the 3rd child (ie: index 2)
int[] focusPath = {0, 2};
hGridProxy = new ClientStateHGridDataProxy(focusPath);

In some cases the tree displayed by the hGrid is small enough that the focusing capability is unnecessary. The focus column (and the breadcrumbs) may be turned off by calling setBreadCrumbsEnabled(false) on the ClientStateHGridDataProxy instance. Note that this can only be done if the hGrid is focused on the root (the default focus). If the hGrid is focused on some subnode, the breadcrumbs should not be disabled, as the user would have no way of focusing out.

Large record set navigation

The constructor doHGridWindowEvent in ClientStateHGridDataProxy enables you to handle large record set navigation in hGrid. See About ChildBlockSize for details about enabling this functionality.