Index: openacs-4/packages/cms/tcl/item-procs.tcl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/cms/tcl/Attic/item-procs.tcl,v diff -u -r1.4 -r1.5 --- openacs-4/packages/cms/tcl/item-procs.tcl 11 Aug 2001 17:40:26 -0000 1.4 +++ openacs-4/packages/cms/tcl/item-procs.tcl 20 Aug 2001 04:35:41 -0000 1.5 @@ -12,20 +12,23 @@ namespace eval item {} -# @public get_live_revision -# -# Retrieves the live revision for the item. If the item has no live -# revision, returns an empty string. -# -# @param item_id The item id -# -# @return The live revision id for the item, or an empty string if no -# live revision exists -# @see proc item::get_best_revision -# @see proc item::get_item_from_revision -ad_proc item::get_live_revision { item_id } { +ad_proc -public item::get_live_revision { item_id } { + @public get_live_revision + + Retrieves the live revision for the item. If the item has no live + revision, returns an empty string. + + @param item_id The item id + + @return The live revision id for the item, or an empty string if no + live revision exists + @see proc item::get_best_revision + @see proc item::get_item_from_revision + +} { + template::query glr_get_live_revision live_revision onevalue " select live_revision from cr_items where item_id = :item_id" -cache "item_live_revision $item_id" @@ -39,21 +42,22 @@ } +ad_proc -public item::get_best_revision { item_id } { -# @public 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. -# -# @param item_id The item id -# -# @return The best revision id for the item, or an empty string if no -# revisions exist -# @see proc item::get_live_revision -# @see proc item::get_item_from_revision + @public 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. + + @param item_id The item id + + @return The best revision id for the item, or an empty string if no + revisions exist + @see proc item::get_live_revision + @see proc item::get_item_from_revision -ad_proc item::get_best_revision { item_id } { +} { template::query gbr_get_best_revision revision_id onevalue " select content_item.get_best_revision(:item_id) from dual " -cache "item_best_revision $item_id" @@ -62,36 +66,40 @@ } -# @public get_item_from_revision -# -# Gets the item_id of the item to which the revision belongs. -# -# @param revision_id The revision id -# -# @return The item_id of the item to which this revision belongs -# @see proc item::get_live_revision -# @see proc item::get_best_revision +ad_proc -public item::get_item_from_revision { revision_id } { -ad_proc item::get_item_from_revision { revision_id } { + @public get_item_from_revision + + Gets the item_id of the item to which the revision belongs. + + @param revision_id The revision id + + @return The item_id of the item to which this revision belongs + @see proc item::get_live_revision + @see proc item::get_best_revision + +} { template::query gifr_get_one_revision item_id onevalue " select item_id from cr_revisions where revision_id = :revision_id " -cache "item_from_revision $revision_id" return $item_id } -# @public 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"). -# -# @param item_id The item id -# -# @return The relative URL to the item, or an empty string on failure -# @see proc item::get_extended_url +ad_proc -public item::get_url { item_id } { -ad_proc item::get_url { item_id } { + @public 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"). + + @param item_id The item id + + @return The relative URL to the item, or an empty string on failure + @see proc item::get_extended_url +} { + # Get the path template::query gu_get_path item_path onevalue " select content_item.get_path(:item_id) from dual @@ -104,34 +112,37 @@ } } -# @public get_id -# -# Looks up the URL and gets the item id at that URL, if any. -# -# @param url The URL -# @param root_folder {default The Sitemap} -# The ID of the root folder to use for resolving the URL -# -# @return The item ID of the item at that URL, or the empty string -# on failure -# @see proc item::get_url -ad_proc item::get_id { url {root_folder ""}} { +ad_proc -public item::get_id { url {root_folder ""}} { + @public get_id + + Looks up the URL and gets the item id at that URL, if any. + + @param url The URL + @param root_folder {default The Sitemap} + The ID of the root folder to use for resolving the URL + + @return The item ID of the item at that URL, or the empty string + on failure + @see proc item::get_url + +} { + # Strip off file extension set last [string last "." $url] if { $last > 0 } { set url [string range $url 0 [expr $last - 1]] } - set sql [db_map gi_get_item_id_1] if { ![template::util::is_nil root_folder] } { - append sql [db_map gi_get_item_id_2] - } - append sql [db_map gi_get_item_id_3] + set root_sql ", :root_folder, 'f'" + } else { + set root_sql ", null, 'f'" + } # Get the path - template::query gi_get_item_id item_id onevalue $sql -cache "item_id $url $root_folder" + template::query id_get_item_id item_id onevalue "select content_item__get_id(:url $root_sql) from dual" -cache "item_id $url $root_folder" if { [info exists item_id] } { return $item_id @@ -140,22 +151,25 @@ } } -# @public 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. -# -# @param revision_id The revision id -# @param 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 proc item::get_extended_url -ad_proc item::get_mime_info { revision_id {datasource_ref mime_info} } { +ad_proc -public item::get_mime_info { revision_id {datasource_ref mime_info} } { + @public 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. + + @param revision_id The revision id + @param 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 proc item::get_extended_url + +} { + return [template::query gmi_get_mime_info mime_info onerow " select m.mime_type, m.file_extension @@ -169,18 +183,20 @@ } -# @public get_content_type -# -# Retrieves the content type of tyhe item. If the item does not exist, -# returns an empty string. -# -# @param item_id The item id -# -# @return The content type of the item, or an empty string if no such -# item exists +ad_proc -public item::get_content_type { item_id } { -ad_proc item::get_content_type { item_id } { + @public get_content_type + + Retrieves the content type of tyhe item. If the item does not exist, + returns an empty string. + + @param item_id The item id + + @return The content type of the item, or an empty string if no such + item exists +} { + template::query gct_get_content_type content_type onevalue " select content_type from cr_items where item_id = :item_id @@ -193,33 +209,36 @@ } } -# @public get_content_type -# -# Retrieves the relative URL of the item with a file extension based -# on the item's mime_type (Example: "/foo/bar/baz.html"). -# -# @param item_id The item id -# -# @option 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" -# -# @option 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. -# -# @return The relative URL of the item with the appropriate file extension -# or an empty string on failure -# @see proc item::get_url -# @see proc item::get_mime_info -# @see proc item::get_template_id -ad_proc item::get_extended_url { item_id args } { +ad_proc -public item::get_extended_url { item_id args } { + @public get_content_type + + Retrieves the relative URL of the item with a file extension based + on the item's mime_type (Example: "/foo/bar/baz.html"). + + @param item_id The item id + + @option 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" + + @option 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. + + @return The relative URL of the item with the appropriate file extension + or an empty string on failure + @see proc item::get_url + @see proc item::get_mime_info + @see proc item::get_template_id + +} { + set item_url [get_url $item_id] if { [template::util::is_nil item_url] } { @@ -278,24 +297,27 @@ return $file_url } -# @public 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. -# -# @param item_id The item id -# @param context {default 'public'} The context in which the template -# will be used. -# -# @return The template_id of the template which can be used to render the -# item, or an empty string on failure -# -# @see proc item::get_template_url -ad_proc item::get_template_id { item_id {context public} } { +ad_proc -public item::get_template_id { item_id {context public} } { + @public 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. + + @param item_id The item id + @param context {default 'public'} The context in which the template + will be used. + + @return The template_id of the template which can be used to render the + item, or an empty string on failure + + @see proc item::get_template_url + +} { + template::query gti_get_template_id template_id onevalue " select content_item.get_template(:item_id, :context) as template_id from dual" -cache "item_itemplate_id $item_id" @@ -307,23 +329,26 @@ } } -# @public 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. -# -# @param item_id The item id -# @param context {default 'public'} The context in which -# the template will be used. -# -# @return The template_id of the template which can be used to render the -# item, or an empty string on failure -# -# @see proc item::get_template_id -ad_proc item::get_template_url { item_id {context public} } { +ad_proc -public item::get_template_url { item_id {context public} } { + @public 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. + + @param item_id The item id + @param context {default 'public'} The context in which + the template will be used. + + @return The template_id of the template which can be used to render the + item, or an empty string on failure + + @see proc item::get_template_id + +} { + set template_id [get_template_id $item_id $context] if { [template::util::is_nil template_id] } { @@ -333,41 +358,47 @@ return [get_url $template_id] } -# @public content_is_null -# -# Determines if the content for the revision is null (not mereley -# zero-length) -# @param revision_id The revision id -# -# @return 1 if the content is null, 0 otherwise -ad_proc item::content_is_null { revision_id } { +ad_proc -public item::content_is_null { revision_id } { + + @public content_is_null + + Determines if the content for the revision is null (not mereley + zero-length) + @param revision_id The revision id + + @return 1 if the content is null, 0 otherwise + +} { template::query cin_get_content content_test onevalue " select 't' from cr_revisions where revision_id = :revision_id and content is not null" return [template::util::is_nil content_test] } -# @public 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. -# -# @param content_type The content type -# -# @option 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 -# -# @return A TCL list of all possible content methods -ad_proc item::content_methods_by_type { content_type args } { +ad_proc -public item::content_methods_by_type { content_type args } { + + @public 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. + + @param content_type The content type + + @option 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 + + @return A TCL list of all possible content methods + +} { template::util::get_opts $args @@ -400,28 +431,31 @@ return $methods } -# @public 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. -# -# @param revision_id The revision whose attributes are to be retrieved -# -# @option item_id {default auto-generated} The item_id of the -# corresponding item. -# -# @return 1 on success (and create a content array in the calling frame), -# 0 on failure -# -# @see proc item::get_mime_info -# @see proc item::get_content_type -ad_proc item::get_revision_content { revision_id args } { +ad_proc -public item::get_revision_content { revision_id args } { + @public 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. + + @param revision_id The revision whose attributes are to be retrieved + + @option item_id {default auto-generated} The item_id of the + corresponding item. + + @return 1 on success (and create a content array in the calling frame), + 0 on failure + + @see proc item::get_mime_info + @see proc item::get_content_type + +} { + template::util::get_opts $args if { [template::util::is_nil opts(item_id)] } { @@ -482,67 +516,77 @@ } -# @public is_publishable -# -# Determine if the item is publishable. The item is publishable only -# if: -#

-# -# @param item_id The item id -# -# @return 1 if the item is publishable, 0 otherwise -ad_proc item::is_publishable { item_id } { +ad_proc -public item::is_publishable { item_id } { + + @public is_publishable + + Determine if the item is publishable. The item is publishable only + if: + + + @param item_id The item id + + @return 1 if the item is publishable, 0 otherwise + +} { template::query ip_is_publishable_p is_publishable onevalue " select content_item.is_publishable(:item_id) from dual " -cache "item_is_publishable $item_id" return [string equal $is_publishable t] } -# @public get_publish_status -# -# Get the publish status of the item. The publish status will be one of -# the following: -# -# -# @param item_id The item id -# -# @return The publish status of the item, or the empty string on failure -# -# @see proc item::is_publishable -ad_proc item::get_publish_status { item_id } { +ad_proc -public item::get_publish_status { item_id } { + + @public get_publish_status + + Get the publish status of the item. The publish status will be one of + the following: + + + @param item_id The item id + + @return The publish status of the item, or the empty string on failure + + @see proc item::is_publishable + +} { + template::query gps_get_publish_status publish_status onevalue " select publish_status from cr_items where item_id = :item_id " -cache "item_publish_status $item_id" return $publish_status } -# @public 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. -# -# @param item_id The item id -# -# @return The title of the item -# -# @see proc item::get_best_revision -ad_proc item::get_title { item_id } { +ad_proc -public item::get_title { item_id } { + + @public 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. + + @param item_id The item id + + @return The title of the item + + @see proc item::get_best_revision + +} { template::query gt_get_title title onevalue " select content_item.get_title(:item_id) from dual " -cache "item_title $item_id"