WCKER tree editing behaviour spec. v0.2 2005-03-17

Preable
=======
Some of the decisions here are sub-optimal so far as usability goes, but they're a solid place to start and to improve upon in the next version of WCKER.
Suggestions to improve clarity are needed and would be apprieciated.




Relationship to Reload
======================
Where possible and relevant, WCKER tree editing should follow that of Reload tree editing. However, differences in the approaches taken by Reload and WCKER will require some divergence.

To put it another way: we should do what Reload does, unless we've got a good reason not to.




The tree
========
 * The tree may contain container items (e.g. units) and pages.
 * At its most permissive, all containers in the tree may hold pages and other containers.
 * More restrictive configurations may be defined in the structure section of the wizard.wsi file.
 * The restrictions can limit the contents of containers at specific depths to only pages, or only containers.




The buttons
===========
There are three groups of buttons relating to editing the tree:
 1) The heirarchical tree widget and editing icons
 2) The Input fields (e.g. title, author, course aim)
 3) The Previous item and Next item buttons

(see http://waterbuck.conted.ox.ac.uk/cgi-bin/trac.cgi/wiki/GuiPrototype#Customise-course-step-course-level)



For 1)
~~~~~~
(Ignoring drag-and-drop as we probably don't have time to implement it.)
There are two major parts to this group: the tree and the editing icon buttons.

_The tree_

The tree is a heirarchy of nodes representing containers and pages, with exactly one root node. The root node relates to the "organization" element on the IMSCP manifest file.

Any one of the tree's nodes can be selected at a time. Doing so creates a "selection context" which will affect what actions are available to the user. (There may or may not be code forming selection context explicitly, that's an implementation detail.)

A selection context describes:
 * What node is selected (there must be a way to relate that to the part of the IMS manifest it represents)
 * Which of the editing icons' actions can be performed on the node, determined by:

    a) Whether the node can accept container nodes as children. True if all of the following are true:
       * node is a container
       * the wizard.wsi structure section allows child containers

    b) Whether the node can accept page nodes as children. True if all of the following are true:
       * node is a container
       * the wizard.wsi structure section allows child pagess

    c) Whether the node can be deleted. True if all of the following are true:
       * node is not the root node
       * node is not marked as indestructable in the wizard.wsi structure section (not implemented)

    d) Whether the node can moved up. True if all of the following are true:
       * node is not the root node
       * node is not the first child of the root node
       * node is not the first instance of that type of node at that tree depth

    e) Whether the node can moved down. True if all of the following are true:
       * node is not the root node    
       * node is not the last node in a depth first linearisation of the tree
       * node is not the last instance of that type of node at that tree depth

NB. Adding siblings will not be allowed in this version of WCKER.


_The editing icon buttons_

These buttons are enabled/disabled according to the selection context.

Behaviour when activated:
 * Add container
    * If only one type of container may be legally inserted as a child of the selected node, it is inserted as the last child of the node.
    * If there are more than one type of container item which may be legally inserted as a child of the selected node, a list of allowed containers should popup, allowing the user to choose which type to add. On selection of a container type, it is inserted as the last child of the node. (The initial version of WCKER may not include this functionality.)

 * Delete container
    * Removes the container and all its childeren from the tree.

 * Add Page
    * Adds a page as the last child of the selected node.

 * Delete Page
    * Removes the page from the tree.

 * Move selected up
    * Moves the selected item to the first available preceding location. Non-exhaustive examples: 
        a) A page with another page immediately preceding it - would moved above the preceding page (or be swapped with it, depending on how you think about it).
        b) A page with no sibling pages immediately preceding it, where pages are legal at any point preceeding the page - would be moved to the first legal point found when looking backwards through a depth first linearisation of the tree, starting at the selected node.
        c) A container with another container immediately preceding it - would moved above the preceding container (or be swapped with it, depending on how you think about it).


 * Move selected down
    * Moves the selected item to the first available following location. Non-exhaustive examples: 
        a) A page with another page immediately following it - would moved below the preceding page (or be swapped with it, depending on how you think about it).
        b) A page with no sibling pages immediately following it, where pages are legal at any point following the page - would be moved to the first legal point found when looking forwards through a depth first linearisation of the tree, starting at the selected node.
        c) A container with another container immediately following it - would moved below the preceding container (or be swapped with it, depending on how you think about it).

NB: The move up and move down actions keep a node as the same node type, at the same hierarchical depth. A later version of WCKER might include functionality to promote/demote nodes up and down the tree, and to convert between node types.



For 2)
~~~~~~
A number of fields used to input data relating to the selected node.
When the Title field is edited, the changes should appear in the corresponding part of the tree widget (on keypress).
No fields other than the title are represented on the tree widget, so changes to them are of no consequence to the tree widget.



For 3)
~~~~~~
These buttons should change the node selected in the tree widget, stepping back and forth through the course structure hierarchy using a depth first linearisation.
Activating the "Previous item" should move the selection one node back (ie up the screen).
Activating the "Next item" should move the selection one node forward (ie down the screen).

"Previous item" is disabled if the selected node is the root node.
"Next item" is disabled if the selected node is the last node in the linearisation.