--- loncom/interface/lonwishlist.pm	2010/08/16 13:37:41	1.3
+++ loncom/interface/lonwishlist.pm	2010/08/16 15:14:37	1.4
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Routines to control the wishlist
 #
-# $Id: lonwishlist.pm,v 1.3 2010/08/16 13:37:41 wenzelju Exp $
+# $Id: lonwishlist.pm,v 1.4 2010/08/16 15:14:37 wenzelju Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -26,7 +26,20 @@
 # http://www.lon-capa.org/
 #
 
+=pod
 
+=head1 NAME
+
+Apache::lonwishlist - Wishlist-Module
+  
+=head1 SYNOPSIS
+
+The wishlist offers a possibility to store links to resources from the resource-pool and external websites in a hierarchical list.
+It is only available for user with access to the resource-pool. The list can be structured by folders.
+
+The wishlist-module uses the CPAN-module "Tree" for easily handling the directory-structure of the wishlist. Each node in the tree has an index to be referenced by.
+
+=cut
 
 package Apache::lonwishlist;
 
@@ -49,6 +62,31 @@ my @allFolders;
 my @allNodes;
 my $indentConst = 20;
 
+=pod
+
+=head2 Routines for getting and putting the wishlist data from and accordingly to users data.
+
+=over 4
+
+=item * &getWishlist()
+
+     Get the wishlist-data via lonnet::dump() and returns the got data in a hash.
+
+
+=item * &putWishlist(wishlist)
+
+     Parameter is a reference to a hash. Puts the wishlist-data contained in the given hash via lonnet::put() to user-data.
+
+
+=item * &deleteWishlist()
+
+     Deletes all entries from the user-data for wishlist. Do this before putting in new data.
+
+
+=back
+
+=cut
+
 
 # Read wishlist from user-data
 sub getWishlist {
@@ -92,6 +130,57 @@ sub deleteWishlist {
 }
 
 
+=pod
+
+=head2 Routines for changing the directory struture of the wishlist.
+
+=over 4
+
+=item * &newEntry(title, path, note)
+
+     Creates a new entry in the wishlist containing the given informations. Additionally saves the date of creation in the entry.  
+
+
+=item * &deleteEntries(marked)
+
+     Parameter is a reference to an array containing the indices of all nodes that should be removed from the tree. 
+
+
+=item * &sortEntries(indexNode, at)
+
+     Changes the position of a node given by indexNode within its siblings. New position is given by at.
+
+
+=item * &moveEntries(indexNodesToMove, indexParent)
+
+     Parameter is a reference to an array containing the indices of all nodes that should be moved. indexParent specifies the node that will become the new Parent for these nodes. 
+
+
+=item * &setNewTitle(nodeindex, newTitle)
+
+     Sets the title for the node given by nodeindex to newTitle.
+
+
+=item * &setNewPath(nodeindex, newPath)
+
+     Sets the path for the node given by nodeindex to newPath.
+
+
+=item * &setNewNote(nodeindex, newNote)
+
+     Sets the note for the node given by nodeindex to newNote.     
+
+
+=item * &saveChanges()
+
+     Prepares the wishlist-hash to save it via &putWishlist(wishlist).   
+
+
+=back
+
+=cut
+
+
 # Create a new entry
 sub newEntry() {
     my ($title, $path, $note) = @_;
@@ -226,6 +315,40 @@ sub saveChanges {
 }
 
 
+=pod
+
+=head2 Routines for handling the directory structure
+
+=over 4
+
+=item * &getFoldersForOption(nodes)
+
+     Return the titles for all exiting folders in an option-tag, used to offer the users a possibility to create a new link or folder in an existing folder.
+     Recursive call starting with all children of the root of the tree (parameter nodes is reference to an array containing the nodes of the current level). 
+
+
+=item * &getfoldersOption()
+
+     Returns the option-tag build by &getFoldersForOption(nodes). Use it to transfer this to other modules (e.g. lonmenu.pm). 
+
+
+=item * &getFoldersToArray(children)
+
+     Puts all nodes that represent folders in the wishlist into an array. 
+     Recursive call starting with all children of the root of the tree (parameter nodes is reference to an array containing the nodes of the current level).     
+
+
+=item * &getNodesToArray(children)
+
+     Puts all existing nodes into an array (apart from the root node, because this one does not represent an entry in the wishlist).
+     Recursive call starting with all children of the root of the tree (parameter nodes is reference to an array containing the nodes of the current level).     
+ 
+
+ =back
+
+=cut
+
+
 # Return the names for all exiting folders in option-tags, so
 # a new link or a new folder can be created in an existing folder
 my $indent = 0;
@@ -294,6 +417,67 @@ sub getNodesToArray {
 }
 
 
+=pod
+
+=head2 Routines for the user-interface of the wishlist
+
+=over 4
+
+=item * &JSforWishlist()
+
+     Returns JavaScript-functions needed for wishlist actions like open and close folders.
+
+
+=item * &wishlistView(nodes)
+
+     Returns the table-HTML-markup for the wishlist in mode "view".
+     Recursive call starting with all children of the root of the tree (parameter nodes is reference to an array containing the nodes of the current level).     
+
+
+=item * &wishlistEdit(nodes)
+
+     Returns the table-HTML-markup for the wishlist in mode "edit".
+     Recursive call starting with all children of the root of the tree (parameter nodes is reference to an array containing the nodes of the current level).     
+
+
+=item * &wishlistMove(nodes, marked)
+
+     Returns the table-HTML-markup for the wishlist in mode "move". Highlights all entry "selected to move" contained in marked (reference to array).
+     Recursive call starting with all children of the root of the tree (parameter nodes is reference to an array containing the nodes of the current level).     
+
+
+=item * &wishlistImport(nodes)
+
+     Returns the table-HTML-markup for the wishlist in mode "import".
+     Recursive call starting with all children of the root of the tree (parameter nodes is reference to an array containing the nodes of the current level).     
+ 
+
+=item * &makePage(mode, marked)
+
+     Returns the HTML-markup for the whole wishlist depending on mode. If mode is "move" we need the marked entries to be highlighted a "selected to move". 
+     Calls &wishlistView(nodes), &wishlistEdit(nodes) or &wishlistMove(nodes, marked).
+ 
+
+=item * &makePageSet()
+
+     Returns the HTML-Markup for the page shown when a link was set by using the icon when viewing a resource.
+
+
+=item * &makePageImport()
+
+     Returns the HTML-Markup for the page shown when links should be imported into courses.
+ 
+
+=item * &makeErrorPage ()
+
+     Returns the HTML-Markup for an error-page shown if the wishlist could not be loaded.
+ 
+
+=back
+
+=cut
+
+
 # Return a script-tag containing Javascript-function
 # needed for wishlist actions like 'new link' ect.
 sub JSforWishlist {
@@ -1243,10 +1427,7 @@ sub makePage {
                                                         'onload' => 'javascript:onLoadAction('."'".$mode."'".');',
                                                         'onunload' => 'javascript:window.name = '."'loncapaclient'"}});
 
-    my $breadcrumbs = &Apache::lonhtmlcommon::breadcrumbs('Wishlist '.
-                           '<a title="Online-Hilfe" href="/adm/help/Wishlist.hlp" target="_top">'.
-                           '<img src="/adm/help/help.png" alt="'.&mt('Help').'" '.
-                           'title="'.&mt('Help').'" class="LC_icon" /></a>');
+    my $breadcrumbs = &Apache::lonhtmlcommon::breadcrumbs('Wishlist '.&Apache::loncommon::help_open_topic('Wishlist'));
 
     # get javascript-code for wishlist-interactions
     my $js = &JSforWishlist();
@@ -1614,6 +1795,65 @@ sub handler {
 # Extend CPAN-Module Tree by function like 'moveNode' or 'deleteNode'
 package Tree;
 
+=pod
+
+=head2 Routines from package Tree
+
+=over 4
+
+=item * &getNodeByIndex(index, nodes)
+
+     Searches for a node, specified by the index, in nodes (reference to array) and returns it. 
+ 
+
+=item * &moveNode(node, at, newParent)
+
+     Moves a given node to a new parent (if new parents is defined) or change the position from a node within its siblings (means sorting, at must be defined).
+
+
+=item * &removeNode(node)
+
+     Removes a node given by node from the tree.
+
+
+=item * &TreeIndex(children)
+
+     Sets an index for every node in the tree, beginning with 0.
+     Recursive call starting with all children of the root of the tree (parameter children is reference to an array containing the nodes of the current level).     
+
+
+=item * &setCountZero()
+
+     Resets index counter.
+
+
+=item * &RootToHash(childrenRt)
+
+     Converts the root-node to a hash-entry: the key is root and values are just the indices of root's children.
+   
+
+=item * &TreeToHash(childrenRt)
+
+     Converts all other nodes in the tree to hash. Each node is one hash-entry where the keys are the index of a node and the values are all other attributes (containing tile, path, note, date and indices for all direct children).
+     Recursive call starting with all children of the root of the tree (parameter childrenRT is reference to an array containing the nodes of the current level).     
+
+
+=item * &HashToTree()
+
+     Converts the hash to a tree. Builds a tree-object for each entry in the hash. Afterwards call &buildTree(node, childrenIn, TreeNodes, TreeHash) to connect the tree-objects.
+
+
+=item * &buildTree(node, childrenIn, TreeNodes, TreeHash)
+
+     Joins the nodes to a tree.
+     Recursive call starting with root and all children of root (parameter childrenIn is reference to an array containing the nodes indices of the current level).
+   
+
+=back
+
+=cut
+
+
 # returns the node with a given index from a list of nodes
 sub getNodeByIndex {
     my $index = shift;