Customizing the Tree in the Admin Interface

56 Customizing the Tree in the Admin Interface

Administrative and editorial users of WebCenter Sites interact with various trees that display in the Admin interface. You can customize the Admin interface by modifying these trees.

Topics:

About the Tree in the Admin Interface

The tree displays a number of nodes in the left pane of the Admin interface.

Figure 56-1 Admin Interface

Description of "Figure 56-1 Admin Interface"

WebCenter Sites tree tabs are created by the tree applet. You can create or modify your own trees by setting various parameters that are passed to the tree applet. The tree applet accepts several kinds of parameters:

Applet-wide parameters, which control the overall appearance and behavior of the applet.
Tree-specific parameters, which control the appearance and behavior of the tree.
Node parameters, which control the appearance and behavior of individual nodes on the tree.
OpURL Node parameters, which allow the tree to communicate with WebCenter Sites.

A set of tree tab tables in the database stores information about tree configuration, including tab names, what roles have access to a tab, and the path to the element that populates the tree tab with data. You enter information into these tables through the Tree Tabs screens. From the Admin interface, select the Admin tab and then click the Tree node.

Loading the Tree Tabs

For most of the default tree tabs supplied with WebCenter Sites, requests for tree data pass through the OpenMarket/Gator/UIFramework/LoadTab element. The LoadTab element performs several basic tasks, such as checking for session timeout.

For example, the Product tab completes the following steps as it loads:

Java code in the Product tab calls the LoadTab element.
The LoadTab element queries the TreeTab database tables to retrieve the elements that load the data for the Product tree's top-level nodes. In this case, the elements are the OpenMarket/Xcelerate/ProductGroups/LoadTree element and the OpenMarket/Xcelerate/Product/LoadTree element.
The OpenMarket/Xcelerate/ProductGroups/LoadTree element and the OpenMarket/Xcelerate/Product/LoadTree element query the database for assets that correspond to the tree nodes and stream back node data to the tree applet.
The tree applet parses the node data and opens the nodes.
Java code in the Product tab calls an element to initialize its global context menu, the OpenMarket/Gator/UIFramework/LoadGlobalPopup element. This element sends a GetTypes command to each tree loading element called by the Product tab. When the tree loading elements receive this command, they return a list of asset types whose start menu items should appear in the global context menu.
The OpenMarket/Gator/UIFramework/LoadGlobalPopup element finds the start menu items for the specified asset types and streams that information back to the tree.

Note that each asset type in the system must have a LoadTree element. The LoadTree element is a pointer to another element that actually loads the tree. If an asset type can have children, each of those children must have a LoadTree element. LoadTree elements have the following path:

OpenMarket/Xcelrate/AssetType/MyAssetType/LoadTree

where MyAssetType is the name of the asset type to which the LoadTree element refers.

LoadTree elements are called based on the asset type set in the Section field of the Manage Tree form.

The following table contains a list of several elements used by core asset types to load their trees.

Table 56-1 Asset Type Elements

Asset Type	Location	Description
Flex Groups	`OpenMarket/Gator/UIFramework/LoadGroupNodes`	Displays a FlexGroup parent hierarchy and FlexAsset children.
Flex Assets	`OpenMarket/Gator/UIFramework/LoadOrphanNodes`	Displays flex assets that do not belong to a flex group.
Site Navigation Tree	`OpenMarket/Xcelerate/AssetType/Page/LoadSiteTree`	Displays the SitePlan tree.
Site Navigation Associations	`OpenMarket/Gator/UIFramework/LoadChildren`	Displays asset associations in the SitePlan tree.
Bookmarks	`OpenMarket/Gator/UIFramework/LoadActiveList`	Displays the Bookmarks tree.
Administrative Tree	`OpenMarket/Gator/UIFramework/LoadAdminTree`	Displays the Administrative tree.
Administrative Tree Helper Elements	`OpenMarket/Gator/UIFramework/Admin`	Loads helper elements for the Administrative tree.
Asset Types	`OpenMarket/Gator/UIFramework/LoadAdministrationAsset`	Displays an asset type node at the top level of the tree and the names of all assets of that type on lower levels of the tree.

To change the appearance or behavior of nodes in your tree, create a new tree loading element based on one of these standard elements. Your website administrator can then specify the element's name and the path to that element in the Section Name and Element Name fields of the New Tree form, located off the Tree Tabs form.

See About Creating Tree Tabs in Administering Oracle WebCenter Sites.

Note:

In some cases with a default JRE installation, some items in the tree may display with boxes in the name rather than UTF-8 characters. There are two ways to solve this font issue:

Copy the supported font files to $JRE_HOME/lib/fonts/fallback
Configure local fonts to physical fonts via mapping through one of the font configuration property files, as described here: http://docs.oracle.com/javase/8/docs/technotes/guides/intl/fontconfig.html.

For more information about modifying tree nodes, see Node Parameters.

Applet-Wide Parameters

Applet-wide parameters are set in the TreeAppletParams.xml element. To modify the tree applet's behavior, change the parameter values as shown in the following table.

Table 56-2 Applet-Wide Parameters

Parameter	Description
`Debug`	Turns debugging on and off. Valid values are `true` and `false`. If `Debug` is set to `true`, Java console debug and error messaging is turned on.
`ServerBaseURL`	Sets the base string to which all the node data URL strings are appended. For example, if the `ServerBaseURL` is set to `file://localhost,` and the value of the `LoadURL` parameter is `NodeReader.test,` then the URL used for loading the tree's child nodes is as follows: `file://localhost/NodeReader.test`
`BackgroundColor`	Sets the background color of the tree using a decimal RGB value. If this parameter is not set, the background color defaults to the color of the HTML frame in which the tree is embedded.
`TotalPanes`	Sets the number of tree tabs that are displayed. This value is set automatically.
`URLTarget`	The target frame in which to display node links. The default value is `XcelAction` (name of the pane on the right side of the browser window).

Tree-Specific Parameters

Tree-specific parameters are set by the Add New Tree Tab form and the OpenMarket\Gator\UIFramework\TreeTabAdd.xml element that creates the Add New Tree Tab form. To modify the tree's appearance or behavior, change the parameter values by using the form or by altering the TreeTabAdd element.

Table 56-3 Tree-Specific Parameters

Parameter	Description
`Title`	Sets the text that is displayed on the tab. This value is set in the Title field of the Manage Tree form, found on the Admin tab.
`ToolTip`	Sets the text that is displayed when the mouse pointer hovers over the tab index. This value is set in the Tool Tip field of the Manage Tree form, found on the Admin tab.
`LoadURI`	The URI of the page to call to retrieve a node's children. This value is set in the `TreeTabAdd` element.
`ActionURL`	The URL of the page that performs a context menu action for a node in the tree. The default value points to the `OpURL.xml` element. This value is set in the `TreeTabAdd` element.
`OpenIcon`	The path to the icon to use when depicting an expanded node. The default is a plus sign (`+`). This value is set in the `TreeTabAdd` element.
`CloseIcon`	The path to the icon to use when depicting an unexpanded node. The default is a minus sign (`-`). This value is set in the `TreeTabAdd` element.
`LineStyle`	Sets whether lines connect the nodes of the tree. Valid values are `Angled` and blank; `Angled` is the default. If the parameter is set to `Angled`, lines connect the nodes. If the value is left blank, no lines connect the nodes. This value is set in the `TreeTabAdd` element.
`RootID`	Sets the ID of the root node. This string is used for specifying the node path. It defaults to the value of the `Title` parameter. This value is set in the `TreeTabAdd` element.
`GlobalItems`	This value is set in the GlobalItems field of the Manage Tree form, found on the Admin tab.
`NodeItems`	This value is set in the NodeItems field of the Manage Tree form, found on the Admin tab.

Node Parameters

The node parameters determine the appearance and behavior of the nodes in your tree. To define the appearance and behavior of these nodes, you write an element that sets the node parameters and passes their values to the BuildTreeNode.xml element, which creates the tree nodes.

Table 56-4 Node Parameters

Parameter	Description
`Label`	Specifies the text to be displayed for this node. The value does not have to be unique. The default value is "".
`ID`	A string identifier that is unique within the tree, used by WebCenter Sites to express selection paths. The ID is specified by WebCenter Sites.
`ExecuteURL`	The URI value of the page to be displayed when completing the `Execute` action. This value has the value of `ServerBaseURL` prepended to it. If the node is not executable, do not include this parameter in the node data.
`URLTarget`	The frame target for `ExecuteURL`. If `ExecuteURL` is not included in the node data, it defaults to the target specified in the Applet-wide parameters.
`Description`	An alternative to the string specified in `Label`, if you choose this option on the tree-wide context menu. The default value is "".
`Level`	The relative level of this node, represented by a number >= 0. A value of 0 indicates that the node is an immediate child of the node requesting the data. To load multiple levels of nodes at a time, set this value to a number greater than zero. The default value is 0.
`Image`	The URI for the image to be prepended to the label. If this field is not included in the node data, then no image is displayed for that node.
`LoadURL`	The URI for the subtree hierarchy. If this field is not included in the node data, this node requires no additional loading. The URL specified in this parameter must contain enough information so that the tree applet can find that node's children. For example, if your hierarchy is as follows: Product Tab / Reebok / Running Shoes the value of `LoadURL` is as follows: ContentServer?pagename=OpenMarket/Gator/UIFramework/ LoadTab&AssetType=ProductGroups&populate=OpenMarket/ Xcelerate/AssetType/ProductGroups/LoadTree&op= load&parent=Variables.parentid where `parentid` is the assetid of the "Running Shoes" asset, and `op` and `populate` are used by `LoadTab` to route to your tree load element.
`OKAction`	An action that is displayed in the node's context menu. This string may appear multiple times in the same node data set.
`OpURL`	The URL to execute a given action on the server. This value is prepended with the value of the `ServerBaseURL` parameter. Include this parameter in the node data unless the value of the `NodeItems` parameter is a null string, and thus has no `OKAction` specified.
`RefreshKeys`	Creates a key or set of set of keys which can be used to refresh the tree. Set the value to the ID of the current node.

The following excerpt from the LoadAdministrationAsset element sets the values of the node parameters and passes those values to the BuildTreeNode element.

The ListofAsset list referred to in this excerpt is a list of information about assets of a given type. This list was generated by a SQL query that is executed elsewhere in the element.

<CALLELEMENT NAME="OpenMarket/Gator/UIFramework/BuildTreeNode">
  <ARGUMENT NAME="Label" 
    VALUE="ListofAsset.name"/>
  <ARGUMENT NAME="Description" 
    VALUE="ListofAsset.description"/>
  <ARGUMENT NAME="ID" 
    VALUE="Variables.TreeNodeID"/>
  <ARGUMENT NAME="OpURL" 
    VALUE="ContentServer?pagename=
    OpenMarket/Gator/UIFramework/TreeOpURL&#38;
    AssetType=Variables.AssetType"/>

  <ARGUMENT NAME="ExecuteURL" 
    VALUE="ContentServer?pagename=
    OpenMarket/Gator/UIFramework/TreeOpURL&#38;
    AssetType=Variables.AssetType&#38;n0_=
    Variables.packedTreeNodeID&#38;op=displayNode"/>

  <ARGUMENT NAME="OKActions" 
    VALUE="Status;Inspect;Edit;Delete;refresh"/>
  <ARGUMENT NAME="Image" 
    VALUE="Xcelerate/OMTree/TreeImages/AssetTypes/Variables.AssetType.gif"/>
  <ARGUMENT NAME="RefreshKeys" 
    VALUE="ListofAsset.id"/>
</CALLELEMENT>

To customize the appearance or behavior of tree nodes, copy one of the standard elements and modify the node arguments. Note that tree loading elements are passed the following variables, so any tree loading element that you create or customize must take these variables into account.

Variables Passed in by the LoadTree Element:

AssetType: Set to the section name that was created using the New Tree form
op: Set to init

Variables Passed in by the LoadGlobalPopup Element:

command: Set to GetTypes
AssetType: Set to the section name that was created using the New Tree form
varname: You set this with a comma-separated list of asset types for which you want to display start menu items
popupvar: You set to either true, to add items to the global context menu, or false, if you do not have to add items to the context menu

Adding a Command Node Context Menu

Each node on the tree has a menu that displays when the user right-clicks the mouse. Commands on this menu allow you to refresh the node or load pages in the right side of the browser window. You can add commands to a node context menu that allow you to load forms such as the status and publish forms. Any form that can be called using an asset type and ID is a good candidate for being called by a node context menu command.

Add a command to the node context menu by completing the following steps:

Add the new command, exactly as you want it to appear, into the node's OKActions field.

In the element referred to in the node's OpURL (usually the TreeOpURL element), add a new IF statement that calls the form you want to load.

For example, the following code from the TreeOpURL element opens a node:

<IF COND="Variables.op=displayNode">
     <THEN>
      <callelement NAME="OpenMarket/Gator/UIFramework/TreeIDFromPath">
      <argument NAME="TreePath" VALUE="Variables.TreeNodePath"/>
      </callelement>
         <setvar NAME="id" VALUE="Variables.ID"/>
         <callelement NAME="OpenMarket/Xcelerate/UIFramework/ApplicationPage">
         <argument NAME="ThisPage" VALUE="ContentDetailsFront"/>
         <argument NAME="contentfunctions" VALUE="true"/>
         <argument NAME="AssetType" VALUE="Variables.AssetType"/>
     </callelement>
    </THEN>

Refreshing the Tree

Elements that can alter the tree are responsible for refreshing the tree so that it displays current data. There are three different types of refresh actions that you can specify:

Self: Refreshes the children of the specified node
Parent: Refreshes the specified node and its children
Root: Refreshes the entire tree

There are two steps to refreshing the tree:

Code your tree customization elements so that the tree nodes that you want to refresh have RefreshKeys. RefreshKeys are usually the asset ID of the current node, and allow the refresh to take place.
Call the OpenMarket/Xcelerate/UIFramework/UpdateTreeOMTree element, and pass the element the _TreeRefreshKeys_ variable, specifying the type of refresh you want in the variable value.

You set the RefreshKeys for a node by passing the RefreshKeys argument to the BuildTreeNode element, as shown in the code sample in Node Parameters.

To refresh the tree, call the OpenMarket/Xcelerate/UIFramework/UpdateTreeOMTree element, as shown in the following example:

<CALLELEMENT NAME="OpenMarket/Xcelerate/UIFramework/UpdateTreeOMTree">
    <ARGUMENT NAME= "_TreeRefreshKeys_" VALUE= "Root:ActiveList"/>
</CALLELEMENT>

About Trees and Security

WebCenter Sites uses security roles to control access to the tree in the WebCenter Sites Admin interface. You need to assign the xceladmin ACL to the users of the system-defined nodes such as Admin and Workflow.

Additional control is available by setting properties in wcs_properties.json. For example, xcelerate.showSiteTree determines whether the tree is displayed by default; xcelerate.restrictSiteTree determines which users can display or hide the tree. See Managing Users and Security in Administering Oracle WebCenter Sites.

About Tree Error Logging

All tree-related error and debug messages are logged to the Java Console. You can turn debugging on and off by supplying a value for the Debug parameter when you create a tree.

Note that enabling debug affects performance, so error logging in the delivery system should generally be turned off.