This section describes how to configure a plugin browse component that displays repository assets as an expandable tree of folders and items. (See the image of the Browse tab in the previous section for an example .) Note that a similar plugin for browsing file-based assets as a tree is provided with ATG Content Administration.
If you want to add your tree to a custom view, see Implementing a New Tree View. Many of the resources you create and configure here are also described in the views section. You need only create these resources once and they can be used by both the view and Asset Picker.
The procedure for configuring the repository browse plugin has these steps, which are described in the sections that follow:
Create a Mutable Repository Tree Definition component, which defines the repository item relationships that make up the tree. Also, use this component to identify the property whose value determines the order of items in the tree. See Mutable Repository Tree Definition Component.
A default component,
/atg/web/tree/CountBasedBucketer, manages the display of large numbers of items by dividing them into buckets. If all trees use the same bucketing specifications, use the existing component, modifying its settings as needed. If bucketing specifications vary, create Count Based Bucketer components for each tree. See Count Based Bucketer Component.Create a Bucketing Tree Impl component to manage the resources used for buckets. See Bucketing Tree Impl Component.
Create a Tree State component to handle persistence of the tree state for each user in the appropriate project context. See Tree State Component.
Register the tree.
If you are adding the Asset Picker tree to the Asset Manager part of the Business Control Center, register the tree in a Tree Registry Component. See Tree Registry Component.
If you are adding the Asset Picker tree to the base Business Control Center (ATG Content Administration), register the tree in the View Mapping system. See Registering the Browse Plugin with the View Mapping System.
Mutable Repository Tree Definition Component
Create a global-scoped component of class atg.web.tree.repository.MutableRepositoryTreeDefinition to configure the parent-child relationships of the repository whose items you want to display. The parent-child relationships correspond to the tree structure that will appear to the user. By defining them here, you allow the client to request the children of any repository item without needing any knowledge of the structure of the repository itself. For example, if you wanted to show related products, you would provide the following value to the treeLinks property:
product=fixedRelatedProducts;dynamicRelatedProducts;
catalogsRelatedProductsConfigure one component of this type for each tree plugin you are adding.
A tree display can have top-down or bottom-up structures. In a top-down structure, an item has one or more properties that point to its children. In a bottom-up example, an item has a property that points to its parent. For example:
folder=folder:parentFolder;media:parentFolder
Given the previous example, this means that items of type parentFolder have two types of children:
foldermedia
For these items, the parentFolder property equals the folder whose children are displayed in this tree.
For a top-down relationship, the treeLinks property is specified with slightly different syntax, where the keys are the names of itemDescriptors and the values are semicolon-delimited lists of the property names of that itemDescriptor's children. In the following example, the children of the parentFolder item type are held in properties folder and media.
parentFolder=folder;media
The way items are sorted depends on whether those items use top-down or bottom-up relationships. Most top-down items appear in the order they were created or added and can be rearranged manually in the UI. For items with bottom-up relationships, the sortProperties property of this component holds the property whose values determine the sort order. By default, items are sorted by display name in alphabetical order.
There are two important things to know about sorting:
Regardless of whether the tree uses top-down or bottom-up relationships, you can use a Node Sorter component to define a complex sorting strategy that, for example, incorporates multiple levels of sorting. See Customizing the Order of Items in a Tree.
If your tree branches contain a large number of assets, they will be automatically grouped into buckets. See the Count Based Bucketer Component section for configuration details.
All Mutable Repository Tree Definition classes provide the following configurable properties:
Property | Description |
|---|---|
| Indicates whether root nodes are hidden from the Browse tab and Asset Picker views. When you create new items, a root node is not automatically assigned as the parent. |
| The Nucleus component that represents the repository whose assets you want to display in this tree. |
| The RQL query that is used to get the root nodes. It might be as simple as ALL or might include some collection criteria—for example, |
| Provides, for each item type in the tree, a property whose value determines an item’s position in the tree as well as the direction – ascending or descending – the values are sorted in. The format is |
| Describes the parent to child relationships of the tree in a map. The exact syntax varies depending on whether the tree has a top-down or bottom-up hierarchy. See the examples below. |
Count Based Bucketer Component
A session-scoped Nucleus component of the class atg.web.tree.CountBasedBucketer manages the display of large numbers of assets by chunking them into groups, or “buckets.” The following diagram illustrates this concept, which is similar to paging:
+ folder a
- folder b
+ folder 1
+ folder 2
+ folder 3
- folder 4
o items 1-25
o items 26-50
o items 51-75
+ folder c
Folder 4 contains more than a specified number of items, which are grouped into buckets (shown with the symbol “o” here) that contain 25 items each. Each bucket is named for the type of items it contains. Note that a bucket can contain one type of item only.
In cases where very large numbers of assets exist, buckets are created within buckets (also called double bucketing).
The bucketRatio and bucketSize properties determine the number of items that appear in a bucket and the number of items that triggers bucketing and double bucketing.
The default component of this class, /atg/web/tree/CountBasedBucketer, has a bucketingRatio of 1.5 and bucketingSize of 40. Modify these values as needed.
Buckets use the sorting strategy defined for the items they contain. If you sort items by creation date (using the sortProperties property of the MutableRepositoryTreeDefinition component), buckets group items by creation date. Each bucket has a label that shows the range of its contents identified by display name, such as City Girl Boots – Spring Showers Boots, regardless of the property used to sort the items within it. You can change the bucket label so it names a range of property values that represent the property used for sorting. To do this, extend the Count Based Bucketer class and override the putLabelsOnBuckets(List pBuckets) method, replacing it with a method that locates the property held by the sortProperties property.
If you prefer to have multiple levels of bucketing, each of which organizes items based on a different property value, for example, you can create a Node Sorter component as described in Customizing the Order of Items in a Tree.
A Count Based Bucketer component has the following configurable properties:
Property | Description |
|---|---|
| Determines when to bucket items and when to simply display all items without bucketing them. Bucketing begins when the number of items is greater than the If the number of items is greater than ( |
| The number of items per bucket. |
| Determines what displays in the bucket label. If |
The following example is from CountBasedBucketer.properties, which defines the buckets for all trees, such as the Organizations and Roles view of the Browse tab.
$class=atg.web.tree.CountBasedBucketer $scope=global bucketRatio=1.5 bucketSize=40
Bucketing Tree Impl Component
Create a global component of class atg.web.tree.BucketingTreeImpl to control the display of items in the tree. Configure one component of this type for each tree plugin you are adding.
All Bucketing Tree Impl classes provide the following configurable properties:
Property | Description |
|---|---|
| Names the Count Based Bucketer component that controls the generation and contents of buckets. |
| Names the Node Sorter component that defines a multi-level sorting strategy for items in the tree. This component is optional. See Customizing the Order of Items in a Tree for more information about it. |
| Names the Bucketing Tree component that defines the parent-child relationship for this repository. |
| Names the Tree Node Filter that defines rules for determining items to exclude from the tree. This component is optional. See Excluding Items from a Tree for more information. |
The following example is from WWWFileSystemTree.properties, which defines the Bucketing Tree Impl component for the default VFS browse plugin.
$class=atg.web.tree.BucketingTreeImpl $scope=global treeDefinition=WWWFileSystemTreeDefinition nodeBucketerPath=/atg/web/tree/CountBasedBucketer
Tree State Component
Create a session-scoped Nucleus component of the class atg.web.tree.TreeState that monitors opened, checked, and selected nodes. Keeping track of the tree state ensures that when a user switches between views tree information persists.
Configure one component of this type for each tree plugin you are adding.
A Tree State component has the following configurable properties:
Property | Description |
|---|---|
| Optional. An array of the item descriptors that you want to appear with the tree check box control in the UI. This property is useful for situations where the user is not already prompted to specify the asset types he or she wants to browse. In the example below, the property has a dummy value. |
| Specifies the Bucketing Tree component that supplies the tree data. |
| Optional. An array of the item descriptors that you want to be highlighted on selection in the UI. The example below uses a dummy value so no highlighting occurs. |
The following example is from TargeterTreeState.properties, which defines the Tree State component for the Targeters view.
$class=atg.web.tree.TreeState $scope=session globalTree=/atg/web/assetmanager/configuration/targeting/TargeterTree
Tree Registry Component
A component of class atg.web.tree.TreeRegistry makes tree views available to the Asset Manager Asset Picker. Update the existing component of this class, atg/web/assetmanager/TreeRegistry, by adding the Bucketing Tree Impl and Tree State components you created earlier to the treeComponents property. These components should be the key and value, respectively.
If your tree displays items of a type that is visible in another tree, create a component, add the two mentioned resources to it, and add the component to the /atg/web/assetmanager/SessionInfo.treeRegistries property.
The following example is from TreeRegistry.properties:
$class=atg.web.tree.TreeRegistry $scope=global treeComponents=\ /atg/web/assetmanager/configuration/profile/FilteredCombinedOrgRoleTreeState =/atg/web/assetmanager/configuration/profile/CombinedOrgRoleTree\ /atg/web/assetmanager/configuration/targeting/ContentGroupTreeState= /atg/web/ assetmanager/configuration/targeting/ContentGroupTree\ /atg/web/assetmanager/configuration/targeting/SegmentTreeState= /atg/web/asset manager/configuration/targeting/SegmentTree\ /atg/web/assetmanager/configuration/targeting/TargeterTreeState= /atg/web/asset manager/configuration/targeting/TargeterTree\ /atg/web/assetmanager/configuration/targeting/nonver/ContentGroupTreeState=/ atg/web/assetmanager/configuration/targeting/nonver/ContentGroupTree\ /atg/web/assetmanager/configuration/targeting/nonver/SegmentTreeState=/atg/ web/assetmanager/configuration/targeting/nonver/SegmentTree/ /atg/web/assetmanager/configuration/targeting/nonver/TargeterTreeState=/atg /web/assetmanager/configuration/targeting/nonver/TargeterTree
Registering the Browse Plugin with the View Mapping System
As part of setting up a repository browse plugin for the Asset Picker in the base Business Control Center, you must register the plugin with the view mapping system by creating an itemMapping for it. The itemMapping includes an attribute that points to the Tree State component. The following table describes how to configure the properties of the itemMapping. If necessary, use the Default Asset Picker Mapping for ConfigFileSystem Assets as a model.
Property | Enter this value |
|---|---|
| Specify |
|
|
| true |
| Specify the repository items to which the plugin applies. Enter an asterisk to specify all items in the repository. |
| The path to the repository component. |
| Specify |
| Enter an asterisk. |
| Specify the tabs you want to include, in other words the |
The DefaultAssetPickerVFSBrowse itemViewMapping calls treeBrowse.jsp by default.
For a detailed description of how to create view mapping items, see Creating View Mapping Repository Items section of the Customizing Asset Display chapter in the ATG Content Administration Programming Guide.
