Index: openacs-4/contrib/packages/bcms/tcl/bcms-folder-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/contrib/packages/bcms/tcl/bcms-folder-procs.tcl,v
diff -u -r1.1 -r1.2
--- openacs-4/contrib/packages/bcms/tcl/bcms-folder-procs.tcl	14 May 2003 15:34:59 -0000	1.1
+++ openacs-4/contrib/packages/bcms/tcl/bcms-folder-procs.tcl	4 Aug 2003 11:19:46 -0000	1.2
@@ -9,16 +9,19 @@
 
 namespace eval bcms::folder {}
 
-# for possible contribution
+
 ad_proc -public bcms::folder::get_cr_root_folder {} {
     Gets the CR Pages root, this is helpful as BCMS will always 
-    create its root from there. returns the folder_id of cr_folder's Pages root
+    create its root from there. 
+
+    @return the folder_id of cr_folder's Pages root
 } {
     return [db_string get_cr_root_folder "SQL"]
 }
 
+
 ad_proc -public bcms::folder::get_bcms_root_folder {} {
-    returns the BCMS folder_id based from the current package instance
+    @return the BCMS folder_id based from the current package instance
     if it is not setup properly it returns 0
 } {
     set bcms_root_folder [parameter::get -parameter root_folder_id -default 0]
@@ -30,16 +33,22 @@
     }
 }
 
-# for possible contribution - maybe we move this on CR's api
+
 ad_proc -public bcms::folder::create_folder {
     {-name:required}
     {-folder_label:required}
     {-parent_id:required}
     {-description ""}
 } {
-    creates a new folder in cr_folders a basic tcl wrapper 
-    for content_folder__new
-    returns the folder_id that was created
+    creates a new folder in cr_folders
+
+    @param name           name or url of the folder
+    @param folder_label   the label used for the folder, this is the human readable title of 
+                          the folder
+    @param parent_id      the folder_id of which this folder will become a subfolder
+    @param description    a description for this folder
+    
+    @return the folder_id that was created
 } {
     set folder_id [db_exec_plsql create_folder "SQL"]
     ns_log notice "bcms::folder::create_folder created folder $folder_id"
@@ -51,8 +60,11 @@
 ad_proc -public bcms::folder::delete_folder { 
     {-folder_id:required} 
 } {
-    deletes a cr_folder based from the folder_id, a tcl wrapper 
-    for content_folder__delete, if its unable to delete the folder
+    deletes a cr_folder based from the folder_id 
+
+    @param folder_id of folder you wish to delete
+    
+    @return 1 if its able to delete the folder otherwise
     it returns 0
 } {
     # TODO: test of we are catching the error message
@@ -72,7 +84,12 @@
     {-label}
     {-parent_id}
 } {
-    edits the folder
+    set/edits the folder properties.
+
+    @param folder_id    folder_id of the folder you wish to edit
+    @param name         edit the name of the folder
+    @param label        edit the label of the folder
+    @param parent_id    edit or basically move this folder to another folder
 } {
 
     set update_list [list]
@@ -99,9 +116,13 @@
 ad_proc -public bcms::folder::get_folder {
     {-folder_id:required}
 } {
-    the the properties of a folder
-    which are parent_id, name, label, description, has_child_folders, 
-    has_child_symlinks, package_id
+    gets the properties of a folder
+
+    @param folder_id you wish to get
+
+    @return an array with the following elments:  
+    parent_id, name, label, description, has_child_folders, has_child_symlinks, package_id
+    if no folder is found a blank array is returned
 } {
     if {[db_0or1row get_1folder "SQL" -column_array one_folder]} {
         return [array get one_folder]
@@ -111,127 +132,96 @@
 
 }
 
+# TODO: to be removed not a general proc
 ad_proc -public bcms::folder::get_image_folder { } {
     returns the folder_id of the image folder of this bcms instance
 } {
     array set one_item [bcms::item::get_item_by_url -root_id [get_bcms_root_folder] -url images -resolve_index false]
     return $one_item(item_id)
 }
 
+# TODO: to be removed not a general proc
 ad_proc -public bcms::folder::get_file_folder { } {
     returns the folder_id of the file folder of this bcms instance
 } {
     array set one_item [bcms::item::get_item_by_url -root_id [get_bcms_root_folder] -url files -resolve_index false]
     return $one_item(item_id)
 }
 
+# TODO: to be removed not a general proc
 ad_proc -public bcms::folder::get_page_folder { } {
     returns the folder_id of the page folder of this bcms instance
 } {
     array set one_item [bcms::item::get_item_by_url -root_id [get_bcms_root_folder] -url pages -resolve_index false]
     return $one_item(item_id)
 }
 
-# TODO: remove level_diff similar to bcms::item::list_items
+
 ad_proc -public bcms::folder::list_folders {
     {-parent_id}
-    {-level_diff 1}
-    {-multirow_name}
+    {-multirow_name bcms_list_folders}
     {-return_list:boolean false}
 } {
     returns a listing of the content folder under the parent_id, if
     no parent_id is provided the bcms root folder is used as the parent_id
 
-    returns this columns: folder_id, name, label, has_child_folders, level and parent_level
+    @param parent_id         lists the folders underneath this folder_id
+    @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
 
-    if -return_list is used it returns a list of ns_sets otherwise it
-    returns a multirow uses the multirow_name if given
-
-    -with_path return the relative path of items to the parent_id, adds path columns
-    that is returns
+    @return this columns: folder_id, name, parent_id, label, has_child_folders,
+    has_child_symlinks, package_id
 } {
-    # initialize the addtionals we will use
-    set addtnl_where_list [list]
-    set addtnl_select_list [list]
 
     if ![info exists parent_id] {
         # if the parent_id does not exists then start from the root
         set parent_id [get_bcms_root_folder]
     }
 
-    # TODO: make use of db_map... 
-    # check to see how deep we want to go
-    if {$level_diff != 0} {
-        lappend addtnl_where_list ":level_diff >= tree_level(i.tree_sortkey) - tree_level(p.tree_sortkey)"
-    }
-
-    # construct the additionals
-    if {[llength $addtnl_where_list] > 0} {
-        set addtnl_where "and [join $addtnl_where_list " and "]"
-    } else {
-        set addtnl_where ""
-    }
-    if {[llength $addtnl_select_list] > 0} {
-        set addtnl_select ", [join $addtnl_select_list ", "]"
-    } else {
-        set addtnl_select ""
-    }
-
     if $return_list_p {
         # return a list of lists
         return [db_list_of_ns_sets get_cr_folders "SQL"]
     } else {
         # make a multirow
-        if ![info exists multirow_name] { set multirow_name bcms_list_folders }
         db_multirow $multirow_name get_cr_folders "SQL"
     }
 }
 
 
 ad_proc -public bcms::folder::tree_folders {
     {-parent_id}
-    {-level_diff 0}
-    {-multirow_name}
+    {-prepend_path "./"}
+    {-multirow_name bcms_list_folders}
     {-return_list:boolean false}
 } {
-    similar to list_folders but also gives additional rows with ancestors, similar to item_lists_and_ancestors
+    similar to list_folders but also gives the subfolders underneath it
+    gives some more addtional columns 
 
-    returns the following columns: folder_id, name, label, has_child_folders,  level and parent_level
+    @param parent_id         gets the subfolder underneath this folder_id
+    @param prepend_path      you can add a string to prepend the path column
+    @param multirow_name     you can supply your own multirow name
+    @param return_list       if supplied it returns a list of ns_sets otherwise it
+                             returns a multirow uses the multirow_name if given
 
+    @return this columns: folder_id, name, parent_id, label, has_child_folders,
+    has_child_symlinks, package_id, level, parent_level, path
+
 } {
-    # initialize the addtionals we will use
-    set addtnl_where_list [list]
-    set addtnl_select_list [list]
+    #TODO we may need to optimze getting the path, we are currently using
+    #content_item__get_path (which is not that fast)
 
+
     if ![info exists parent_id] {
         # if the parent_id does not exists then start from the root
         set parent_id [get_bcms_root_folder]
     }
 
-    # TODO: make use of db_map... 
-    # check to see how deep we want to go
-    if {$level_diff != 0} {
-        lappend addtnl_where_list ":level_diff >= tree_level(i.tree_sortkey) - tree_level(p.tree_sortkey)"
-    }
-
-    # construct the additionals
-    if {[llength $addtnl_where_list] > 0} {
-        set addtnl_where "and [join $addtnl_where_list " and "]"
-    } else {
-        set addtnl_where ""
-    }
-    if {[llength $addtnl_select_list] > 0} {
-        set addtnl_select ", [join $addtnl_select_list ", "]"
-    } else {
-        set addtnl_select ""
-    }
-
     if $return_list_p {
         # return a list of lists
         return [db_list_of_ns_sets get_cr_folders "SQL"]
     } else {
         # make a multirow
-        if ![info exists multirow_name] { set multirow_name bcms_list_folders }
         db_multirow $multirow_name get_cr_folders "SQL"
     }