oracle.cabo.ui.data.tree
Class ClientStateHGridDataProxy

java.lang.Object
  |
  +--oracle.cabo.ui.data.tree.BaseTreeDataProxy
        |
        +--oracle.cabo.ui.data.tree.ClientStateHGridDataProxy

All Implemented Interfaces:

HGridDataProxy, TreeDataProxy

public class ClientStateHGridDataProxy

extends BaseTreeDataProxy

implements HGridDataProxy

This HGrid proxy supports expanding/collapsing (all) tree nodes and focusing on subtree nodes. It does this by storing the current HGrid state on the client side. This proxy is designed for use with an immutable tree; the proxy does not detect if the backend data tree has been modified since its state was recorded on the client side.

In order to use this class, an instance of this class must be bound to the proxy attribute of an HGrid. Once bound, the appropriate links of the HGrid will behave like a form submission with a parameter named UIConstants.EVENT_PARAM set to one of UIConstants.EXPAND_EVENT, UIConstants.FOCUS_EVENT, UIConstants.EXPAND_ALL_EVENT, and UIConstants.COLLAPSE_ALL_EVENT. In addition there could be another four parameters: UIConstants.SOURCE_PARAM, UIConstants.STATE_PARAM, UIConstants.ROOT_PARAM and UIConstants.NODE_PARAM.

The UIConstants.SOURCE_PARAM identifies the HGrid (or Tree) element that generated the event (this is obtained from the ID attribute of the bean). The UIConstants.STATE_PARAM is an encoding of the current state of the HGrid. UIConstants.ROOT_PARAM is an index. This index identifies the current focus root of the HGrid. UIConstants.NODE_PARAM identifies some tree node that needs to be expanded or collapsed.

When handling these requests on the server, it is necessary to call the correct ClientStateHGridDataProxy constructor that matches the event. This new proxy must be used to render the HGrid so that the interaction is continued. The following is an example:

First the HGridBean is created and the proxy is bound:-

 HGridBean hgrid = new HGrid();
 hgrid.setID("hgrid");
 hgrid.setAttributeValue(UIConstants.PROXY_ATTR,
                         new ContextPropertyBoundValue("my namespace",
                                                       "HGrid State"));
 

Prior to rendering, the server must examine the request to obtain the necessary parameters to use to construct the HGridDataProxy:-

 String event = request.getParameter(UIConstants.EVENT_PARAM);
 String source = request.getParameter(UIConstants.SOURCE_PARAM);
 String state = request.getParameter(UIConstants.STATE_PARAM);
 String root = request.getParameter(UIConstants.ROOT_PARAM);
 String node = request.getParameter(UIConstants.NODE_PARAM);
 HGridDataProxy proxy;
 if (UIConstants.EXPAND_EVENT.equals(event))
   proxy = new ClientStateHGridDataProxy(state, root, node);
 else if (UIConstants.FOCUS_EVENT.equals(event))
   proxy = new ClientStateHGridDataProxy(state, root);
 else if (UIConstants.EXPAND_ALL_EVENT.equals(event))
   proxy = new ClientStateHGridDataProxy(state, root, true);
 else if (UIConstants.COLLAPSE_ALL_EVENT.equals(event))
   proxy = new ClientStateHGridDataProxy(state, root, false);
 else
   proxy = new ClientStateHGridDataProxy();

 renderingContext.setProperty("my namespace", "HGrid State", proxy);
 

Expand/Collapse All

Expand/collapse all is enabled by default. However, depending on the size of the subtree, it might be not feasible to perform an expand-all. In order to turn off expand-all, this proxy recognizes an EXPAND_ALL_KEY property on the DataObject that represents the respective subtree node. If this property is bound to Boolean.FALSE then expand-all (and collapse-all) will not be generated for that subtree. In Addition, an expand/collapse-all performed on a parent node, will not affect a child node with expand-all disabled.

Breadcrumbs and Focus Column

The breadcrumbs and focus column are enabled by default. However, when small trees are being displayed, they may not be very useful. In this case, the breadcrumbs and focus column may be hidden by calling setBreadCrumbsEnabled(boolean) with false. Note that it is not possible to disable the breadcrumbs if the HGrid is already focused in on a subtree, the reason being that the only way a user can focus out is to use the breadcrumbs.

See Also:

HGridBean, TreeBean, ClientStateTreeDataProxy

Field Summary

static java.lang.String

EXPAND_ALL_KEY the key to examine when deciding the feasibility of performing an expand-all.

Constructor Summary

ClientStateHGridDataProxy()
Constructs a proxy with no tree state.

ClientStateHGridDataProxy(int[] focusRootPath)
Constructs a proxy that produces an HGrid that is initially focused on a given tree node.

ClientStateHGridDataProxy(java.lang.String state, java.lang.String root)
Create a proxy in response to a focus event

ClientStateHGridDataProxy(java.lang.String state, java.lang.String root, boolean expandAll)
Create a proxy in response to an expandAll (or collapseAll) event

ClientStateHGridDataProxy(java.lang.String state, java.lang.String root, java.lang.String node)
Create a proxy in response to an expand event

Method Summary

void	doPostRender(RenderingContext context, UINode node) renders the javascript needed by this proxy
DataObjectList	getBreadCrumbs(RenderingContext context, DataObject root)
java.lang.String	getCollapseAllDestination(RenderingContext context, DataObject focusRoot) Gets the destination of the collapse-all link in an HGrid.
java.lang.String	getCollapseDestination(RenderingContext context, DataObject node, int index) Returns a destination that would collapse the tree at the indicated node.
java.lang.String	getExpandable(RenderingContext context, DataObject node, int index) Is this node expanded?
java.lang.String	getExpandAllDestination(RenderingContext context, DataObject focusRoot) Gets the destination of the expand-all link in an HGrid.
java.lang.String	getExpandDestination(RenderingContext context, DataObject node, int index) Returns a destination that would expand the tree at the indicated node.
java.lang.String	getFocusDestination(RenderingContext context, DataObject node, int index) Returns a destination that would focus the HGrid at the indicated node.
DataObject	getFocusRoot(RenderingContext context, DataObject root) Gets the tree node that has the focus.
DataObject	getTreeNode(RenderingContext context, DataObject root, int index)
boolean	isExpandAllEnabled(RenderingContext context, DataObject focusRoot) checks to see if the expand/collapse-all links on this HGrid are enabled.
void	setBreadCrumbsEnabled(boolean isEnabled) Use this method to hide the breadcrumbs.

Methods inherited from class oracle.cabo.ui.data.tree.BaseTreeDataProxy

getChildren, isSelected, selectionEnabled, setFormName, sharedInstance

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.cabo.ui.data.tree.TreeDataProxy

getChildren, isSelected, selectionEnabled, setFormName

Field Detail

EXPAND_ALL_KEY

public static final java.lang.String EXPAND_ALL_KEY

the key to examine when deciding the feasibility of performing an expand-all. The uiXML value is "expandAll"

See Also:

isExpandAllEnabled(RenderingContext, DataObject)

Constructor Detail

ClientStateHGridDataProxy

public ClientStateHGridDataProxy()

Constructs a proxy with no tree state. The expand/collapse state of the tree will be determined by examining the tree node DataObjects at render time.

ClientStateHGridDataProxy

public ClientStateHGridDataProxy(int[] focusRootPath)

Constructs a proxy that produces an HGrid that is initially focused on a given tree node.

Parameters:

focusRootPath - This describes the path from the root of the tree to the subnode that must be the current focus root. Each element in this array indicates the child index of the next node on the path. ie: The I+1'th node is the focusRootPath[I]'th child of node I. Node zero is the root of the tree.
eg: To focus in on the 2nd child of the 5th child of the root use:

int[] focusRootPath = {4, 1};

This follows the child at index 4 (which is the 5th child), and then follows that node's child at index 1 (which is its 2nd child).

ClientStateHGridDataProxy

public ClientStateHGridDataProxy(java.lang.String state,
                                 java.lang.String root)

Create a proxy in response to a focus event

Parameters:

state - the encoded string with the current state of the tree.

root - this identifies the current focus root of the HGrid

Throws:

java.lang.IllegalArgumentException - if the above strings are not well formed.

ClientStateHGridDataProxy

public ClientStateHGridDataProxy(java.lang.String state,
                                 java.lang.String root,
                                 boolean expandAll)

Create a proxy in response to an expandAll (or collapseAll) event

Parameters:

state - the encoded string with the current state of the tree.

root - this identifies the current focus root of the HGrid. The expand/collapse all takes place starting at this node.

expandAll - if true does an expand-all. Otherwise do a collapse-all.

Throws:

java.lang.IllegalArgumentException - if the above strings are not well formed.

ClientStateHGridDataProxy

public ClientStateHGridDataProxy(java.lang.String state,
                                 java.lang.String root,
                                 java.lang.String node)

Create a proxy in response to an expand event

Parameters:

state - the encoded string with the current state of the tree.

root - this identifies the current focus root of the HGrid

node - this identifies the node that must be expanded/collapsed

Throws:

java.lang.IllegalArgumentException - if the above strings are not well formed.

Method Detail

setBreadCrumbsEnabled

public void setBreadCrumbsEnabled(boolean isEnabled)

Use this method to hide the breadcrumbs. The breadcrumbs cannot be hidden if the HGrid has been focused into a subtree. If the breadcrumbs are hidden, then the focus column will also be hidden.

Parameters:

isEnabled - The breadcrumbs are enabled by default. Setting this to false will hide the breadcrumbs.

Throws:

java.lang.IllegalArgumentException - if the breadcrumbs cannot be disabled.

doPostRender

public void doPostRender(RenderingContext context,
                         UINode node)
                  throws java.io.IOException

renders the javascript needed by this proxy

Specified by:

doPostRender in interface TreeDataProxy

Overrides:

doPostRender in class BaseTreeDataProxy

Parameters:

node - the HGrid UINode

getFocusDestination

public java.lang.String getFocusDestination(RenderingContext context,
                                            DataObject node,
                                            int index)

Returns a destination that would focus the HGrid at the indicated node.

Specified by:

getFocusDestination in interface HGridDataProxy

Parameters:

node - the tree node

index - the row index of this tree node

getExpandDestination

public java.lang.String getExpandDestination(RenderingContext context,
                                             DataObject node,
                                             int index)

Returns a destination that would expand the tree at the indicated node.

Specified by:

getExpandDestination in interface TreeDataProxy

Overrides:

getExpandDestination in class BaseTreeDataProxy

Parameters:

node - the tree node

index - the row index of this tree node

getCollapseDestination

public java.lang.String getCollapseDestination(RenderingContext context,
                                               DataObject node,
                                               int index)

Returns a destination that would collapse the tree at the indicated node.

Specified by:

getCollapseDestination in interface TreeDataProxy

Overrides:

getCollapseDestination in class BaseTreeDataProxy

Parameters:

node - the tree node

index - the row index of this tree node

getExpandable

public java.lang.String getExpandable(RenderingContext context,
                                      DataObject node,
                                      int index)

Description copied from interface: TreeDataProxy

Is this node expanded?

Specified by:

getExpandable in interface TreeDataProxy

Overrides:

getExpandable in class BaseTreeDataProxy

Returns:

one of UIConstants.EXPANDABLE_NO, UIConstants.EXPANDABLE_EXPANDED or UIConstants.EXPANDABLE_COLLAPSED

getFocusRoot

public DataObject getFocusRoot(RenderingContext context,
                               DataObject root)

Description copied from interface: HGridDataProxy

Gets the tree node that has the focus.

Specified by:

getFocusRoot in interface HGridDataProxy

Parameters:

root - the root of the HGrid tree.

Returns:

the tree node that currently has the HGrid focus.

getTreeNode

public DataObject getTreeNode(RenderingContext context,
                              DataObject root,
                              int index)

Parameters:

root - the root of the HGrid tree.

index - the row index (zero based) of the required tree node.

Returns:

the tree node at the specified index, or null, if there is none.

getBreadCrumbs

public DataObjectList getBreadCrumbs(RenderingContext context,
                                     DataObject root)

Specified by:

getBreadCrumbs in interface HGridDataProxy

Parameters:

root - the root of the tree

Returns:

each DataObject is a bread crumb.

isExpandAllEnabled

public boolean isExpandAllEnabled(RenderingContext context,
                                  DataObject focusRoot)

Description copied from interface: HGridDataProxy

checks to see if the expand/collapse-all links on this HGrid are enabled. If an expand-all operation on the focus root (the tree node that has the focus) would result in too many rows, then this method must return false.

Specified by:

isExpandAllEnabled in interface HGridDataProxy

Parameters:

focusRoot - checks to see if it is feasible to completely expand this focus root.

Returns:

true if focusRoot has a property EXPAND_ALL_KEY and its value is not Boolean.FALSE

See Also:

EXPAND_ALL_KEY, Boolean.FALSE

getExpandAllDestination

public java.lang.String getExpandAllDestination(RenderingContext context,
                                                DataObject focusRoot)

Description copied from interface: HGridDataProxy

Gets the destination of the expand-all link in an HGrid. This method is called only if the expand-all operation is permitted.

Specified by:

getExpandAllDestination in interface HGridDataProxy

Parameters:

focusRoot - The current focus of the HGrid

getCollapseAllDestination

public java.lang.String getCollapseAllDestination(RenderingContext context,
                                                  DataObject focusRoot)

Description copied from interface: HGridDataProxy

Gets the destination of the collapse-all link in an HGrid. This method is called only if the expand-all operation is permitted.

Specified by:

getCollapseAllDestination in interface HGridDataProxy

Parameters:

focusRoot - The current focus of the HGrid