Index: openacs-4/contrib/packages/bcms/tcl/bcms-item-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/contrib/packages/bcms/tcl/bcms-item-procs.tcl,v
diff -u -r1.12 -r1.13
--- openacs-4/contrib/packages/bcms/tcl/bcms-item-procs.tcl	3 Nov 2003 14:08:11 -0000	1.12
+++ openacs-4/contrib/packages/bcms/tcl/bcms-item-procs.tcl	11 Nov 2003 16:34:20 -0000	1.13
@@ -78,13 +78,12 @@
     if {![info exists creation_user_id]} { set creation_user_id [ad_conn user_id] }
     if {![info exists creation_ip]} { set creation_ip [ad_conn peeraddr] }
 
-    set item_id [db_exec_plsql create_link "SQL"]
+    set item_id [db_exec_plsql create_link {}]
     ns_log Debug "bcms::item::create_link created new link $item_id to $target_id"
     return $item_id
 }
 
 
-#TODO: use the views to update
 ad_proc -public bcms::item::set_item {
     {-item_id:required}
     {-name}
@@ -98,10 +97,10 @@
 } {
 
     if [info exists name] {
-        db_dml update_name "SQL"
+        db_dml update_name {}
     }
     if [info exists parent_id] {
-        db_exec_plsql update_parent "SQL"
+        db_exec_plsql update_parent {}
     }
 
 }
@@ -117,7 +116,7 @@
 
     @returns 0 if successful.  
 } {
-    return [db_exec_plsql delete_item "SQL"]
+    return [db_exec_plsql delete_item {}]
 }
 
 
@@ -126,7 +125,6 @@
     {-revision latest}
     {-multirow_name bcms_list_items}
     {-return_list:boolean false}
-    {-additional_columns}
     {-orderby "item_id asc"}
     {-show_only}
 } {
@@ -137,29 +135,25 @@
     @param multirow_name        you can supply your own multirow name
     @param return_list          if supplied a list of ns_sets otherwise it
                                 returns a multirow uses the multirow_name if given
-    @param additional_columns   to be returned with the results
+    @param show_only            ids of the item to show only, normally this used in conjuction with
+                                list builder and paginator
      
     @returns rows of content items below the parent_id
     with the following columns:
 
     item_id, name, live_revision, latest_revision, publish_status, 
-    content_type, storage_type, tree_sortkey, title, description
+    content_type, storage_type, tree_sortkey, last_modified, title, description
 
 } {
     # TODO: make use of db_map... 
 
     # initialize the addtionals we will use
     set addtnl_where_list [list]
     set addtnl_where_folder_list [list]
-    if {[info exists additional_columns]} {
-        set addtnl_select_list $additional_columns
-    } else {
-        set addtnl_select_list [list]
-    }
+    set addtnl_select_list [list]
 
     # if additional revision data must be returned, set the additional columns here
     # for revisions.
-
     set addtnl_from ""
 
     switch -exact $revision {
@@ -202,10 +196,10 @@
 
     if {$return_list_p} {
         # return a list of lists since its not easy to pass multirow from proc to proc
-        return [db_list_of_ns_sets get_items "SQL"]
+        return [db_list_of_ns_sets get_items {}]
     } else {
         # make a multirow, it is likely that this proc is not being called from another proc
-        db_multirow $multirow_name get_items "SQL"
+        db_multirow $multirow_name get_items {}
     }
 
 }
@@ -222,6 +216,9 @@
     both are complex i haven't decided if making them into one and
     adding more complexity to list_items is good, once this proves to be ok and
     fast enough then I will merge the 2 api.
+
+    TODO: it seems i am not using this lately must review and to look more like
+    bcms::folder::tree_folders
 } {
     # initialize the addtional where we will use
     set addtnl_where_list [list]
@@ -272,29 +269,36 @@
 
     if {$return_list_p} {
         # return a list of lists since its not easy to pass multirow from proc to proc
-        return [db_list_of_ns_sets get_items "SQL"]
+        return [db_list_of_ns_sets get_items {}]
     } else {
         # make a multirow, it is likely that this proc is not being called from another proc
         if ![info exists multirow_name] { set multirow_name bcms_list_items }
-        db_multirow $multirow_name get_items "SQL"
+        db_multirow $multirow_name get_items {}
     }
 }
 
 ad_proc -public bcms::item::list_related_items {
     {-item_id:required}
     {-relation_tag:required}
-    {-multirow_name}
+    {-multirow_name bcms_list_related_items}
     {-revision}
     {-return_list:boolean false}
 } {
-    get the related items of item_id.  it returns the following columns
+    get the related items of item_id.  
 
-    item_id, name, live_revision, latest_revision, publish_status, 
-    content_type, storage_type, level, parent_level, rel_id, order_n
+    @param item_id        the item you want to check the relations with
+    @param relation_tag   what type of relationship to the item you want it to list
+    @param multirow_name  you can supply your own multirow name
+    @param return_list    if supplied a list of ns_sets otherwise it
+                          returns a multirow uses the multirow_name if given
+    @param revision       will only returns items that have live or latest revision under the parent_id
+                          if this is used additional info are returned such as revision_id, title, description, publish_date
 
-    -revision will only returns items that have live or latest revision under the parent_id
-    if this is used additional info are returned such as revision_id, title, description, publish_date
+    @returns the following columns
 
+    item_id, name, live_revision, latest_revision, publish_status, 
+    content_type, storage_type, rel_id, order_n, path
+
 } {
     # initialize the addtional where we will use
     set addtnl_where_list [list]
@@ -327,11 +331,10 @@
 
     if {$return_list_p} {
         # return a list of lists since its not easy to pass multirow from proc to proc
-        return [db_list_of_ns_sets get_related_items "SQL"]
+        return [db_list_of_ns_sets get_related_items {}]
     } else {
         # make a multirow, it is likely that this proc is not being called from another proc
-        if ![info exists multirow_name] { set multirow_name bcms_list_related_items }
-        db_multirow $multirow_name get_related_items "SQL"
+        db_multirow $multirow_name get_related_items {}
     }
 
 }
@@ -419,8 +422,8 @@
                               properties are returned
 
     @returns an array that contains the following  
-    name, parent_id, live_revision, latest_revision, publish_status, content_type 
-    and storage_type
+    item_id, name, parent_id, live_revision, latest_revision, publish_status, content_type,
+    storage_type
 
     if "-revision live" or "-revision lastest" is given then the details of the
     live or lastest revision is also place inside the array.  The additional
@@ -469,90 +472,7 @@
     }
 }
 
-# TODO move this out, this is too specific
-ad_proc -public bcms::item::list_pages {
-    {-parent_id:required}
-    {-revision latest}
-    {-multirow_name}
-    {-return_list:boolean false}
-} {
-    returns a list of pages under the parent_id.  it also gets the latest
-    or live pages with index name on the folder under parent_id. if revision
-    is not specified then we will just get the folder label
 
-    returns item_id, name, publish_status, content_type, storage_type, title
-
-    TODO: will need to merge this with list_items
-    I think we really need to rethink what this proc really want to do,
-    confusing proc, gets pages and folders, get live... latest etc.
-} {
-    switch -exact $revision {
-        latest { 
-            set addtnl_select ", bcms__get_title(i.item_id, 'latest') as title, content_folder__get_label(i.item_id) as folder_label" 
-        }
-        live { 
-            set addtnl_select ", bcms__get_title(i.item_id, 'live') as title, content_folder__get_label(i.item_id) as folder_label" 
-        }
-        default { 
-            ns_log debug "bcms: revision requested not valid" 
-            return
-        }
-    }
-
-    if {$return_list_p} {
-        # return a list of lists since its not easy to pass multirow from proc to proc
-        return [db_list_of_ns_sets get_pages "SQL"]
-    } else {
-        # make a multirow, it is likely that this proc is not being called from another proc
-        if ![info exists multirow_name] { set multirow_name bcms_list_pages }
-        db_multirow $multirow_name get_pages "SQL"
-    }
-
-}
-
-
-# TODO move this out, this is too specific
-ad_proc -public bcms::item::list_images {
-    {-parent_id:required}
-    {-live_items:boolean false}
-    {-level_diff 0}
-    {-multirow_name}
-    {-return_list:boolean false}
-} {
-    list the images related to a content item which is the parent_id
-} {
-    if {$return_list_p} {
-        # return a list of lists since its not easy to pass multirow from proc to proc
-        return [list_items -parent_id $parent_id -content_type image -level_diff $level_diff -return_list]
-    } else {
-        # make a multirow, it is likely that this proc is not being called from another proc
-        if ![info exists multirow_name] { set multirow_name bcms_list_images }
-        list_items -parent_id $parent_id -content_type image -level_diff $level_diff -multirow_name $multirow_name
-    }
-
-}
-
-# TODO move this out, this is too specific
-ad_proc -public bcms::item::list_files {
-    {-parent_id:required}
-    {-live_items:boolean false}
-    {-level_diff 0}
-    {-multirow_name}
-    {-return_list:boolean false}
-} {
-    list the files related to a content item which is the parent_id
-} {
-    if {$return_list_p} {
-        # return a list of lists since its not easy to pass multirow from proc to proc
-        return [list_items -parent_id $parent_id -content_type bcms_file -level_diff $level_diff -return_list]
-    } else {
-        # make a multirow, it is likely that this proc is not being called from another proc
-        if ![info exists multirow_name] { set multirow_name bcms_list_files }
-        list_items -parent_id $parent_id -content_type bcms_file -level_diff $level_diff -multirow_name $multirow_name
-    }
-
-}
-
 ad_proc -public bcms::item::relate_item {
     {-relation_tag:required}
     {-item_id:required}
@@ -562,6 +482,15 @@
 } {
     relate item_id to related_object_id with relation_type
 
+    @param relation_tag        what relationship tag item_id and related_object_id will have, you have to register the relation_tag
+                               between the object type of item_id and related_object_id if they are custom content types
+    @param item_id             id of the item you wish to put a relation to.
+    @param related_object_id   id of the item/object you wish to have relation with.
+    @param order_n             order of the relation, you can have 1 to many relation.  the order of this relation.
+    @param relation_type LARS HELP NEEDED
+
+    @returns LARS HELP NEEDED
+
 } {
     return [db_exec_plsql relate_item {}]
 }
@@ -570,10 +499,14 @@
     {-rel_id:required}
 } {
     unrelate an item
+
+    @param rel_id   the relationship id you wish to break/unrelate
 } {
-    return [db_exec_plsql unrelate_item "SQL"]
+    return [db_exec_plsql unrelate_item {}]
 }
 
+
+# TODO: remove this?  too pg specific?
 ad_proc -public bcms::item::get_sortkeys {
     {-item_id:required}
 } {
@@ -583,30 +516,34 @@
 
     array set sortkeys {}
 
-    db_1row get_currentkey "SQL"
+    db_1row get_currentkey {}
     set sortkeys(current_sortkey) $current_sortkey
 
-    set sortkeys(next_sortkey) [db_string get_nextkey "SQL" -default {}]
-    set sortkeys(prev_sortkey) [db_string get_prevkey "SQL" -default {}]
+    set sortkeys(next_sortkey) [db_string get_nextkey {} -default {}]
+    set sortkeys(prev_sortkey) [db_string get_prevkey {} -default {}]
 
     return [array get sortkeys]
 
 }
 
 
-
 ad_proc -public bcms::item::format_string_as_url {
-	{-url:required}
+	{-string:required}
     {-truncate 10}
 } {
 	trim the string to format as url
+
+    @param string     the string to format
+    @param truncate   if the string is long truncate at what point
+
+    @returns the url friendly transformed string
 } {
-	set url [string trim $url]
-    regsub -all " " $url "" url
-   	regsub -all {([^a-zA-Z0-9])} $url "" url
+	set string [string trim $string]
+    regsub -all " " $string "" string
+   	regsub -all {([^a-zA-Z0-9])} $string "" string
     
     
-    return [string range [string tolower $url] 0 $truncate]
+    return [string range [string tolower $string] 0 $truncate]
 }
 
 ad_proc -public bcms::item::is_item_duplicate_p {
@@ -634,14 +571,23 @@
     return $duplicate_p 
 }
 
-ad_proc -public bcms::item::item_url_duplicate_test {
+ad_proc -public bcms::item::create_unique_url {
     {-url:required}    
     {-root_id:required}
     {-count 10}
 } {
 	this eliminates the chance of having dupplicate pages
-        it checks if url exists, if it does it then pads a 1 after url
+    it checks if url exists, if it does it then pads a number after url
+
+    @param url      the url to check
+    @param root_id  start the checking from which root_id/folder_id
+    @param count    pad a number up to how many times if there is a duplicate
+
+    @returns a none duplicate url
+
 } {
+    set url [bcms::item::format_string_as_url -string $url]
+
 	set ctr 0  	
    	while { ([bcms::item::is_item_duplicate_p -url $url -root_id $root_id] > 0) && ($ctr <= $count) } {
         set url "${url}1"          
@@ -687,9 +633,9 @@
     }
 
     if {$return_list_p} {
-        return [db_list_of_ns_sets get_item_path "SQL"]
+        return [db_list_of_ns_sets get_item_path {}]
     } else {
-        db_multirow $multirow_name get_item_path "SQL"
+        db_multirow $multirow_name get_item_path {}
     }
 }
 
@@ -698,29 +644,27 @@
    {-category_id:required}
    {-item_id:required}
 } {
-
     categorize a content item to a category
 
     @param category_id    The keyword id of the category we map to
     @param item_id        The item id of the content item we map
 
 } {
-    return [db_exec_plsql assign_category "SQL"]
+    return [db_exec_plsql assign_category {}]
 }
 
 
 ad_proc -public bcms::item::unassign_category {
    {-category_id:required}
    {-item_id:required}
 } {
-
     removes map of a category to a content item
 
     @param category_id     The category id of the category we unmap to
     @param item_id         The item id of the content item we unmap
 
 } {
-    return [db_exec_plsql unassign_category "SQL"]
+    return [db_exec_plsql unassign_category {}]
 }
 
 
@@ -731,7 +675,7 @@
 
     @param item_id        The item id of the content item we unmap
 } {
-    db_list unassign_all_category "SQL"
+    db_list unassign_all_category {}
 }
 
 
@@ -746,5 +690,5 @@
     @returns category ids assigned to this item
 } {
 
-    return [db_list get_categories "SQL"]
+    return [db_list get_categories {}]
 }