Hierarchy Macro
 | Displays and allows to manipulate the documents hierarchy in a space / on the wiki. |
| Type | XAR |
| Category | |
| Developed by | Anca Luca, Paul Cojan, Mircea Staicu |
| Active Installs | 117 |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
Table of contents
Description
Displays and allows to manipulate the documents hierarchy in a space / on the wiki.
The hierarchy of the documents is defined by the standard parent / child relation in XWiki. In addition, this macro introduces the concept of children order for a parent. However, the children order is used by default only by the hierarchy macro; if this order needs to be used in other places in the wiki as well, those places need to be customized to use this additional information introduced by the macro.
The macro can be used from the Wysiwyg edit mode of a page in the Macros menu, or by adding the macro call in wiki edit mode of a page:
Editing hierarchy
The hierarchy can also be displayed in edit mode allowing the user to change the documents hierarchy (parents and order of the children) with a nice drag & drop UI. Note, however, that all operations that a user does on the hierarchy are obeying the rights of the user performing the operations (he needs to have edit right on the child to change its parent and on the parent to change the order of its children; the two operations are, however, disconnected: if one fails, the other will be executed just fine).
Parameters
| Name | Optional | Allowed values | Default value | Description |
|---|---|---|---|---|
| space | yes | the name of a space in the wiki | empty | Space for which the pages should be displayed, if a selection should be made for the space. Note that space restriction applies to parents too: pages that have parents outside this space will behave as if they were orphan. If empty, all pages from the wiki will be included. |
| onlyroots | yes | true/false | false | Parameter that allows to limit the display to only the roots of the hierarchy. Use "true" if only the roots of the hierarchy should be shown, "false" if all the pages should be displayed. |
| excludes | yes | comma separated list of wiki documents fullnames | empty | Comma separated list of pages to exclude from the hierarchy display. These pages will be excluded from parents too (pages that have these pages as parent will behave as if they were orphan). |
| displayvalue | yes | fullName, name, title, displayTitle | fullName | The value to display for a document: use "fullName" for document fullname (space name followed by document name), "name" for the document name, "title" for the raw title of the document (if it contains velocity code it will not be interpreted) or "displayTitle" for the display title of the document (note that this last option slows down a lot the execution since it needs to load each document independently to compute its display title). |
| editable | yes | true/false | false | Whether the hierarchy tree should be editable or not. Note that if there are multiple hierarchy macros on the page, edit mode won't work. |
| checkright | yes | true/false | false | Whether the right (view or edit) should be verified when displaying a document in the hierarchy (in view or edit mode). By default it's false since it consumes resources to check rights, since document needs to be loaded in memory. If user doesn't have view right on a document and this parameter is false, a link will be displayed, and when accessing the link the user will get the regular rights error message in xwiki. |
| defaultparent | yes | name of a wiki document | empty | The default parent to set to a document when it's dragged on the first level, if this is an editable hierarchy. By default this parameter is empty, but it's highly recommended to set it so that you don't create orphaned pages in the wiki. If "editable" is false, this parameter is ignored. |
| showcheckboxes | yes | true/false | false | Whether this macro should display a checkbox for every document that it displays in the hierarchy. This allows to embed this macro in a form to submit the list of checked documents. |
| checkboxname | yes | any valid html form input name | hierarchydocs | To be used with the showcheckboxes parameter, it's the name to be used for the generated checkboxes. By default it is hierarchydocs. You can change it to anything besides "docreference" and "restupdateurl" which are reserved for the internal usage of the hierarchy macro. |
| checked | yes | true/false | false | To be used with the showcheckboxes parameter, it's the default value for the displayed checkboxes, whether all should be checked or not. |
| checkboxexcludes | yes | comma separated list of wiki documents fullnames | empty | Comma separated list of pages to not display checkboxes for, if showcheckboxes is set to true. If showcheckboxes is set to false, this parameter is ignored. |
| reorderable | yes | true/false | false | Enables reordering of the elements in visual mode, with no binding to actual data (no changes will be performed, as opposed to the effect of the "editable" parameter). You can see it as a "fake editable". This is usually used in conjunction with the showcheckboxes to put it all in a form to submit a list of pages, in the order selected by the user. If it's set together with the editable parameter, the editable will win (i.e. reordering will be binding). |
| documentLanguage | yes | a string representing the language | empty | This parameter's value is used to display a tree of documents in the desired language. For example displaying the tree only for the french language: documentLanguage='fr'. |
| openNode | yes | a string representing the full name of the looked up document | empty | This parameter's value is used to restrict the hierarchy tree from displaying the whole tree expanded, instead it expands only the path from the root node to the specified document's node. 'openNode' parameter's value should specify the full name of the document for which the tree should expand its branch. We also added a CSS class called 'open-node' to the container of the looked up node. |
| collapsed | yes | true/yes | false | This parameter's value is used to display the tree of documents collapsed. |
Note about scalability
The hierarchy macro was developed for the usecase of around 200-400 documents to be displayed in the hierarchy at once. The performance of the macro depends on the number of documents to display and of the various parameters that are used (editable and reorderable, for example, will create a lot of javascript objects in the browser and will risk to kill your browser). If you need to use this macro for more documents than the number above, do make a test/simulation with the actual parameters that you will use, before relying on the fact that it will work. Also, let us know in the comments what are the results of these tests!
For developers
Displaying checkboxes
The hierarchy macro can also display checkboxes next to each document in the hierarchy. Note that if this option is used, the tree only displays a list of html inputs (of type checkbox), no other elements are displayed (fieldset or form or etc). The responsibility of wrapping it in a html form, implementing the action to be taken on the form submit, etc, are all the responsibility of the caller of the hierarchy macro. Also, the reorderable parameter can be used in conjunction with the checkboxes to allow changing the order of the pages before they are submitted.
Using children order
The children order introduced by this macro is stored as a list in an object of type XWiki.ChildrenOrderClass in the parent. Note that this list an be out of sync with the actual hierarchy in the wiki since the parent can be changed also through the standard UI for changing parent (the edit mode of the document) and this standard operation does not update children list. Thus, in order to the list must be used as follows (and this is how it is used by the hierarchy macro itself to display the children of a document):
- all the documents that are listed in the XWiki.ChildrenOrderClass object and that are actual children of the document are displayed first, in the order in which they appear in the XWiki.ChildrenOrderClass object
- all the actual children of the document which were not displayed on the previous step are displayed after, sorted by the specified displayvalue
Known issues
- there could be issues with the drag and drop of the editable hierarchy in various browsers. This was implemented and tested on Firefox.
- the checkright parameter is not implemented for edit mode
- edit mode doesn't work if multiple hierarchies in edit mode are used on the same page
- alphabetical ordering of children does not work properly when using the displayTitle display value (because sorting is done before evaluating the displayTitle)
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Localization setup
After installing the application with extension manager, set the XWiki.HierarchyMacroTranslations document in the Internationalization bundles in Administration -> Localization. This application contains translations for English and French but you can add your own by adding a translation of the XWiki.HierarchyMacroTranslations document in your own language.
