Pinned Child Pages

[mflorea]

Hi everyone,

In order to implement Loading... (manual ordering of the page tree) I introduced the concept of pinned child pages. You can find details here https://design.xwiki.org/xwiki/bin/view/Proposal/PinnedChildPages but in “short”:

• Pinned child pages are displayed first under their parent (in manual order), followed by the rest of the child pages (in alphabetical order).

• There’s a new “Look & Feel >> Pinned Pages” administration section, both at wiki and at space level, to manage the list of (direct) child pages that are pinned.
  

  

• Top level pinned pages are saved in XWikiPreferences (using an object of XWiki.PinnedChildPagesClass).

• Pinned child pages for a given parent page are saved in WebPreferences of that page

• The saved list of pinned child pages is of course updated when the referenced pages are renamed, moved or deleted.

• There’s a new suggest picker to select direct child pages. Suggestions are fetched from:

  • WikiChildrenResource (e.g. rest/wikis/xwiki/children?offset=0&limit=10&search=foo) a new REST resource
  • PageChildrenResource (e.g. rest/wikis/xwiki/spaces/Sandbox/pages/WebHome/children?hierarchy=nestedpages&start=0&number=10&search=foo) an existing REST resource that was modified to support the nested page hierarchy besides the old parent-child hierarchy.
  • Selected (pinned) pages can be reordered with drag & drop in the suggest picker

• There’s a new PageHierarchy component (in xwiki-platform-index-tree-api), used by the previously mentioned REST resources, to get the list of child pages for a given parent entity reference (wiki or document reference).

• The Navigation Panel administration section was modified to allow changing the order of the top level pages and save this as pinned pages.

  • Moving a top level page pins it (in its new position) and all its previous sibling top level pages (relative to the new position).
  • There’s a button to explicitly pin / unpin top level pages.
  • The pinned top level pages are marked with a specific icon.
  • You can also use the keyboard to move top level pages as well as to pin / unpin them.
  • There’s an information box below the tree advertising the new feature.
    
    

This has already been pushed in 16.4.0RC1 but if you have doubts or disagree with any of the changes I made please let me know, and I’ll try to make the needed adjustments or even revert the parts that are not good if needed.

Sorry for not bringing this up earlier.
Marius

[vmassol]

@mflorea

There’s a new “Look & Feel >> Pinned Pages” administration section, both at wiki and at space level, to manage the list of (direct) child pages that are pinned.

From the location in the Admin UI, it seems you want to make the concept of Pinned Pages something independent of the Navigation panel. Could you explain what other use cases you see for them and in what areas of the XWiki UI this concept will surface apart from the Navigation tree?

@mflorea

• Top level pinned pages are saved in XWikiPreferences (using an object of XWiki.PinnedChildPagesClass).
• Pinned child pages for a given parent page are saved in WebPreferences of that page

AFAIK it’s no longer a good practice to use the XWikiPreferences/WebPreferences pages. We said some time ago that each module should have a *Config page to hold its configuration. We have quite a few such pages. PS: I searched quickly on xwiki.org and couldn’t find it documented.

@mflorea

There’s a new suggest picker to select direct child pages

Have you documented it under https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/ ?

@mflorea

There’s a new PageHierarchy component (in xwiki-platform-index-tree-api), used by the previously mentioned REST resources, to get the list of child pages for a given parent entity reference (wiki or document reference).

BTW are these REST resources documented on xwiki.org?

Thanks for working on this.

[mflorea]

@vmassol

From the location in the Admin UI, it seems you want to make the concept of Pinned Pages something independent of the Navigation panel. Could you explain what other use cases you see for them and in what areas of the XWiki UI this concept will surface apart from the Navigation tree?

The pinned pages configuration is, by default, taken into account by any page tree displayed in XWiki. This includes the tree from the Navigation Panel, the breadcrumb tree, the Page Index tree, the page picker tree, the page export tree, etc.

The Navigation Panel administration section allows ATM to reorder (and thus pin) only top level pages. But since the order is saved as pinned pages configuration, it means it affects the other trees as well.

The Navigation Panel administration section is visible only at wiki level, while the Pinned Pages administration section is available also at space level, allowing a space administrator to force a manual order on some of the pages from that space.

Exposing the Navigation Panel administration section at space level and limiting the actions to that space (i.e. making the administered page the root of the tree) is possible but more complex (we need to adjust how the extensions and applications filters displayed on the right side behave).

@vmassol

AFAIK it’s no longer a good practice to use the XWikiPreferences/WebPreferences pages. We said some time ago that each module should have a *Config page to hold its configuration. We have quite a few such pages. PS: I searched quickly on xwiki.org and couldn’t find it documented.

Maybe if you have a single wiki-level configuration but for a module that supports space level configuration it’s not conveninent to have to create and manage your own configuration pages. I don’t see the problem of using XWikiPreferences/WebPreferences pages as long as you have a dedicated configuation object.

@vmassol

Have you documented it under https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/FrontendResources/ ?

Not yet.

@vmassol

BTW are these REST resources documented on xwiki.org?

Not yet.

Thanks,
Marius

[vmassol]

@mflorea

The pinned pages configuration is, by default, taken into account by any page tree displayed in XWiki. This includes the tree from the Navigation Panel, the breadcrumb tree, the Page Index tree, the page picker tree, the page export tree, etc.

oh ok, I hadn’t realized this since the Release notes is currently only showing changes for the Navigation Tree at https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.0RC1/#HPinnedPages

It would be nice to add screenshots of trees fro the breadcrumb, etc, to show that the pinned pages are also visible there.

Note that the RN is not very precise as it says:

You can now manually change the order of the pages displayed in the page tree

However we don’t know what page tree is referred to.

Sounds cool. Technically I guess this means that the change was done at the level of the Tree macro? If that’s the case we need to update https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Macro

If it’s done at the level of the Tree Widget, it should be documented in https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Widget I guess.

@mflorea

The Navigation Panel administration section allows ATM to reorder (and thus pin) only top level pages. But since the order is saved as pinned pages configuration, it means it affects the other trees as well.

It feels a bit weird to me that you have to go to the Nav Panel admin UI to configure the order for all the trees (not just the Nav Panel one).

@mflorea

Maybe if you have a single wiki-level configuration but for a module that supports space level configuration it’s not conveninent to have to create and manage your own configuration pages. I don’t see the problem of using XWikiPreferences/WebPreferences pages as long as you have a dedicated configuation object.

We probably need to rediscuss this to make sure we all agree about our best practices for the various cases and document it.

Here’s an example of what I had done back then for the mail config: xwiki-platform/xwiki-platform-core/xwiki-platform-mail/xwiki-platform-mail-send/xwiki-platform-mail-send-default/src/main/java/org/xwiki/mail/internal/configuration at 5a2c63a5dc8f2aa3ddc8be320bd681a83d50c790 · xwiki/xwiki-platform · GitHub (but it doesn’t have support for space level config AFAIR).

Thanks!

[tmortagne]

It all make sense, I honestly don’t have anything to complain about (even the naming sounds good).

Great job!

@mflorea

@vmassol

AFAIK it’s no longer a good practice to use the XWikiPreferences/WebPreferences pages. We said some time ago that each module should have a *Config page to hold its configuration. We have quite a few such pages. PS: I searched quickly on xwiki.org and couldn’t find it documented.

Maybe if you have a single wiki-level configuration but for a module that supports space level configuration it’s not conveninent to have to create and manage your own configuration pages. I don’t see the problem of using XWikiPreferences/WebPreferences pages as long as you have a dedicated configuation object.

Yes, the main focus back then was more the XWikiPreferences class. There is still the problem that XWikiPreference is a mess, but it’s generally OK to add new objects at runtime (adding new objects to it as part of the flavor would really not be a good idea as it’s really complex to upgrade, but I don’t see much reason to do that with this feature). WebPreference does not cause any kind of problem (and IMO it’s good that we find all space configuration in there, easier to discover) as long as you use a custom xobject and not new fields in XWikiPreferences.

[mflorea]

@tmortagne

but it’s generally OK to add new objects at runtime (adding new objects to it as part of the flavor would really not be a good idea as it’s really complex to upgrade, but I don’t see much reason to do that with this feature)

The PinnedChildPagesClass objects are added at runtime, when you first save the Pinned Pages administration section or the Navigation Panel administration section (and for the later it happens only if you change the order for the top level pages manually in the navigation tree).

[mflorea]

@vmassol

oh ok, I hadn’t realized this since the Release notes is currently only showing changes for the Navigation Tree at https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.0RC1/#HPinnedPages

There are actually two videos there, one of which is showing the new Pinned Pages administration section. There’s also a link to the documentation for this new administration section in:

Besides the new administration section, we also updated the Navigation Panel administration section to allow you to change the order of the top level pages and save this manual order using pinned pages.

@vmassol

It would be nice to add screenshots of trees fro the breadcrumb, etc, to show that the pinned pages are also visible there.

There’s no visual difference between pinned pages and pages that are not pinned in the page trees that users see throughout the wiki. The only place where there is a difference is in the Navigation Panel administration section, in the tree used to configure the navigation tree.

@vmassol

Sounds cool. Technically I guess this means that the change was done at the level of the Tree macro? If that’s the case we need to update https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Macro

If it’s done at the level of the Tree Widget, it should be documented in https://extensions.xwiki.org/xwiki/bin/view/Extension/Tree%20Widget I guess.

The Tree Widget and the Tree Macro are generic and not aware of the page/document concept. The “page tree” model (data source) is implemented in xwiki-platform-index-tree-api and that’s also where the concept of “pinned pages” is implemented. This is why I documented the new “Pinned Page” administration section in https://extensions.xwiki.org/xwiki/bin/view/Extension/Index+Application#HTreeViewofallPages where I said:

The page tree macro, the navigation panel, the breadcrumb trees and in general any page tree displayed in XWiki should (by default) take into account the pinned pages, unless it has custom configuration that removes the pinned child pages filter.

@vmassol

It feels a bit weird to me that you have to go to the Nav Panel admin UI to configure the order for all the trees (not just the Nav Panel one).

Yes, which is why I kept the “Pinned Pages” administration section also at wiki level (not just space level). So an administrator that wants to configure the order of the top level pages for all page trees would probably use this section (but they can also use the Navigation Panel section).

Thanks,
Marius

[vmassol]

@mflorea

There’s no visual difference between pinned pages and pages that are not pinned in the page trees that users see throughout the wiki. The only place where there is a difference is in the Navigation Panel administration section, in the tree used to configure the navigation tree.

hmm I guess I misunderstood you then when you said:

@mflorea

The pinned pages configuration is, by default, taken into account by any page tree displayed in XWiki.

I understood this as meaning that the pinned page config was taken into account into all trees displayed i the wiki, and that’s a UI change. Or do you mean that there’s a visual difference but that the users won’t notice it without looking closely at the order in the tree and noticing it’s not using the title order?

@mflorea

There are actually two videos there, one of which is showing the new Pinned Pages administration section.

Yes, I’ve seen the release notes but it doesn’t show any change in the trees other than the nav panel one.

I don’t see how users are going to realize that all the trees in the wiki are using the pinned configuration to display the tree items. EDIT: I’ve taken the liberty of updating the RN with https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.0RC1/Entry001/?viewer=changes&rev1=2.1&rev2=4.1&

@mflorea

So an administrator that wants to configure the order of the top level pages for all page trees would probably use this section (but they can also use the Navigation Panel section).

ok, I hadn’t understood that there was now 2 ways to set pinned pages. Not sure it’s the best in term of UX as users will certainly wonder what is the difference when using on admin UI section vs the other one. Maybe we can iterate over this in the future.

Thanks for the explanation and for this very nice feature, much awaited!

[mflorea]

@vmassol

Or do you mean that there’s a visual difference but that the users won’t notice it without looking closely at the order in the tree and noticing it’s not using the title order?

Exactly.

@vmassol

I’ve taken the liberty of updating the RN with https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.0RC1/Entry001/?viewer=changes&rev1=2.1&rev2=4.1&

Looks good, Thanks!

@vmassol

Maybe we can iterate over this in the future.

Definitely. To give a bit of context, I started with the “Pinned Pages” administration section because it was easier to test during development: you have a text input mapped directly to the xobject property, you put the list of pinned pages, save, reload and check the result. After I got it working I started modifying the Navigation Panel administration section to support pinning top level pages. We could:

• refactor the code of the Navigation Panel administration section to support pinning not only top level pages
• use the result in the “Pinned Pages” administration section, to allow pinning not only direct child pages but also any descendant pages (e.g. by showing a tree rooted in the parent page being administered).