From version < 3.7 >
edited by Guillaume Delhumeau
on 2016/02/25
To version < 3.8 >
edited by Guillaume Delhumeau
on 2016/02/25
< >
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -16,6 +16,28 @@
16 16  
17 17  Some applications used this parent/child relationship to organized their data. For them, this relationship is crucial.
18 18  
19 +== The introduction of the Nested Pages concept ==
20 +
21 +In XWiki 7.2, due to frequent users demands, we have introduced the ability to create spaces under some other spaces. It's the **Nested Spaces** concept. We suddenly had the ability to create a hierarchy of spaces to organize our content.
22 +
23 +But we have also found some issues. What if a space hold the same name then a page? Which entry should we render to the user when she reach an URL where 2 entities are matching? Moreover, does it make sense to have a difference between a space and a page? Why the pages cannot have sub-pages inside of them?
24 +
25 +Then we have decided to switch to the **Nested Pages** concept. In theory, a page should now be able to have some sub-pages, because we don't need to have a distinct between a page and a space like we have between a file and a folder.
26 +
27 +But this change was not possible to make on the API side because it would have required too much work that we could not afford at this time. So the decision was made to stick on the **Nested Spaces** implementation on the API (for now), but to propose **Nested Pages** in the UI.
28 +
29 +How does it work?
30 +
31 +Each time a user creates a page from the XWiki UI, she now actually creates a space (without knowing it ;)) with its ##WebHome## page. It means that any user-created page is called ##WebHome##.
32 +
33 +Then, when the user wants to create a sub-page ##FrankCapra## in the page ##Directors.WebHome##, she actually creates a new space inside the space ##Directors## with its ##WebHome## page: ##Directors.FrankCapra.WebHome##. **That's the trick!**
34 +
35 +The notion of space have been removed from the UI. It's not mentioned anywhere, anymore. Everything seems to work as if we were really creating sub-pages, even if we have created sub-spaces behind the scene.
36 +
37 +{{info}}
38 +That tricks should be temporary. When we will able the opportunity to rewrite the core model of XWiki, we will really implement the Nested Pages concept in the API.
39 +{{/info}}
40 +
19 19  = Principle =
20 20  
21 21  After having upgrade the XWiki instance to a recent version (7.4+), you should convert your existing pages to nested ones. This will permit:

A bit of history

Before the introduction of the Nested Pages concept (in 7.2), the content in a wiki was organized like this:

  • we had some Spaces, that you can see as "folder"
  • inside these spaces, we had Pages, where you were able to write some texts or store applications entries.

In that time, we cannot have spaces inside spaces, so all pages were placed inside a one-level space. The pages were identified like this: NameOfTheSpace.NameOfThePage.

Some pages were a bit special. They were the "home" page of a space. Every time a user wanted to reach a space without specifying a precise page name, she was redirected to that space home page. These pages were called "WebHome" (because at the very beginning of XWiki, "spaces" were called "web").

Parent/Child relationship

The user was able to specify a parent page for each page she had created. This parent could have been any page, for example the page Movies.ItsAWonderfulLife could have Directors.FrankCapra as parent. Then ItsAWonderfulLife was listed as Child of FrankCapra. This relationship was displayed in the breadcrumb at the top of each page. The user was able to navigate through this hierarchy

Some applications used this parent/child relationship to organized their data. For them, this relationship is crucial.

The introduction of the Nested Pages concept

In XWiki 7.2, due to frequent users demands, we have introduced the ability to create spaces under some other spaces. It's the Nested Spaces concept. We suddenly had the ability to create a hierarchy of spaces to organize our content.

But we have also found some issues. What if a space hold the same name then a page? Which entry should we render to the user when she reach an URL where 2 entities are matching? Moreover, does it make sense to have a difference between a space and a page? Why the pages cannot have sub-pages inside of them?

Then we have decided to switch to the Nested Pages concept. In theory, a page should now be able to have some sub-pages, because we don't need to have a distinct between a page and a space like we have between a file and a folder.

But this change was not possible to make on the API side because it would have required too much work that we could not afford at this time. So the decision was made to stick on the Nested Spaces implementation on the API (for now), but to propose Nested Pages in the UI.

How does it work?

Each time a user creates a page from the XWiki UI, she now actually creates a space (without knowing it emoticon_wink) with its WebHome page. It means that any user-created page is called WebHome

Then, when the user wants to create a sub-page FrankCapra in the page Directors.WebHome, she actually creates a new space inside the space Directors with its WebHome page: Directors.FrankCapra.WebHome. That's the trick!

The notion of space have been removed from the UI. It's not mentioned anywhere, anymore. Everything seems to work as if we were really creating sub-pages, even if we have created sub-spaces behind the scene.

That tricks should be temporary. When we will able the opportunity to rewrite the core model of XWiki, we will really implement the Nested Pages concept in the API.

Principle

After having upgrade the XWiki instance to a recent version (7.4+), you should convert your existing pages to nested ones. This will permit:

  • (1) to keep the existing hierarchy between pages, made with the parent/child relationship, which will be lost otherwise.
  • (2) give you the opportunity to create pages under any old page, as you could under new pages.

To perform this conversion, we have developed an application called Nested Pages Migrator Application. Its principle is to move all existing pages under their parent, so that the old parent/child relationship become physically represented by the Nested Pages hierarchy.

Fix the hierarchy

However, the current hierarchy may be messy. For example, so pages inside the space Proposal could have Main.WebHome as parent instead of Proposal.WebHome which would be more logical. It happens when the user is invited to create pages in the space Proposal directly from the main page (ex: http://design.xwiki.org/).

It's important to identify such a case before applying the migration tool, because the tool won't be able to detect this kind of unwanted hierarchies.

In the previous example, the solution was to put manually the parent of all pages of the Proposal space that had Main.WebHome as parent, to Proposal.WebHome. The following script have been used to migrate (ex: http://design.xwiki.org/):

#set ($xwql = "where doc.space in ('Proposal', 'Design', 'Improvements') and doc.parent = 'Main.WebHome'")
#foreach($r in $services.query.xwql($xwql).execute())
 #set ($d = $xwiki.getDocument($r))
 #set ($discard = $d.setParent('Proposal.WebHome'))
 #set ($discard = $d.save())
  * $r updated
#end 

Install Nested Pages Migrator Application

Go to the Extension Manager, and install Nested Pages Migrator Application. Then go to the page NestedPagesMigration.WebHome.

Get Connected