Index: openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp 27 Oct 2014 16:39:15 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/guide/keywords.adp 7 Aug 2017 23:47:47 -0000 1.3 @@ -1,37 +1,49 @@ -{/doc/acs-content-repository {Content Repository}} {Content Repository Developer Guide: Subject Keywords +{/doc/acs-content-repository {ACS Content Repository}} {Content Repository Developer Guide: Subject Keywords (Categories)} Content Repository Developer Guide: Subject Keywords (Categories) - - -

Subject Keywords (Categories)

Overview

+

Subject Keywords (Categories)

+ +Content Repository : Developer +Guide +
+

Overview

+

Subject Keywords are used to implement categorization for the Content Management system. A Subject Keyword is a small -label, such as "Oracle Documentation" or "My Favorite Foods", which -can be associated with any number of content items. Thus, content -items may be grouped by arbitrary categories. For example, -assigning the Subject Keyword "My Favorite Foods" to the content -items "Potstickers", "Strawberries" and "Ice Cream" would indicate +label, such as "Oracle Documentation" or "My +Favorite Foods", which can be associated with any number of +content items. Thus, content items may be grouped by arbitrary +categories. For example, assigning the Subject Keyword "My +Favorite Foods" to the content items "Potstickers", +"Strawberries" and "Ice Cream" would indicate that all the three items belong in the same category - namely, the -category of the user's favorite foods. The actual physical location -of these items within the repository is irrelevant.

Subject Keywords may be nested to provide more detailed control -over categorization; for example, "My Favorite Foods" may be -further subdivided into "Healthy" and "Unhealthy". Subject Keywords -which have descendants are referred to as "Subject -Categories".

Data Model

The content_keyword object type is used to represent -Subject Keywords (see content_keyword.sql) The -content_keyword type inherits from -acs_object:

+category of the user's favorite foods. The actual physical
+location of these items within the repository is irrelevant.

+
Subject Keywords may be nested to provide more detailed control
+over categorization; for example, "My Favorite Foods" may
+be further subdivided into "Healthy" and
+"Unhealthy". Subject Keywords which have descendants are
+referred to as "Subject Categories".

+
Data Model

+
The content_keyword object type is used to represent
+Subject Keywords (see content_keyword.sql) The
+content_keyword type inherits from
+acs_object:

+
  acs_object_type.create_type ( supertype => 'acs_object', object_type
    => 'content_keyword', pretty_name => 'Content Keyword',
    pretty_plural => 'Content Keywords', table_name => 'cr_keywords',
    id_column => 'keyword_id', name_method => 'acs_object.default_name'
    ); 
 

-In addition, the cr_keywords table (see
-content-create.sql) contains extended attributes of
+
+In addition, the cr_keywords
+ table (see
+content-create.sql
+) contains extended attributes of
 Subject Keywords:
 
 create table cr_keywords (
@@ -44,7 +56,9 @@
   description            varchar2(4000)
 );
 

-In content-keyword.sql:
+
+In content-keyword.sql
+:
 
 attr_id := acs_attribute.create_attribute (
   object_type    => 'acs_object',
@@ -61,11 +75,15 @@
   pretty_name    => 'Description',
   pretty_plural  => 'Descriptions'
 );
-
Thus, each Subject Keyword has a heading, which is a
-user-readable heading for the keyword, and a description,
-which is a somewhat longer description of the keyword.
The cr_item_keyword_map table (see
-content-create.sql) is used to relate content items to
-keywords:
+

+
Thus, each Subject Keyword has a heading, which is a
+user-readable heading for the keyword, and a
+description, which is a somewhat longer description of
+the keyword.

+
The cr_item_keyword_map table (see
+content-create.sql) is used to relate content items to
+keywords:

+
 create table cr_item_keyword_map (
   item_id          integer
                    constraint cr_item_keyword_map_item_fk
@@ -80,19 +98,22 @@
   constraint cr_item_keyword_map_pk
   primary key (item_id, keyword_id)
 );
-

-API Access
The API used to access and modify content keywords are outlined
+
+

+API Access

+

The API used to access and modify content keywords are outlined below. The function names are links that will take you to a more -detailed description of the function and its parameters.

+detailed description of the function and its parameters.

+
- -
Function/ProcedurePurposeDescription
newCreate a new Subject KeywordThis is a standard new function, used to create a new -Subject Keyword. If the parent id is specified, the new keword +newCreate a new Subject KeywordThis is a standard new function, used to create a +new Subject Keyword. If the parent id is specified, the new keword becomes a child of the parent keyword (which may now be called a Subject Category)
deleteDelete a Subject KeywordThis is a standard delete function, used to delete a +deleteDelete a Subject KeywordThis is a standard delete function, used to delete a Subject Keyword
@@ -106,25 +127,28 @@ Assign Keywords to ItemsThese functions should be used to assign Subject Keywords to content items, to unassign keywords from items, and to determine whether a particular keyword is assigned to an item. -

The is_assigned function can be used to determine if a -keyword matches a content item, based on the recurse +

The is_assigned function can be used to determine if +a keyword matches a content item, based on the recurse parameter:

    -
  • If recurse is set to 'none', -is_assigned will return 't' if and only if there -is an exact assignment of the keyword to the item.
  • If recurse is set to 'down', -is_assigned will return 't' if there is an exact -assignment of the keyword to the item, or if a narrower keyword is -assigned to the item. For example, a query whether "Potstickers" is -assigned the category "My Favorite Foods" will return 't' -even if "Potstickers" is only assigned the category "Healthy".
  • If recurse is set to 'up', -is_assigned will return 't' if there is an exact -assignment of the keyword to the item, or if a broader Subject -Category is assigned to the item. For example, a query whether -"Potstickers" is assigned the category "Healthy" will return -'t' even if "Potstickers" is assigned the broader category -"My Favorite Foods".
    • +
  • If recurse is set to 'none', +is_assigned will return 't' if and +only if there is an exact assignment of the keyword to the +item.
  • If recurse is set to 'down', +is_assigned will return 't' if there +is an exact assignment of the keyword to the item, or if a narrower +keyword is assigned to the item. For example, a query whether +"Potstickers" is assigned the category "My Favorite +Foods" will return 't' even if +"Potstickers" is only assigned the category +"Healthy".
  • If recurse is set to 'up', +is_assigned will return 't' if there +is an exact assignment of the keyword to the item, or if a broader +Subject Category is assigned to the item. For example, a query +whether "Potstickers" is assigned the category +"Healthy" will return 't' even if +"Potstickers" is assigned the broader category "My +Favorite Foods".
-