## 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_labels` | Return 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_extension` | Signifies 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` | default auto-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