Extension:HierarchyBuilder

The HierarchyBuilder extension introduces a tag,  , two Semantic Form input types, hierarchySelect and hierarchy, and three parser functions #hierarchyChildren, #hierarchyParent, #hierarchySectionNumber.

Installation
This extension requires Semantic MediaWiki to be installed first.

Hierarchy Tag
The body of the   tag contains a wikitext list of page names forming the hierarchy, where each list item ( * ) contains a wikitext link to a page ( page name ). For example:



The tag is rendered similar to a collapsible file system hierarchy with each page name hyperlinked to the corresponding page in the wiki. For example:



Note that the pages that are referenced in the hierarchy are not modified and do not store any of the hierarchy-related information. In this manner, pages may be included in many independent hierarchies.

The   tag takes three optional attributes: collapsed, displaynameproperty, and autonumbered. collapsed is provided if the hierarchy should initially be displayed with only the top-level pages visible, with all subtrees collapsed. It defaults to false. For example,



displaynameproperty can be set to the name of a property whose value to use instead of the name of the page as the text on the link. This is useful when the name of a page is not user friendly. For example, if the name of the page is an automatically generated number, the value of a property on the page can be displayed to the user instead. If the property does not exist on the page or is empty, the page name will be used.

autonumbered is provided if the hierarchy should prepend section numbers (e.g. 1.2.1) to each row in the hierarchy. For example:



Semantic Forms Input Types
The hierarchySelect Semantic Form input type allows other pages in the wiki that are edited using a form to select a subset of pages from the hierarchy to populate a multi-valued property of type Page. The hierarchy is rendered as above with the addition of a checkbox before each page name to allow selection of the desired pages. The name of the property that stores the hierarchy and the page on which that property is set must be provided in the form in order to be able to locate the hierarchy. The name of the property is provided in the propertyname parameter. The name of the page holding the hierarchy from which to select components is provided in the pagename parameter.

The form field

could be used to add the following to a form:



An optional Boolean parameter, collapsed, specifies whether the tree should initially be displayed with only the top-level pages visible, with all sub-trees collapsed. It defaults to false.

As above, a displaynameproperty parameter can be used to display the value of a property rather than the page name. Note that this property will only be used for display; the page names of the selected pages will be returned from the form rather than the display names. If the property does not exist on the page or is empty, the page name will be used.

The hierarchy Semantic Form input type allows editing of the hierarchy in a graphical manner within a form. The name of a category that pages must belong to in order to be eligible for inclusion in the hierarchy must be provided in the form. The name of the category is provided in the category parameter. Pages that are in this category but are not yet in the hierarchy are listed on the right side of the form to allow drag and drop on to the hierarchy as desired. Pages already in the hierarchy can be rearranged and their indentation level in the hierarchy can be modified using drag and drop. Page can be dragged out of the hierarchy and dropped on to the area on the right side of the form to delete them from the hierarchy. Deleting pages from the hierarchy does not affect the actual pages in the wiki. For example, the form field

could be used to edit a hierarchy on a form as follows:



As above, a displaynameproperty parameter can be used to display the value of a property rather than the page name. Note that this property will only be used for display; the page names of the pages in the hierarchy will be returned from the form rather than the display names. If the property does not exist on the page or is empty, the page name will be used.

hierarchyBreadcrumb
The hierarchyBreadcrumb parser function can be used to display a hierarchy breadcrumb bar at the top of a page including the previous row, hierarchical parent row, and next row within the hierarchy.

The parameters are given in the table below:

The parser function invocation:

would display the breadcrumb for the page  within the hierarchy stored in property Hierarchy Data on the page Table of Contents using the semantic page names stored within the property Name on each page. The bar might contain the row that immediately precedes ', immediately succeeds ', and the hierarchical parent of  within the hierarchy on the page Table of Contents.

hierarchyChildren
The hierarchyChildren parser function can be used to retrieve the immediate hierarchical children of a given page from a hierarchy on a specified page.

The parameters are given in the table below:

The parser function takes the following three mandatory arguments in order: page name, hierarchy page, and hierarchy property. There are also the following optional arguments: sep, template, introtemplate, outrotemplate, and link. The sep argument is used to specify the separator for returned values. The argument template is the name of a template with which to display the printouts. The introtemplate argument is the name of a template to display before the results if there are any. The outrotemplate argument is the name of a template to display after the results if there are any. The argument link is used to specify whether or not to display results as links if there are any results. The value of the link argument can either be empty or none. By default, link is enabled.

The parser function invocation:

would display the template Y followed by the immediate children of the page  in the hierarchy stored in the property hierarchy property on the page hierarchy page after applying the template X to each result, followed by the template Z.

hierarchyParent
The hierarchyParent parser function is used to retrieve the hierarchical parent of a given page from a hierarchy on a specified page.

The parameters are given in the table below:

The parser function take the following three mandatory arguments in order: page name, hierarchy page, and hierarchy property. Additionally, there are also the following optional arguments: template, introtemplate, outrotemplate, and link. Each of these arguments behaves the same as they do for the hierarchyChildren parser function above. The argument template is the name of a template with which to display the printouts. The introtemplate argument is the name of a template to display before the results if there are any. The outrotemplate argument is the name of a template to display after the results if there are any. The argument link is used to specify whether or not to display results as links if there are any results. The value of the link argument can either be empty or none. By default, link is enabled.

The parser function invocation:

would display the hierarchical parent row of  within the hierarchy stored in property hierarchy property on the page hierarchy page name rendered as a hyperlink.

hierarchySectionNumber
The hierarchySectionNumber parser function is used to automatically compute a given page's section number within a particular hierarchy on a specified page.

The parameters are given in the table below:

The parser function takes three mandatory arguments in order: page name, hierarchy page, and hierarchy property.

The parser function invocation:

would give the section number of the page  within the hierarchy in property Hierarchy Data on the page Table of Contents.

hierarchySubtree
The hierarchySectionNumber parser function is used to render the subtree rooted at a given node within a specified hierarchy.

The parameters are given in the table below:

The parser function takes three mandatory arguments in order: root node, hierarchy page, and hierarchy property. If format is given as 'ul' then the subtree will be rendered as a bulleted list. Otherwise, the subtree is rendered by default as a hierarchy. If 'showroot' is given then the root of the subree will be rendered as a part of the result. By default the root of the subtree is hidden in the display. If 'collapsed' is given then the subtree will be initialized in collapsed mode. By default the subtree is not rendered in collapsed mode.

The parser function invocation:

would render the subtree rooted at "Hierarchy Builder" within the hierarchy in property Hierarchy Data on the page Main Page as a bulleted list.

hierarchySelected
The hierarchySelected parser function is used to find and render the minimum spanning tree that contains specified rows within a hierarchy in addition to the root node of the specified hierarchy. The rendered minimum spanning tree will show each selected node with a checked box.

The parameters are given in the table below:

The parser function takes three mandatory arguments in order: selected pages, hierarchy page, and hierarchy property. If the display mode is given as 'collapsed' then the minimum spanning tree will be initialized in collapsed display mode.

The parser function invocation:

would render the minimum spanning tree in collapsed mode of the hierarchy in property hierarchy property on the page hierarchy page name which contained the hierarchy root and each of the listed page names so that the listed page names would be marked as "checked".

Acknowledgements
This extension is implemented using jsTree and nestedSortable libraries.