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 of how the tree looks in the UI.) 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. 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 according to its settings. If all trees should use the same bucketing specifications, use the existing component, modifying its settings as needed. If bucketing specification vary by tree, create a Count Based Bucketer component. See Count Based Bucketer Component.Create a Bucketing Tree Impl component to manage the sorting, filtering, and ordering of overflow items into 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 a tree. If you are adding the Asset Picker tree to:
The Asset Manager part of the ATG Business Control Center (Personalization or Merchandising Operations): register the tree in a Tree Registry Component. See Tree Registry Component.
The base ATG Business Control Center (Content Administration or Outreach Operations): 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 assets 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, beneath a product, its related products, you would provide the following value to the treeLinks property: product=fixedRelatedProducts;dynamicRelatedProducts;catalogsRelatedProducts
Configure one component of this type for each tree plugin you are adding.
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. |
| The Nucleus component that controls the label used for an item in the tree. |
The following example is from the MediaTreeDefinition.properties file, which supports the ATG Merchandising Media view.
$class=atg.web.tree.repository.MutableRepositoryTreeDefinition $scope=global treeLinks=\ folder=folder:parentFolder;media:parentFolder sortProperties=\ media=name:ascending,\ folder=name:ascending repository=/atg/commerce/catalog/MerchandisingProductCatalog rootNodeRQL=folder='parentFolder IS NULL' versionManager^=/atg/epub/Configuration.versionManager cloneHelper=/atg/web/assetmanager/action/NameChangingCloneHelper
Note that a tree can be defined as top-down or bottom-up structures. In a top-down tree, each non-leaf node in the tree has one or more properties that point to its children. In a bottom-up tree, each non-root node has a property that points to its parent. The previous example defines a bottom-up tree, and it uses the following syntax:
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 by this tree.
For a top-down tree, the treeLinks property is specified with slightly different syntax, where the keys are the names of itemDescriptors and the values are semi-colon 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.
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 items 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 1.5 and bucketingSize of 20. Modify these values as needed. If a given tree requires different values for these properties than required of other trees, create a component of this class and define its property values. If you’ve created a custom Node Sorter component that sorts your items by creation date, for example, you might want to change the bucketing mechanism so that it also groups items by creation date. To do this, create a class that extends the NodeBucketer interface and provides the logic to group items in the way you prefer.
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. |
The following example is from CountBasedBucketer.properties, which defines the buckets for the Organizations and Roles view of the Browse tab.
$class=atg.web.tree.CountBasedBucketer $scope=global bucketRatio=1.5 bucketSize=20
Bucketing Tree Impl Component
Create a global component of class atg.web.tree.BucketingTreeImplto 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. |
| Holds the Node Sorter component that defines the sort order of items in the tree. |
| Names the Bucketing Tree component that defines the parent-child relationship for this repository. |
| Holds the Tree Node Filter that defines rules for determining items to exclude from the tree. |
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 as the key and value, respectively to the treeComponents property. If your tree displays items of an item type that’s visible in another tree, create a new 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 ATG 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 DefaultAssetPickerVFSBrowseitemViewMapping calls treeBrowse.jsp by default.
For a detailed description of how to create view mapping items, see Creating New View Mapping Repository Items section of the Customizing Asset Display chapter in the ATG Content Administration Programming Guide.
