• Publicity: Public Only All

category-trees-procs.tcl

Procs for the site-wide categorization package.

Location:
packages/categories/tcl/category-trees-procs.tcl
Created:
16 April 2003
Author:
Timo Hentschel <timo@timohentschel.de>
CVS Identification:
$Id: category-trees-procs.tcl,v 1.31.2.15 2023/02/27 12:10:41 antoniop Exp $

Procedures in this file

Detailed information

category_tree::add (public)

 category_tree::add [ -tree_id tree_id ] -name name \
    [ -description description ] [ -site_wide_p site_wide_p ] \
    [ -locale locale ] [ -user_id user_id ] \
    [ -creation_ip creation_ip ] [ -context_id context_id ]

Insert a new category tree. The same translation will be added in the default language if it's in a different language.

Switches:
-tree_id (optional)
-name (required)
-description (optional)
-site_wide_p (optional, defaults to "f")
-locale (optional)
-user_id (optional)
-creation_ip (optional)
-context_id (optional)
Options:
-tree_id
tree_id of the category tree to be inserted.
-locale
locale of the language. [ad_conn locale] used by default.
-name
tree name.
-description
description of the category tree.
-user_id
user that adds the category tree. [ad_conn user_id] used by default.
-creation_ip
ip-address of the user that adds the category tree. [ad_conn peeraddr] used by default.
-context_id
context_id of the category tree. [ad_conn package_id] used by default.
Returns:
tree_id
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_synonyms, category_link, category_crud, category_get_procs, category_tree_procs

category_tree::copy (public)

 category_tree::copy -source_tree source_tree -dest_tree dest_tree

Copies a category tree into another category tree.

Switches:
-source_tree (required)
-dest_tree (required)
Options:
-source_tree
tree_id of the category tree to copy.
-dest_tree
tree_id of the category tree to copy into.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::delete (public)

 category_tree::delete tree_id

Deletes a category tree.

Parameters:
tree_id (required)
category tree to be deleted.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::edit_mapping (public)

 category_tree::edit_mapping -tree_id tree_id -object_id object_id \
    [ -assign_single_p assign_single_p ] \
    [ -require_category_p require_category_p ] [ -widget widget ]

Edit the parameters of a mapped category tree.

Switches:
-tree_id (required)
-object_id (required)
-assign_single_p (optional, defaults to "f")
-require_category_p (optional, defaults to "f")
-widget (optional)
Options:
-tree_id
mapped category tree.
-object_id
object the category tree is mapped to.
-assign_single_p
shows if the user will be allowed to assign multiple categories to objects or only a single one in this subtree.
-require_category_p
shows if the user will have to assign at least one category to objects.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::flush_cache (public)

 category_tree::flush_cache tree_id

Flushes category tree hierarchy cache of one category tree.

Parameters:
tree_id (required)
category tree to be flushed.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::flush_translation_cache (public)

 category_tree::flush_translation_cache tree_id

Flushes category tree translation cache of one category tree.

Parameters:
tree_id (required)
category tree to be flushed.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::get_categories (public)

 category_tree::get_categories -tree_id tree_id [ -locale locale ]

Return root categories of a given tree

Switches:
-tree_id (required)
-locale (optional)
sort results by name in specified locale. If a translation in this locale is not available, the one in en_US will be used. When missing, will default to locale of the connection or en_US when we are outside a connection context.
Returns:
list of category ids

Testcases:
category_tree_procs

category_tree::get_data (public)

 category_tree::get_data tree_id [ locale ]

Get category tree name, description and other data.

Parameters:
tree_id (required)
category tree to get the data of.
locale (optional)
language in which to get the name and description.
Returns:
array: tree_name description site_wide_p
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::get_id (public)

 category_tree::get_id name [ locale ]

Gets the id of a category tree given a name.

Parameters:
name (required)
the name of the category tree to retrieve
locale (optional, defaults to "en_US")
the locale in which the name is supplied
Returns:
the tree id or empty string if no category tree was found
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::get_id_by_object_title (public)

 category_tree::get_id_by_object_title [ -title title ]

Gets the id of a category_tree given an object title (object_type=category). This is highly useful as the category_tree object title will not change if you change the name (label) of the category_tree, so you can access the category_tree even if the label has changed. Why would you want this? E.g. if you have the category widget and want to get only one specific tree displayed and not all of them.

Switches:
-title (optional)
object title of the category to retrieve
Returns:
the category_tree_id or empty string if no category was found
Author:
Malte Sussdorff <malte.sussdorff@cognovis.de>

Testcases:
category_tree_procs

category_tree::get_mapped_trees (public)

 category_tree::get_mapped_trees object_id [ locale ]

Get the category trees mapped to an object.

Parameters:
object_id (required)
object to get the mapped category trees.
locale (optional)
language in which to get the name. [ad_conn locale] used by default.
Returns:
Tcl list of lists: tree_id tree_name subtree_category_id assign_single_p require_category_p
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::get_mapped_trees_from_object_list (public)

 category_tree::get_mapped_trees_from_object_list object_id_list \
    [ locale ]

Get the category trees mapped to a list of objects.

Parameters:
object_id_list (required)
list of object to get the mapped category trees.
locale (optional)
language in which to get the name. [ad_conn locale] used by default.
Returns:
Tcl list of lists: tree_id tree_name subtree_category_id assign_single_p require_category_p widget
Author:
Jade Rubick <jader@bread.com>

Testcases:
category_tree_procs

category_tree::get_multirow (public)

 category_tree::get_multirow [ -tree_id tree_id ] \
    [ -subtree_id subtree_id ] [ -assign_single_p assign_single_p ] \
    [ -require_category_p require_category_p ] \
    [ -container_id container_id ] \
    [ -category_counts category_counts ] [ -append ] \
    [ -datasource datasource ]

get a multirow datasource for a given tree or for all trees mapped to a given container. datasource is: tree_id tree_name category_id category_name level pad deprecated_p count child_sum where:

  • mapped_p indicates the category_id was found in the list mapped_ids.
  • child_sum is the naive sum of items mapped to children (may double count)
  • count is the number of items mapped directly to the given category
  • pad is a stupid hard coded pad for the tree (I think trees should use nested lists and css)
Here is an example of how to use this in adp: 
    <multiple name="categories">
      <h2>@categories.tree_name@</h2>
      <ul>
      <group column="tree_id">
        <if @categories.count@ gt 0 or @categories.child_sum@ gt 0>
          <li>@categories.pad;noquote@<a href="@categories.category_id@">@categories.category_name@</a>
          <if @categories.count@ gt 0>(@categories.count@)</if></li>
        </if>
      </group>
    </multiple>

Switches:
-tree_id (optional)
tree_id or container_id must be provided.
-subtree_id (optional)
-assign_single_p (optional, defaults to "f")
-require_category_p (optional, defaults to "f")
-container_id (optional)
returns all mapped trees for the given container_id
-category_counts (optional)
list of category_id and counts {catid count cat count ... }
-append (optional, boolean)
-datasource (optional)
the name of the datasource to create.
Author:
Jeff Davis davis@xarg.net

Testcases:
category_crud

category_tree::get_name (public)

 category_tree::get_name tree_id [ locale ]

Gets the category tree name in the given language, if available. Uses the default language otherwise.

Parameters:
tree_id (required)
category tree to get the name of.
locale (optional)
language in which to get the name. [ad_conn locale] used by default.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::get_translation (public)

 category_tree::get_translation tree_id [ locale ]

Gets the category tree name and description in the given language, if available. Uses the default language otherwise.

Parameters:
tree_id (required)
category tree to get the name and description of.
locale (optional)
language in which to get the name and description. [ad_conn locale] used by default.
Returns:
tcl-list: name description
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_import, category_crud

category_tree::get_tree (public)

 category_tree::get_tree [ -all ] [ -subtree_id subtree_id ] tree_id \
    [ locale ]

Get all categories of a category tree from the cache.

Switches:
-all (optional, boolean)
-subtree_id (optional)
Parameters:
tree_id (required)
category tree to get the categories of.
locale (optional)
language in which to get the categories. [ad_conn locale] used by default.
Options:
-all
Indicates that phased_out categories should be included.
-subtree_id
Return only categories of the given subtree.
Returns:
Tcl list of lists: category_id category_name deprecated_p level
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_crud

category_tree::get_trees (public)

 category_tree::get_trees object_id

Get the category trees mapped to an object.

Parameters:
object_id (required)
object to get the mapped category trees.
Returns:
Tcl list of tree_ids
Author:
Peter Kreuzinger <peter.kreuzinger@wu-wien.ac.at>

Testcases:
category_object_mapping

category_tree::import (public)

 category_tree::import -name name [ -description description ] \
    -categories categories [ -locale locale ] [ -user_id user_id ] \
    [ -creation_ip creation_ip ] [ -context_id context_id ]

Insert a new category tree with categories. Here is an example of how to use this in tcl: 

    set tree_id [category_tree::import -name regions -description {regions and states} -categories {
    1 europe
    2 germany
    2 {united kingdom}
    2 france
    1 asia
    2 china
    1 {north america}
    2 {united states}
    }]

Switches:
-name (required)
-description (optional)
-categories (required)
-locale (optional)
-user_id (optional)
-creation_ip (optional)
-context_id (optional)
Options:
-name
tree name.
-description
tree description.
-categories
Tcl list of levels and category_names.
-locale
locale of the language. [ad_conn locale] used by default.
-user_id
user that adds the category tree. [ad_conn user_id] used by default.
-creation_ip
ip-address of the user that adds the category tree. [ad_conn peeraddr] used by default.
-context_id
context_id of the category tree. [ad_conn package_id] used by default.
Returns:
tree_id
Authors:
Jeff Davis
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_import

category_tree::map (public)

 category_tree::map -tree_id tree_id -object_id object_id \
    [ -subtree_category_id subtree_category_id ] \
    [ -assign_single_p assign_single_p ] \
    [ -require_category_p require_category_p ] [ -widget widget ]

Map a category tree to a package (or other object).

Switches:
-tree_id (required)
-object_id (required)
-subtree_category_id (optional)
-assign_single_p (optional, defaults to "f")
-require_category_p (optional, defaults to "f")
-widget (optional)
Options:
-tree_id
category tree to be mapped.
-object_id
object to map the category tree to.
-subtree_category_id
category_id of the subtree to be mapped. If not provided, the whole category tree will be mapped.
-assign_single_p
shows if the user will be allowed to assign multiple categories to objects or only a single one in this subtree.
-require_category_p
shows if the user will have to assign at least one category to objects.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::reset_cache (public)

 category_tree::reset_cache

Reloads all category tree hierarchies in the cache.

Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_crud

category_tree::reset_translation_cache (public)

 category_tree::reset_translation_cache

Reloads all category tree translations in the cache.

Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_init_procs

category_tree::unmap (public)

 category_tree::unmap -tree_id tree_id -object_id object_id

Unmap a category tree from a package (or other object) Note: This will not delete existing categorizations of objects.

Switches:
-tree_id (required)
-object_id (required)
Options:
-tree_id
category tree to be unmapped.
-object_id
object to unmap the category tree from.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs

category_tree::update (public)

 category_tree::update -tree_id tree_id -name name \
    [ -description description ] [ -site_wide_p site_wide_p ] \
    [ -locale locale ] [ -user_id user_id ] \
    [ -modifying_ip modifying_ip ]

Updates / inserts a category tree translation.

Switches:
-tree_id (required)
-name (required)
-description (optional)
-site_wide_p (optional, defaults to "f")
-locale (optional)
-user_id (optional)
-modifying_ip (optional)
Options:
-tree_id
tree_id of the category tree to be updated.
-locale
locale of the language. [ad_conn locale] used by default.
-name
tree name.
-description
description of the category tree.
-user_id
user that adds the category tree. [ad_conn user_id] used by default.
-modifying_ip
ip-address of the user that updated the category tree. [ad_conn peeraddr] used by default.
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_crud, category_tree_procs

category_tree::usage (public)

 category_tree::usage tree_id

Gets all package instances using a category tree.

Parameters:
tree_id (required)
category tree to get the using packages for.
Returns:
Tcl list of lists: package_pretty_plural object_id object_name package_id instance_name read_p
Author:
Timo Hentschel <timo@timohentschel.de>

Testcases:
category_tree_procs
[ show source ]