Index: openacs-4/packages/acs-content-repository/www/doc/api/item.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-content-repository/www/doc/api/item.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-content-repository/www/doc/api/item.adp 27 Oct 2014 16:39:14 -0000 1.2 +++ openacs-4/packages/acs-content-repository/www/doc/api/item.adp 7 Aug 2017 23:47:47 -0000 1.3 @@ -1,58 +1,73 @@ -{/doc/acs-content-repository {Content Repository}} {Package: content_item} +{/doc/acs-content-repository {ACS Content Repository}} {Package: content_item} Package: content_item - - -

content_item

-Content Repository : -content_item

content_item

+Content Repository : +content_item

Overview
Related Objects
API

Overview

Content items store the overview of the content published on a +

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

+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 +

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:
+
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
+ +

+
+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:
+
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)
+ +

+
+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)
@@ -65,18 +80,20 @@ -

Author: Karl Goldstein
root_folder_id: Starts path resolution from this folder. Defaults to the root of the sitemap
Declaration:
```
+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 +content_item.get_latest_revision +
Retrieves the id of the latest revision for the item (as opposed to the live revision)
@@ -85,17 +102,18 @@ null if no revisions exist
Author: Karl Goldstein
Parameters:
-
item_id: The item for which the latest revision is to be retrieved
Declaration:
+
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 +

+
+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.
@@ -104,33 +122,36 @@ if no live revision exists
Parameters:
-
item_id: The item for which the live revision is to be retrieved
Declaration:
+
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.
+

+
+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:
+
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 + +

+

Author:	Karl Goldstein
root_folder_id:		Starts path resolution from this folder. Defaults to the root of the sitemap

+Function: content_item.get_path +

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

@@ -143,18 +164,19 @@ -

Author:	Karl Goldstein	root_folder_id:		Starts path resolution from this folder. Defaults to the root of the sitemap

Declaration:


+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

+Function: content_item.get_publish_date +

Retrieves the publish date for the item

@@ -164,47 +186,52 @@ - + -

Author:	Karl Goldstein
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'	is_live:	If 't', use the live revision for the item. Otherwise, +use the latest revision. The default is 'f'

Declaration:


+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

+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: 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. + +

+

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 +given context, the default template for the item's type is returned.

@@ -215,24 +242,26 @@ - + -

Author:	Karl Goldstein
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'	use_context:	The context in the item is to be rendered, such as +'admin' or 'public'

Declaration:


+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 +

+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.

+the folder's label. In addition, this function will +automatically resolve symlinks.

@@ -241,22 +270,23 @@ - + -

Author:	Karl Goldstein
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'	is_live:	If 't', use the live revision to get the title. +Otherwise, use the latest revision. The default is 'f'

Declaration:


+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 +

+Function: content_item.get_virtual_path +

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

@@ -269,112 +299,119 @@ -

Author:	Michael Pih	root_folder_id:		Starts path resolution from this folder. Defaults to the root of the sitemap

Declaration:


+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. +

+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 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 +

+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' 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 + +

+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 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 +

+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 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.

+ +

+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.

@@ -392,47 +429,49 @@ - - + - + - + +simultaneously with the text parameter +Defaults to 'parent content type'-'child content +type' - - - -

Author:	Karl Goldstein
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 +	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	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	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'	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` +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_date:	As in `acs_object.new`
creation_ip:		As in `acs_object.new` +	creation_ip:	As in `acs_object.new`
creation_user:		As in `acs_object.new` +	creation_user:	As in `acs_object.new`

Declaration:


+Declaration:
 function new (
   name          in cr_items.name%TYPE,
   parent_id     in acs_objects.context_id%TYPE default null,
@@ -457,12 +496,14 @@
   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: 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, @@ -471,9 +512,11 @@ 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 + +

+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.
@@ -485,33 +528,37 @@ -
target_folder_id: The folder where the item is to be copied
Declaration:
```
+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, +

+
+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:
+
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 +

+
+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.
@@ -522,18 +569,20 @@ -

target_folder_id: The new folder for the item
Declaration:
```
+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.
+content_item.register_template +
Registers a template which will be used to render this item.
Author: Karl Goldstein
Parameters:
@@ -545,20 +594,22 @@ -
use_context: The context in which the template is appropriate, such as 'admin' or 'public'
Declaration:
+
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
+

+
+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:
@@ -567,35 +618,39 @@ -
name: The new name for the item, must be URL-encoded
Declaration:
+
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
+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:
+
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 +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.
@@ -608,17 +663,19 @@ -

end_when: The time and date when the item should be expired.
Declaration:
```
+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

target_folder_id:		The folder where the item is to be copied

target_folder_id:		The new folder for the item

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

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

@@ -631,34 +688,37 @@ -

Author:	Karl Goldstein	use_context:		The context in which the template is appropriate, such as 'admin' or 'public'

Declaration:


+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:


+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}
+  --    \@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
+
+
 
+
+Procedure: content_item.write_to_file
+Writes the content of the live revision of this item to a file,
+creating all the necessary directories in the process

 
 Author: Karl Goldstein
 
Parameters:

@@ -668,15 +728,19 @@
 
-root_path:    The path in the filesystem to which the root of the sitemap
 corresponds
 
Declaration:

+

Declaration:


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