Index: openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-templating/www/doc/TclDocs/item.adp 27 Oct 2014 16:40:17 -0000 1.2 @@ -0,0 +1,332 @@ + +{/doc/acs-templating {Templating}} {} + + + + +

Namespace item

The item commands allow easy access to properties of +the content_item object. In the future, a unified API for caching +item properties will be developed here.

Also see:

+
namespace
publish
+

Method Summary

+Listing of public methods:
+item::content_is_null
item::content_methods_by_type
item::get_best_revision
item::get_content_type
item::get_extended_url
item::get_id
item::get_item_from_revision
item::get_live_revision
item::get_mime_info
item::get_publish_status
item::get_revision_content
item::get_template_id
item::get_template_url
item::get_title
item::get_url
item::is_publishable
+

Method Detail

+* indicates required

Public Methods:
+ +
item::content_is_null
+
Determines if the content for the revision is null (not +mereley zero-length)
+
+Parameters: + +
+revision_id* +The revision id
+
Returns:
1 if the content is null, 0 otherwise
+
+
+ +
item::content_methods_by_type
+
Determines all the valid content methods for +instantiating a content type. Possible choices are text_entry, +file_upload, no_content and xml_import. Currently, this proc merely +removes the text_entry method if the item does not have a text mime +type registered to it. In the future, a more sophisticated +mechanism will be implemented.
+
+Parameters: + +
+content_type* +The content type
+
Returns:
A Tcl list of all possible content methods
Options:
+ +
get_labelsReturn not just a list of types, but a list of +name-value pairs, as in the -options ATS switch for form +widgets
+
+
+ +
item::get_best_revision
+
Attempts to retrieve the live revision for the item. If +no live revision exists, attempts to retrieve the latest revision. +If the item has no revisions, returns an empty string.
+
+Parameters: + +
+item_id* +The item id
+
Returns:
The best revision id for the item, or an empty string if no +revisions exist
See Also:
proc - item::get_item_from_revision
item::get_live_revision
+
+
+
+ +
item::get_content_type
+
Retrieves the content type of tyhe item. If the item +does not exist, returns an empty string.
+
+Parameters: + +
+item_id* +The item id
+
Returns:
The content type of the item, or an empty string if no such +item exists
+
+
+ +
item::get_extended_url
+
Retrieves the relative URL of the item with a file +extension based on the item's mime_type (Example: { +/foo/bar/baz.html} ).
+
+Parameters: + +
+item_id* +The item id
+
Returns:
The relative URL of the item with the appropriate file +extension or an empty string on failure
Options:
+ + + + + +
template_extensionSignifies that the file extension should be +retrieved using the mime_type of the template assigned to the item, +not from the item itself. The live revision of the template is +used. If there is no template which could be used to render the +item, or if the template has no live revision, the extension +defaults to { .html}
revision_id +default the live revision; Specifies the +revision_id which will be used to retrieve the item's mime_type. +This option is ignored if the -template_extension option is +specified.
See Also:
proc - item::get_mime_info
item::get_template_id
item::get_url
+
+
+
+ +
item::get_id
+
Looks up the URL and gets the item id at that URL, if +any.
+
+Parameters: + + + + + +
+url* +The URL
root_folder +default The Sitemap; The ID of the root +folder to use for resolving the URL
+
Returns:
The item ID of the item at that URL, or the empty string on +failure
See Also:
proc - item::get_url
+
+
+
+ +
item::get_item_from_revision
+
Gets the item_id of the item to which the revision +belongs.
+
+Parameters: + +
+revision_id* +The revision id
+
Returns:
The item_id of the item to which this revision belongs
See Also:
proc - item::get_best_revision
item::get_live_revision
+
+
+
+ +
item::get_live_revision
+
Retrieves the live revision for the item. If the item +has no live revision, returns an empty string.
+
+Parameters: + +
+item_id* +The item id
+
Returns:
The live revision id for the item, or an empty string if no +live revision exists
See Also:
proc - item::get_best_revision
item::get_item_from_revision
+
+
+
+ +
item::get_mime_info
+
Creates a onerow datasource in the calling frame which +holds the mime_type and file_extension of the specified revision. +If the revision does not exist, does not create the +datasource.
+
+Parameters: + + + + + +
+revision_id* +The revision id
datasource_ref +default mime_info; The name of the +datasource to be created. The datasource will have two columns, +mime_type and file_extension. return 1 (one) if the revision +exists, 0 (zero) otherwise.
+
See Also:
proc - item::get_extended_url
+
+
+
+ +
item::get_publish_status
+
Get the publish status of the item. The publish status +will be one of the following: +
    +
  • +production - The item is still in production. The +workflow (if any) is not finished, and the item has no live +revision.
  • +ready - The item is ready for publishing
  • +live - The item has been published
  • +expired - The item has been published in the past, but +its publication has expired
    • +
+
+
+Parameters: + +
+item_id* +The item id
+
Returns:
The publish status of the item, or the empty string on +failure
See Also:
proc - item::is_publishable
+
+
+
+ +
item::get_revision_content
+
Create a onerow datasource called content in the +calling frame which contains all attributes for the revision +(including inherited ones). +

The datasource will contain a column called { text} , +representing the main content (blob) of the revision, but only if +the revision has a textual mime-type.

+
+
+Parameters: + +
+revision_id* +The revision whose attributes are to be +retrieved
+
Returns:
1 on success (and create a content array in the calling frame), +0 on failure
Options:
+ +
item_id +defaultauto-generated; The item_id +of the corresponding item.
See Also:
proc - item::get_content_type
item::get_mime_info
+
+
+
+ +
item::get_template_id
+
Retrieves the template which can be used to render the +item. If there is a template registered directly to the item, +returns the id of that template. Otherwise, returns the id of the +default template registered to the item's content_type. Returns an +empty string on failure.
+
+Parameters: + + + + + +
+item_id* +The item id
context +default 'public'; The context in which the +template will be used.
+
Returns:
The template_id of the template which can be used to render the +item, or an empty string on failure
See Also:
proc - item::get_template_url
+
+
+
+ +
item::get_template_url
+
Retrieves the relative URL of the template which can be +used to render the item. The URL is relative to the TemplateRoot as +it is specified in the ini file.
+
+Parameters: + + + + + +
+item_id* +The item id
context +default 'public'; The context in which the +template will be used.
+
Returns:
The template_id of the template which can be used to render the +item, or an empty string on failure
See Also:
proc - item::get_template_id
+
+
+
+ +
item::get_title
+
Get the title for the item. If a live revision for the +item exists, use the live revision. Otherwise, use the latest +revision.
+
+Parameters: + +
+item_id* +The item id
+
Returns:
The title of the item
See Also:
proc - item::get_best_revision
+
+
+
+ +
item::get_url
+
Retrieves the relative URL stub to th item. The URL is +relative to the page root, and has no extension (Example: { +/foo/bar/baz} ).
+
+Parameters: + +
+item_id* +The item id
+
Returns:
The relative URL to the item, or an empty string on +failure
See Also:
proc - item::get_extended_url
+
+
+
+ +
item::is_publishable
+
Determine if the item is publishable. The item is +publishable only if: +
    +
  • All child relations, as well as item relations, are satisfied +(according to min_n and max_n)
  • The workflow (if any) for the item is finished
    • +
+
+
+Parameters: + +
+item_id* +The item id
+
Returns:
1 if the item is publishable, 0 otherwise
+
+

+* indicates required

+