[LON-CAPA-cvs] cvs: loncom /html/adm/help/png add_folder.png add_link.png delete.png edit.png move.png note.png save.png view.png /html/adm/help/tex Wishlist.tex /interface lonwishlist.pm
wenzelju
wenzelju@source.lon-capa.org
Mon, 16 Aug 2010 15:14:37 -0000
This is a MIME encoded message
--wenzelju1281971677
Content-Type: text/plain
wenzelju Mon Aug 16 15:14:37 2010 EDT
Added files:
/loncom/html/adm/help/png add_folder.png add_link.png delete.png
edit.png move.png note.png save.png
view.png
/loncom/html/adm/help/tex Wishlist.tex
Modified files:
/loncom/interface lonwishlist.pm
Log:
- User-help and POD for wishlist.
--wenzelju1281971677
Content-Type: text/plain
Content-Disposition: attachment; filename="wenzelju-20100816151437.txt"
Index: loncom/interface/lonwishlist.pm
diff -u loncom/interface/lonwishlist.pm:1.3 loncom/interface/lonwishlist.pm:1.4
--- loncom/interface/lonwishlist.pm:1.3 Mon Aug 16 13:37:41 2010
+++ loncom/interface/lonwishlist.pm Mon Aug 16 15:14:37 2010
@@ -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 @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 @@
}
+=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 @@
}
+=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 @@
}
+=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 @@
'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 @@
# 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;
Index: loncom/html/adm/help/tex/Wishlist.tex
+++ loncom/html/adm/help/tex/Wishlist.tex
\label{Wishlist}
The wishlist is only available for users with access to the resource-pool. It offers a possibility to save links to resources from resource-pool or to external websites in a hierarchical list. Links must contain a title and a path. They can be stored in two ways:
\begin{enumerate}
\item When viewing a resource, an icon is offered to automatically set a link for this resource to the wishlist.
\item A link can be manually set by inserting the required informations.
\end{enumerate}
Folders, named by a title, can be used to structure the list. Both links and folder can also be added a note, for example to describe the content. The wishlist offers some functions for a dynamical structure. Therefor it is differentiated between a "'view"'(\includegraphics[width=0.03\paperwidth]{view})- and an "'edit"'(\includegraphics[width=0.03\paperwidth]{edit})-mode. The "'view"'-mode contains the following functions:
\begin{enumerate}
\item Add a new link (\includegraphics[width=0.03\paperwidth]{add_link}) to the wishlist by manually inserting a title, a path and a optional note.
\item Add a new folder (\includegraphics[width=0.03\paperwidth]{add_folder}) to the wishlist by inserting a title and a optional note.
\item View and edit notes (\includegraphics[width=0.03\paperwidth]{note}).
\item Select links and folders via checkboxes to move them to another folder (\includegraphics[width=0.03\paperwidth]{move}). Moving a folder means moving all content within this folder.
\item Select links and folders via checkboxes to delete them (\includegraphics[width=0.03\paperwidth]{delete}). Deleting a folder means deleting all content within this folder.
\item Save (\includegraphics[width=0.03\paperwidth]{save}) changed notes.
\end{enumerate}
The "'edit"'-mode offers the functions:
\begin{enumerate}
\item Add a new link (\includegraphics[width=0.03\paperwidth]{add_link}) to the wishlist by manually inserting a title, a path and a optional note.
\item Add a new folder (\includegraphics[width=0.03\paperwidth]{add_folder}) to the wishlist by inserting a title and a optional note.
\item Edit the titles (and paths) of links and folders via textfields.
\item View and edit notes (\includegraphics[width=0.03\paperwidth]{note}).
\item Sorting links and folders within a directory-level using the select-boxes before the title.
\item Select links and folders via checkboxes to move them to another folder (\includegraphics[width=0.03\paperwidth]{move}). Moving a folder means moving all content within this folder.
\item Select links and folders via checkboxes to delete them (\includegraphics[width=0.03\paperwidth]{delete}). Deleting a folder means deleting all content within this folder.
\item Save (\includegraphics[width=0.03\paperwidth]{save}) changed titles, paths and notes.
\end{enumerate}
The stored links can be imported into courses by using "'Edit Course"' -> "'Published Resources"' -> "'Import from wishlist"'.
--wenzelju1281971677--