Pinned Child Pages
Description
Goal
The page tree lists pages using an automatic order, based on the translated page title by default. This is fine most of the time, but there are cases where a custom order is needed, like for instance if you want your navigation panel to use a logical order (e.g. similar to the chapters of a book) rather than an alphabetical or time-based order.
At the same time the page tree hierarchy is dynamic: you can add new pages or refactor existing ones. This means that in practice only a few of the pages need to be manually ordered. The rest can use some automatic order (be it alphabetical or time-based). One way to achieve this mix of manual and automatic order, with the current alphabetical order being the default, is to add support for pinning child pages.
Pinned child pages are displayed first under their parent, followed by the rest of the child pages using the automatic order.
Implementation Details
Storage
We need to store the pinned child pages in a way that reduces the amount of updates required when the page tree is refactored:
- Moving or renaming a parent page shouldn't trigger an update for the pinned child or descendant pages.
- Deleting a parent page with its child pages shouldn't require additional work to clean up the deleted pinned pages.
- Deleting a parent page without its child pages shouldn't remove the state of the pinned child pages (the page hierarchy can have holes and the page tree supports this, meaning that the remaining child pages can still be accessed from the page tree, so the manual order should be preserved when the parent page is deleted alone).
- A user with just edit right on the parent page shouldn't be able to change the order of the child pages (for everyone else).
- A user with just edit right on a child page shouldn't be able to pin or unpin that page (i.e. change the order).
- A user that has administration rights on a parent page should be able to change the order of the child pages.
- When a pinned child page is renamed, the pinned state should be preserved.
- When a pinned child page is deleted, the list of pinned child pages for its parent page should be updated.
- When a pinned child page is moved (to a different parent page) the pinned state should be removed (the moved page shouldn't be pinned under the new parent page).
Solution
- Introduce a XWiki.PinnedChildPagesClass with a single pinnedChildPages property of type Static List (with multiple selection and relational storage).
- For top level pinned pages add an object to the wiki preferences (XWiki.XWikiPreferences).
- For a given parent (nested) page add an object to the page preferences (<Page>.WebPreferences).
- pinnedChildPages property can use a custom displayer based on a "child pages" suggest picker to help administrators manage the list of pinned child pages.
- The list of pinned child pages should ideally be a list of child page names, in order to avoid the need of updates when the parent page is refactored.
- The problem is that XWiki supports both terminal and nested pages, and a pinned child page can be either of them. For instance Parent.WebHome can have both Parent.Foo and Parent.Bar.WebHome as child pages. The name of the first child page is "Foo" while the name of the second child page is "Bar". We can't simply store "Foo, Bar" as the list of pinned child pages because we won't be able to recreate their references. We can't use PageReference either, because Parent.WebHome can have both Parent.Foo and Parent.Foo.WebHome as child pages, and although it sounds crazy, you might want to pin both.
- The solution is to add a marker that can help us distinguish between terminal and nested pinned child pages, but if we do this then we need to encode this marker that may appear in the page name.
- A simple solution is to suffix the name of a nested page with / (slash) and to perform a partial URL encoding of the page name (just for % and /).
- This makes it easy to reconstruct the page references: check for the slash suffix and apply URL decoding after removing it.
- It also makes the list of pinned child pages easy to read (by a person).
- This means that for our example, the list of pinned child pages of Parent.WebHome could be "Foo, Bar/".
- We still need an even listener to update the list of pinned child pages when a pinned page is renamed, moved or deleted.
- We need an administration section both at wiki and space level to manage the list of pinned child pages.
Child Page Picker
For the custom displayer of the pinnedChildPages property we need a child page (suggest) picker. Implementing a new suggest picker is relatively easy, but we need to:
- Have a REST resource to give us child page suggestions.
- We actually need 2 REST sources: one for top level pages (the parent is the wiki) and one for a given parent page.
- Allow the user to change the order of the selected child pages, both using drag & drop and with the keyboard (accessibility).
Solution
- We already have the PageChildrenResource but it uses the deprecated parent-child hierarchy mode.
- Example URL: rest/wikis/xwiki/spaces/Sandbox/pages/WebHome/children
- We need to add a new hierarchy query string parameter to be able to select the hierarchy mode, and keep parent-child by default for backwards compatibility.
- We also need a new search query string parameter to be able to filter the child pages (by typing on the suggest input)
- Introduce WikiChildrenResource to retrieve the top level pages of a wiki
- Example URL: rest/wikis/xwiki/children
/** * The top level pages in the page hierarchy of a given wiki. * * @version $Id: 77feab1126092d27f27bb01fb6e87e15f912571a $ * @since 16.4.0RC1 */ @Path("/wikis/{wikiName}/children") @Unstable public interface WikiChildrenResource { /** * Retrieve the child pages (i.e. top level pages) of a specified wiki, optionally filtered by a search string. * * @param wikiName the wiki to retrieve the top level pages from * @param offset the index of the first child page to return * @param limit the maximum number of child pages to return * @param search a search string to filter the child pages by name or title * @return the child pages that match the search criteria * @throws XWikiRestException if there was an error while retrieving the child pages */ @GET Pages getChildren( @PathParam("wikiName") String wikiName, @QueryParam("offset") @DefaultValue("0") Integer offset, @QueryParam("limit") @DefaultValue("-1") Integer limit, @QueryParam("search") @DefaultValue("") String search ) throws XWikiRestException; } - We can default on nested pages hierarchy mode for this one (and no need for a hierarchy parameter)
- We need to be able to filter the top level pages, as well as limit the results
- Example URL: rest/wikis/xwiki/children
- There is currently no component that can give us the list of child pages for a given parent entity (wiki or document) so we need to add one.
- Introduce the PageHierarchy component role, with a "nestedpages" implementation provided by the Index Application Tree API.
/** * Used to navigate the hierarchy of wiki pages (documents). * * @version $Id: aff3f6c809960c2f82816c2b9c5b8bab0f4ce678 $ * @since 16.4.0RC1 */ @Role @Unstable public interface PageHierarchy { /** * Encapsulates a query to retrieve the child pages. */ interface ChildrenQuery { /** * @param offset the index of the first child to return * @return this query */ ChildrenQuery withOffset(int offset); /** * @param limit the maximum number of children to return * @return this query */ ChildrenQuery withLimit(int limit); /** * @param text a search text to filter the child pages by their name or title * @return this query */ ChildrenQuery matching(String text); /** * @return the list of child document references */ List<DocumentReference> getDocumentReferences() throws QueryException; /** * @return the number of child pages */ int count() throws QueryException; } /** * Base class for {@link ChildrenQuery} implementations. */ abstract class AbstractChildrenQuery implements ChildrenQuery { protected final EntityReference parentReference; protected int offset; protected int limit = -1; protected String text = ""; /** * Creates a new query to retrieve the children of the given parent entity. * * @param parentReference the reference of the parent entity for which to retrieve the children */ protected AbstractChildrenQuery(EntityReference parentReference) { this.parentReference = parentReference; } @Override public ChildrenQuery withOffset(int offset) { this.offset = offset; return this; } @Override public ChildrenQuery withLimit(int limit) { this.limit = limit; return this; } @Override public ChildrenQuery matching(String text) { this.text = text; return this; } } /** * @param wikiReference the reference of the wiki for which to retrieve the top level pages * @return a query to retrieve the top level pages of the given wiki */ ChildrenQuery getChildren(WikiReference wikiReference); /** * @param documentReference the reference of the parent document for which to retrieve the children * @return a query to retrieve the children of the given document */ ChildrenQuery getChildren(DocumentReference documentReference); }
- Introduce the PageHierarchy component role, with a "nestedpages" implementation provided by the Index Application Tree API.
- For reordering the pinned pages, fortunately selectize (the JavaScript component used to implement the suggest pickers) has a configuration (plugin) to enable drag & drop on the selected items. This plugin requires jQueryUI which we are already using in some other parts of XWiki so it was just a matter of adding it as a required dependency.
- For keyboard interaction we don't have to do anything because selectize already supports inserting anywhere in the list (when multiple selection is on).
Pinned Pages Configuration
Administrators need to be able to manage the list of pinned child pages, both for the wiki (top level pages) and for any nested page (because they can have child pages).
Solution

- Define a new administration section that is available both at wiki and at space level
- We could have also added this to an existing section, but none was a good fit.
- Name the section "Pinned Pages" and expose in this section only one property, the pinnedChildPages property.
- We could have also named this section "Page Tree" thinking that we could gather here more tree related configuration options in the future.
Page Tree
The page tree needs to be modified to take into account the list of pinned child pages.
Solution
- We need to exclude the pinned child pages when retrieving the list of child pages for the wiki or a parent page. Fortunately, the tree API already supports implementing tree filters so we have to implement a PinnedChildPagesTreeFilter.
- Pinned child pages need to be listed first when retrieving the list of child pages for the wiki or a parent page. This requires some refactoring of the tree API implementation in order to properly support pagination.
- Add a TreeNodeGroup interface to be able to group related child nodes (e.g. the pinned child pages form a group, and the rest of the child pages form another group).
/** * A group of related tree nodes, similar to a document fragment in a DOM tree. * * @version $Id: 86a1a685f289e8555d8960d4aeba684f37f1b805 $ * @since 16.4.0RC1 */ @Unstable public interface TreeNodeGroup extends TreeNode { @Override default String getParent(String nodeId) { // Tree node groups are never attached to the tree. return null; } } - Add a CompositeTreeNodeGroup component (with a DefaultCompositeTreeNodeGroup implementation) that wraps multiple tree nodes (or groups) and handles the pagination. When you ask it for the child nodes it places the offset before the right child node or inside the right child node group and then returns child nodes across multiple child subgroups, if needed.
/** * A tree node group that aggregates multiple, optional, tree nodes. * * @version $Id: 9f049702719fb7e5f263cb8fd48710271db9cb29 $ * @since 16.4.0RC1 */ @Role @Unstable public interface CompositeTreeNodeGroup extends TreeNodeGroup { /** * Adds an optional tree node to the group, that is enabled for a given node id only when the specified condition is * met. * * @param treeNode the optional tree node to add * @param condition the condition that must be met for the tree node to be enabled for a given node id */ void addTreeNode(TreeNode treeNode, Predicate<String> condition); /** * Sets the id generator used to generate ids for the aggregated child nodes. * * @param idGenerator a function that generates the id for an aggregated child node, given the parent node id and * the child node type */ void setIdGenerator(BinaryOperator<String> idGenerator); } - Refactor the wiki and document tree nodes to use the CompositeTreeNodeGroup component under the hood.
- Wiki node will wrap: pinned child pages (subgroup) and other child pages (subgroup)
- Document node will wrap: translations, attachments, class properties, objects, add document, pinned child pages and other child pages
- Add a TreeNodeGroup interface to be able to group related child nodes (e.g. the pinned child pages form a group, and the rest of the child pages form another group).
Navigation Panel Administration
The navigation panel administration section already allows you to drag & drop tree nodes, but the manual order is not saved. At the same time, the only way to reorder the tree nodes is with drag & drop which is not accessible. Moreover, the administrator needs to be able to pin or unpin individual top level pages:
- moving a top level page doesn't always mean you want that page to be pinned (you may move it from the top to the button because you don't want it to appear at the top, but you don't care in which order it appears at the bottom)
- you don't always want all the top level pages to be pinned, so always saving the full manual order might not be the right choice
Solution

- We need to modify the jsTree styles to allow us to show some action buttons when a tree node is hovered or focused (you can use the keyboard to navigate the tree nodes and "hover" or focus them).
- The HTML structure used by jsTree is not very helpful, but we can try to apply flex style on the tree nodes.
- We need to use the "large" jsTree style so that the action button we add (to pin/unpin a page) has proper dimensions (accessible).
- jsTree doesn't support node action buttons so we need to inject them after the tree is loaded, whenever a tree node is displayed.
- We can't put the action buttons inside the node label because the node label uses an anchor tag (link). But the node hovered / focused state if determined the node label, so we need to do some hacks in order to keep the node hovered / focused when the action buttons are hovered / focused.
- We need to make sure the user can use the keyboard (Tab) to jump to the action buttons from a selected node, and also come back (Shift + Tab) to continue the tree navigation (with Up/Down arrow keys).
- We need to indicate visually the pinned pages. We can use the pin/unpin button this way:
- When a node is not hovered/focused we just show the pin (button) icon, if the node is pinned.
- When a node is hovered/focused we just the pin / unpin button with the proper label (depending on whether the node is pinned or not)
- Clicking the pin button for a given node pins that node and all of its previous sibling page nodes, because in order to preserve that node's position we also need to preserve the position of the previous nodes.
- Clicking the unpin button for a given node unpins that node and all of its next sibling page nodes, because if that node's position is dynamic then all the following nodes have a dynamic position (basically we can have two groups of pages: manually ordered first and then automatically ordered; we can't interleave these groups).
- When a top level page is drag & dropped that page becomes pinned at the new location (still top level). This means all its previous siblings (from the new location) become pinned also.
- We add a shortcut key to move a top level page (that is selected / focused): Alt + Shift + Up/Down
- We probably need to advertise this shortcut key (at least for now) with an information box displayed under the tree.
- On save, we need to update first the wiki preferences (with the list of pinned top level pages) and then the navigation panel configuration.
Marius Dumitru Florea