In addition to mapping an entire tree to an object, admins have
the option of mapping only a subtree of an existing tree. To do
that, they have to click on a "Map subtree" link, after
which they will see a list of tree nodes.
The mapped subtree will consist of all subcategories of the
category the user selected - the category itself will not be
included. Note that the mapped subtree will not be a new tree.
Therefore, this option should be used only if an admin plans to use
the subtree as-is and has no intention of making changes to it.
An alternative solution is available for admins who want to
create a tree by copying one of the existing trees and subsequently
playing around with it (moving/adding/deleting categories). To
accomplish that, they would have to create a new tree, go to the
admin page for this tree and click on a "Copy existing
tree" link. They will see a list of available trees to copy.
Clicking on the "Copy this one" link will result in
creating copies of the categories from the source trees and placing
them in the new tree.
This operation can be performed several times, each time the copied
categories will be placed as toplevel categories of the tree.
As far as unmapping is concerned, this operation doesn't delete the mapping between categories and objects.
Permissions
The creator of the category tree is granted the
category_tree_read, category_tree_write and
category_tree_grant_permissions privileges.
The operations one can perform on categories are:
ad (d) You cannot delete a category that has children. Also, you
cannot delete a category that has objects mapped to it (do we want
it or not?)
ad (e) The effect of phasing out a category is that users no longer
will be able to associate objects with it, but existing
associations will still be visible
Deletions and phasing it/out can be performed as bulk
operations.
ad (f) sort key is used to order children of the same parent
category, that is the elements of the tree are sorted first by
parent, then by the sort key.
This table actually stores the information whether the tree is side-wide or not.
create table category_trees (
tree_id integer primary key
constraint cat_trees_tree_id_fk
references acs_objects on delete cascade,
site_wide_p char(1) default 't'
constraint cat_trees_site_wide_p_ck
check (site_wide_p in ('t','f'))
);
Here the tree's name and description is stored in different translations.
create table category_tree_translations (
tree_id integer
constraint cat_tree_trans_tree_id_fk
references category_trees on delete cascade,
locale varchar2(5) not null
constraint cat_tree_trans_locale_fk
references ad_locales,
name varchar2(50) not null,
description varchar2(1000),
primary key (tree_id, locale)
);
This table stores the tree hierarchy by holding the information about the parent category. The tree is ordered by a nested index (left_ind, right_ind). Sorting is thus accomplished by means of a nested set. You can read a description of how nested sets work. This also describes how to write queries that sort correctly when using categories.
create table categories (
category_id integer primary key
constraint cat_category_id_fk
references acs_objects on delete cascade,
tree_id integer
constraint cat_tree_id_fk
references category_trees on delete cascade,
parent_id integer
constraint cat_parent_id_fk
references categories,
deprecated_p char(1) default 'f'
constraint cat_deprecated_p_ck
check (deprecated_p in ('t','f')),
left_ind integer,
right_ind integer
);
Here the actual categories are stored together with different translations.
create table category_translations (
category_id integer
constraint cat_trans_category_id_fk
references categories on delete cascade,
locale varchar2(5) not null
constraint cat_trans_locale_fk
references ad_locales,
name varchar2(200),
description varchar2(4000),
primary key (category_id, locale)
);
This table contains mapping between categories and objects
create table category_object_map (
category_id integer
constraint cat_object_map_category_id_fk
references categories on delete cascade,
object_id integer
constraint cat_object_map_object_id_fk
references acs_objects on delete cascade,
primary key (object_id, category_id)
) organization index;
This is the table for the relation of trees and objects. subtree_category_id comes to play in situations when you map a subtree of an existing tree to an object.
create table category_tree_map (
tree_id integer
constraint cat_tree_map_tree_id_fk
references category_trees on delete cascade,
object_id integer
constraint cat_tree_map_object_id_fk
references acs_objects on delete cascade,
subtree_category_id integer default null
constraint cat_tree_map_subtree_id_fk
references categories,
primary key (object_id, tree_id)
) organization index;
Known Limitations
Integration with other packages
Here are the changes needed to be made to integrate with other packages.
index.adp
Provide an admin-link to
/categories/cadmin/one-object?object_id=\@package_id\@ to let admins
map trees to the package instance.
form-page.tcl
Use this in ad_form to display all mapped category trees and
selected categories (if editing an object):
{category_ids:integer(category),multiple,optional {label "Categories"}
{html {size 4}} {value {$object_id $package_id}}}
Alternatively, you can include the following in your adp:
<include src="/packages/categories/www/include/widget" object_id=\@object_id\@ package_id=\@package_id\@>In the processing part of ad_form use:
category::map_object -remove_old -object_id $object_id $category_ids