Package: content

Index: openacs-4/packages/acs-content-repository/www/doc/api/item.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/item.html,v diff -u -r1.3.18.1 -r1.3.18.2 --- openacs-4/packages/acs-content-repository/www/doc/api/item.html 9 Jun 2016 08:21:01 -0000 1.3.18.1 +++ openacs-4/packages/acs-content-repository/www/doc/api/item.html 22 Jun 2016 07:40:41 -0000 1.3.18.2 @@ -1,1394 +1,1394 @@ - - - Package: content_item - - - - -

content_item

-Content Repository : content_item -

- -

Overview
Related Objects
API

- - -

Overview

-Content items store the overview of the content published on a -website. The actual content is stored in content revisions. It is -implemented this way so that there can be mulitple versions of the -actual content while the main idea remains constant. For example: If -there is a review for the movie "Terminator," there will exist a -content item by the name "terminator" with all the right parameters -(supertype, parent, etc), there will also exist at least one content -revision pointing to this item with the actual review content. -

- -

Related Objects

-See also: content_revision, content_folder -

- - -

API

Function: content_item.get_content_type - -

Retrieve the content type of this item. Only objects of this type may be -used as revisions for the item. -

- - - - - - - - - - - - - -

Author: Karl Goldstein

Returns: The content type of the item

Parameters:

- -

- - - - -
item_id: The item for which the content type is to be retrieved -

Declaration:


-function get_content_type (
-  item_id     in cr_items.item_id%TYPE
-) return cr_items.content_type%TYPE;
-
-

- -

Function: content_item.get_context - -

Retrieve the parent of the given item -

- - - - - - - - - - - - - -

Author: Karl Goldstein

Returns: The id of the parent for this item

Parameters:

- -

- - - - -
item_id: The item for which the parent is to be retrieved -

Declaration:


-function get_context (
-  item_id	in cr_items.item_id%TYPE
-) return acs_objects.context_id%TYPE;
-
-

- -

Function: content_item.get_id - -

Takes in a path, such as "/tv/programs/star_trek/episode_203" -and returns the id of the item with this path. Note: URLs are abstract (no -extensions are allowed in content item names and extensions are stripped when -looking up content items) -

- - - - - - - - - - - - - - - -

Author: Karl Goldstein

Returns: The id of the item with the given path, or null if no such item exists

Parameters:

- -

- - - - - - - -
item_path: The path to be resolved -
root_folder_id: Starts path resolution from this folder. Defaults to -the root of the sitemap -

Declaration:


-function get_id (
-  item_path   in varchar2,
-  root_folder_id in cr_items.item_id%TYPE default c_root_folder_id
-) return cr_items.item_id%TYPE;
-
-

Parameters:
- - Not yet documented -
Declaration:
- `-function get_root_folder return cr_folders.folder_id%TYPE; - -` -

Parameters:
- - Not yet documented -
Declaration:
- `-function relate ( - item_id in cr_items.item_id%TYPE, - object_id in acs_objects.object_id%TYPE, - relation_tag in cr_type_relations.relation_tag%TYPE default 'generic', - order_n in cr_item_rels.order_n%TYPE default null, - relation_type in acs_object_types.object_type%TYPE default 'cr_item_rel' -) return cr_item_rels.rel_id%TYPE; - -` -

content_item

+Content Repository : content_item +

+ +

Overview
Related Objects
API

+ + +

Overview

+Content items store the overview of the content published on a +website. The actual content is stored in content revisions. It is +implemented this way so that there can be mulitple versions of the +actual content while the main idea remains constant. For example: If +there is a review for the movie "Terminator," there will exist a +content item by the name "terminator" with all the right parameters +(supertype, parent, etc), there will also exist at least one content +revision pointing to this item with the actual review content. +

+ +

Related Objects

+See also: content_revision, content_folder +

+ + +

API

Function: content_item.get_content_type + +

Retrieve the content type of this item. Only objects of this type may be +used as revisions for the item. +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The content type of the item

Parameters:

+ +

+ + + + +
item_id: The item for which the content type is to be retrieved +

Declaration:


+function get_content_type (
+  item_id     in cr_items.item_id%TYPE
+) return cr_items.content_type%TYPE;
+
+

+ +

Function: content_item.get_context + +

Retrieve the parent of the given item +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The id of the parent for this item

Parameters:

+ +

+ + + + +
item_id: The item for which the parent is to be retrieved +

Declaration:


+function get_context (
+  item_id	in cr_items.item_id%TYPE
+) return acs_objects.context_id%TYPE;
+
+

+ +

Function: content_item.get_id + +

Takes in a path, such as "/tv/programs/star_trek/episode_203" +and returns the id of the item with this path. Note: URLs are abstract (no +extensions are allowed in content item names and extensions are stripped when +looking up content items) +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The id of the item with the given path, or null if no such item exists

Parameters:

+ +

+ + + + + + + +
item_path: The path to be resolved +
root_folder_id: Starts path resolution from this folder. Defaults to +the root of the sitemap +

Declaration:


+function get_id (
+  item_path   in varchar2,
+  root_folder_id in cr_items.item_id%TYPE default c_root_folder_id
+) return cr_items.item_id%TYPE;
+
+

See Also:

content_item.get_path

+ +

Function: content_item.get_latest_revision + +

Retrieves the id of the latest revision for the item (as opposed to the live +revision) +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The id of the latest revision for this item, or null if no revisions +exist

Parameters:

+ +

+ + + + +
item_id: The item for which the latest revision is to be retrieved +

Declaration:


+function get_latest_revision (
+  item_id    in cr_items.item_id%TYPE
+) return cr_revisions.revision_id%TYPE;
+
+

See Also:

content_item.get_live_revision

+ +

Function: content_item.get_live_revision + +

Retrieves the id of the live revision for the item

+ +

Note that this function does nothing else besides retrieving + the value of the column cr_items.live_revision. It is + thus more efficient in many cases to join against + cr_items and retrieve the value directly.

+ + + + + + + + + + + + + +

Returns:

The id of the live revision for this item, or null if no live revision +exists

Parameters:

+ +

+ + + + +
item_id: The item for which the live revision is to be retrieved +

Declaration:


+function get_live_revision (
+  item_id   in cr_items.item_id%TYPE
+) return cr_revisions.revision_id%TYPE;
+
+

See Also:

content_item.set_live_revision, content_item.get_latest_revision

+ +

Function: content_item.get_parent_folder + +

Get the parent folder. +

+ + + + + + + + + + + + + +

Author:

Michael Pih

Returns:

the folder_id of the parent folder, null otherwise

Parameters:

+ +

+ + + + +
item_id: The item id +

Declaration:


+function get_parent_folder (
+  item_id	in cr_items.item_id%TYPE
+) return cr_folders.folder_id%TYPE;
+
+

+ +

Function: content_item.get_path + +

Retrieves the full path to an item, in the form of +"/tv/programs/star_trek/episode_203" +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The path to the item

Parameters:

+ +

+ + + + + + + +
item_id: The item for which the path is to be retrieved +
root_folder_id: Starts path resolution from this folder. Defaults to +the root of the sitemap +

Declaration:


+function get_path (
+  item_id        in cr_items.item_id%TYPE,
+  root_folder_id in cr_items.item_id%TYPE default c_root_folder_id
+) return varchar2;
+
+

See Also:

content_item.get_id, content_item.write_to_file

+ +

Function: content_item.get_publish_date + +

Retrieves the publish date for the item +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The publish date for the item, or null if the item has no revisions

Parameters:

+ +

+ + + + + + + +
item_id: The item for which the publish date is to be retrieved +
is_live: If 't', use the live revision for the item. Otherwise, use +the latest revision. The default is 'f' +

Declaration:


+function get_publish_date (
+  item_id    in cr_items.item_id%TYPE,
+  is_live    in char default 'f'
+) return cr_revisions.publish_date%TYPE;
+
+

See Also:

content_item.get_live_revision, content_item.get_latest_revision,

+ +

Function: content_item.get_revision_count + +

Return the total count of revisions for this item +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The number of revisions for this item

Parameters:

+ +

+ + + + +
item_id: The id the item +

Declaration:


+function get_revision_count (
+  item_id   in cr_items.item_id%TYPE
+) return number;
+
+

See Also:

content_revision.new

+ +

Function: content_item.get_root_folder + +
+ + + + + + + + + +
Parameters:
+ + Not yet documented +
Declaration:
+
+function get_root_folder return cr_folders.folder_id%TYPE; + +
+
+ +
+ +

+

Function: content_item.get_template + +

Retrieves the template which should be used to render this item. If no template +is registered to specifically render the item in the given context, the +default template for the item's type is returned. +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The id of the registered template, or null if no template could be +found

Parameters:

+ +

+ + + + + + + +
item_id: The item for which the template will be unregistered +
use_context: The context in the item is to be rendered, such +as 'admin' or 'public' +

Declaration:


+function get_template (
+  item_id     in cr_items.item_id%TYPE,
+  use_context in cr_item_template_map.use_context%TYPE
+) return cr_templates.template_id%TYPE;
+
+

See Also:

content_type.register_template, content_item.register_template,

+ +

Function: content_item.get_title + +

Retrieves the title for the item, using either the latest or the live revision. +If the specified item is in fact a folder, return the folder's label. +In addition, this function will automatically resolve symlinks. +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The title of the item

Parameters:

+ +

+ + + + + + + +
item_id: The item for which the title is to be retrieved +
is_live: If 't', use the live revision to get the title. Otherwise, +use the latest revision. The default is 'f' +

Declaration:


+function get_title (
+  item_id    in cr_items.item_id%TYPE,
+  is_live    in char default 'f'
+) return cr_revisions.title%TYPE;
+
+

See Also:

content_item.get_live_revision, content_item.get_latest_revision, +content_symlink.resolve

+ +

Function: content_item.get_virtual_path + +

Retrieves the virtual path to an item, in the form of +"/tv/programs/star_trek/episode_203" +

+ + + + + + + + + + + + + + + +

Author:

Michael Pih

Returns:

The virtual path to the item

Parameters:

+ +

+ + + + + + + +
item_id: The item for which the path is to be retrieved +
root_folder_id: Starts path resolution from this folder. Defaults to +the root of the sitemap +

Declaration:


+function get_virtual_path (
+  item_id        in cr_items.item_id%TYPE,
+  root_folder_id in cr_items.item_id%TYPE default c_root_folder_id
+) return varchar2;
+
+

See Also:

content_item.get_id, content_item.write_to_file, content_item.get_path

+ +

Function: content_item.is_index_page + +

Determine if the item is an index page for the specified folder. +The item is an index page for the folder if it exists in the +folder and its item name is "index". +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

't' if the item is an index page for the specified +folder, 'f' otherwise

Parameters:

+ +

+ + + + + + + +
item_id: The item id +
folder_id: The folder id +

Declaration:


+function is_index_page (
+  item_id   in cr_items.item_id%TYPE,
+  folder_id in cr_folders.folder_id%TYPE
+) return varchar2;
+
+

See Also:

content_folder.get_index_page

+ +

Function: content_item.is_publishable + +

Determines if an item is publishable. Publishable items must +meet the following criteria: + 1) for each child type, the item has n children, min_n < n < max_n + 2) for each relation type, the item has n relations, min_n < n < max_n + 3) any 'publishing_wf' workflows are finished +

+ + + + + + + + + + + + + +

Author:

Michael Pih

Returns:

't' if the item is publishable in it's present state, +Otherwise, returns 'f'

Parameters:

+ +

+ + + + +
item_id The: item ID of the potential parent +

Declaration:


+function is_publishable (
+  item_id		in cr_items.item_id%TYPE
+) return char;
+
+

+ +

Function: content_item.is_subclass + +

Determines if one type is a subclass of another. A class is always a subclass of +itself. +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

't' if the child class is a subclass of the superclass, 'f' otherwise

Parameters:

+ +

+ + + + + + + +
object_type: The child class +
supertype: The superclass +

Declaration:


+function is_subclass (
+  object_type in acs_object_types.object_type%TYPE,
+  supertype	in acs_object_types.supertype%TYPE
+) return char;
+
+

See Also:

acs_object_type.create_type

+ +

Function: content_item.is_valid_child + +

Determines if an item would be a valid child of another item by +checking if the parent allows children of the would-be child's +content type and if the parent already has n_max children of +that content type. +

+ + + + + + + + + + + + + +

Author:

Michael Pih

Returns:

't' if the item would be a valid child, 'f' otherwise

Parameters:

+ +

+ + + + + + + +
item_id The: item ID of the potential parent +
content_type The: content type of the potential child item +

Declaration:


+function is_valid_child (
+  item_id	in cr_items.item_id%TYPE,
+  content_type  in acs_object_types.object_type%TYPE
+) return char;
+
+

+ +

Function: content_item.new + +

Creates a new content item. If the data, title or text +parameters are specified, also creates a revision for the item. +

+ + + + + + + + + + + + + + + +

Author:

Karl Goldstein

Returns:

The id of the newly created item

Parameters:

+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
name:    The name for the item, must be URL-encoded. +If an item with this name already exists under the specified +parent item, an error is thrown +
parent_id:    The parent of this item, defaults to null +
item_id:    The id of the new item. A new id will be allocated if this +parameter is null +
locale:    The locale for this item, for use with Intermedia search +
item_subtype:    The type of the new item, defaults to 'content_item' +This parameter is used to support inheritance, so that +subclasses of content_item can call this function +to initialize the parent class +
content_type:    The content type for the item, defaults to +'content_revision'. Only objects of this type +may be used as revisions for the item +
title:    The user-readable title for the item, defaults to the item's +name +
description:    A short description for the item (4000 characters maximum) +
mime_type:    The file type of the item, defaults to 'text/plain' +
nls_language:    The language for the item, used for Intermedia search +
text:    The text content of the new revision, 4000 charcters maximum. +Cannot be specified simultaneously with the data +parameter +
data:    The blob content of the new revison. Cannot be specified +simultaneously with the text parameter +
relation_tag:    If a parent-child relationship is registered +for these content types, use this tag to + describe the parent-child relationship. Defaults +to 'parent content type'-'child content type' +
is_live:    If 't', the new revision will become live +
creation_date:    As in acs_object.new +
creation_ip:    As in acs_object.new +
creation_user:    As in acs_object.new +

Declaration:


+function new (
+  name          in cr_items.name%TYPE,
+  parent_id     in acs_objects.context_id%TYPE default null,
+  item_id	in acs_objects.object_id%TYPE default null,
+  locale        in cr_items.locale%TYPE default null,
+  creation_date	in acs_objects.creation_date%TYPE
+			   default sysdate,
+  creation_user	in acs_objects.creation_user%TYPE
+			   default null,
+  creation_ip	in acs_objects.creation_ip%TYPE default null,
+  item_subtype	in acs_object_types.object_type%TYPE
+                           default 'content_item',
+  content_type  in acs_object_types.object_type%TYPE
+                           default 'content_revision',
+  title         in cr_revisions.title%TYPE default null,
+  description   in cr_revisions.description%TYPE default null,
+  mime_type   	in cr_revisions.mime_type%TYPE default 'text/plain',
+  nls_language 	in cr_revisions.nls_language%TYPE default null,
+  text	        in varchar2 default null,
+  data	        in cr_revisions.content%TYPE default null,
+  relation_tag  in cr_child_rels.relation_tag%TYPE default null,
+  is_live       in char default 'f'
+) return cr_items.item_id%TYPE;
+
+

See Also:

acs_object.new

+ +

Function: content_item.relate + +

+ + + + + + + + + +

Parameters:

+ + Not yet documented +

Declaration:


+function relate (
+  item_id       in cr_items.item_id%TYPE,
+  object_id     in acs_objects.object_id%TYPE,
+  relation_tag in cr_type_relations.relation_tag%TYPE default 'generic',
+  order_n       in cr_item_rels.order_n%TYPE default null,
+  relation_type in acs_object_types.object_type%TYPE default 'cr_item_rel'
+) return cr_item_rels.rel_id%TYPE;
+
+

+ +

Procedure: content_item.copy + +

Copies the item to a new location, creating an identical item with no revisions +or associated workflow. If the target folder does +not exist, or if the folder already contains an item with the same name +as the given item, an error will be thrown. +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + + + + +
item_id: The item to be copied +
target_folder_id: The folder where the item is to be copied +

Declaration:


+procedure copy (
+  item_id		in cr_items.item_id%TYPE,
+  target_folder_id	in cr_folders.folder_id%TYPE
+);
+
+

See Also:

content_item.new, content_folder.new, content_item.move

+ +

Procedure: content_item.delete + +

Deletes the specified content item, along with any revisions, symlinks, +workflows, and template relations for the item. Use with caution - this +operation cannot be undone. +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + +
item_id: The id of the item to delete +

Declaration:


+procedure delete (
+  item_id	in cr_items.item_id%TYPE
+);
+
+

See Also:

acs_object.delete

+ +

Procedure: content_item.move + +

Move the specified item to a different folder. If the target folder does +not exist, or if the folder already contains an item with the same name +as the given item, an error will be thrown. +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + + + + +
item_id: The item to be moved +
target_folder_id: The new folder for the item +

Declaration:


+procedure move (
+  item_id		in cr_items.item_id%TYPE,
+  target_folder_id	in cr_folders.folder_id%TYPE
+);
+
+

See Also:

content_item.new, content_folder.new, content_item.copy

+ +

Procedure: content_item.register_template + +

Registers a template which will be used to render this item. +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + + + + + + + +
item_id:    The item for which the template will be registered +
template_id:    The template to be registered +
use_context:    The context in which the template is appropriate, such +as 'admin' or 'public' +

Declaration:


+procedure register_template (
+  item_id      in cr_items.item_id%TYPE,
+  template_id  in cr_templates.template_id%TYPE,
+  use_context  in cr_item_template_map.use_context%TYPE
+);
+
+

See Also:

content_type.register_template, content_item.unregister_template, +content_item.get_template

+ +

Procedure: content_item.edit_name + +

Renames the item. If an item with the specified name already exists +under this item's parent, an error is thrown +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + + + + +
item_id: The id of the item to rename +
name: The new name for the item, must be URL-encoded +

Declaration:


+procedure rename (
+  item_id	 in cr_items.item_id%TYPE,
+  name           in cr_items.name%TYPE
+);
+
+

See Also:

content_item.new

+ +

Procedure: content_item.set_live_revision + +

Make the specified revision the live revision for the item +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + +
revision_id: The id of the revision which is to become live +for its corresponding item +

Declaration:


+procedure set_live_revision (
+  revision_id   in cr_revisions.revision_id%TYPE,
+  publish_status in cr_items.publish_status%TYPE default 'ready'
+);
+
+

See Also:

content_item.get_live_revision

+ +

Procedure: content_item.set_release_period + +

Sets the release period for the item. This information may be +used by applications to update the publishing status of items +at periodic intervals. +

+ + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + + + + + + + +
item_id:    The id the item. +
start_when:    The time and date when the item should be released. +
end_when:    The time and date when the item should be expired. +

Declaration:


+procedure set_release_period (
+  item_id    in cr_items.item_id%TYPE,
+  start_when date default null,
+  end_when   date default null
+);
+
+

+ +

Procedure: content_item.unregister_template + +

Unregisters a template which will be used to render this item. +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + + + + + + + +
item_id:    The item for which the template will be unregistered +
template_id:    The template to be registered +
use_context:    The context in which the template is appropriate, such +as 'admin' or 'public' +

Declaration:


+procedure unregister_template (
+  item_id      in cr_items.item_id%TYPE,
+  template_id  in cr_templates.template_id%TYPE default null,
+  use_context  in cr_item_template_map.use_context%TYPE default null
+);
+
+

See Also:

content_type.register_template, content_item.register_template, +content_item.get_template

+ +

Procedure: content_item.unset_live_revision + +

+ + + + + + + + + +

Parameters:

+ + Not yet documented +

Declaration:


+procedure unset_live_revision (
+  --/** Set the live revision to null for the item
+  --    @author Michael Pih
+  --    @param item_id The id of the item for which to unset the live revision
+  --    @see {content_item.set_live_revision}
+  item_id      in cr_items.item_id%TYPE
+);
+
+

+ +

Procedure: content_item.write_to_file + +

Writes the content of the live revision of this item to a file, +creating all the neccessary directories in the process +

+ + + + + + + + + + + + + +

Author:

Karl Goldstein

Parameters:

+ +

+ + + + + + + +
item_id: The item to be written to a file +
root_path: The path in the filesystem to which the root of the +sitemap corresponds +

Declaration:


+procedure write_to_file (
+  item_id     in cr_items.item_id%TYPE,
+  root_path   in varchar2
+);
+
+

See Also:

content_item.get_path

+ +

+ + +Last Modified: $Id$ + + +

Parameters:
+ + Not yet documented +
Declaration:
+ `+function get_root_folder return cr_folders.folder_id%TYPE; + +` +