Migration Guide to Nested Pages
History
Executive Summary
Up to XWiki 7.1, there has been 2 ways to organize content in XWiki:
- Wiki > Space > Page (which includes rights inheritance and administration features)
- Page > Child Page > Child Page of child Page > ... (which is used for hierarchical navigation purposes)
Note that both are independent: a page can have a parent Page in a different Space/Wiki than its own .
While this was working, we've found that it could create confusion for users, leading to questions such as:
- Should I create a sub-Wiki or a Space for my team?
- Which navigation should I put on my home page: list of Spaces or tree view of Pages?
- Can I set rights on a page that is under a space?
At the same time, for a long time there have been discussions on the list about the future "new model" of XWiki, which would ideally include
Nested Spaces, offering the following features:
- Unified way to handle hierarchical navigation (Page > Sub-page > Sub-sub-page >...)
- Navigation reflected in URLs (.../PageA/PageB/PageC)
- Inheritance of access rights (rights on PageA apply to PageB and PageC, unless defined otherwise. Rights on PageB supersede those on PageA
and also apply to PageC, and so on.)
In the end, we took the opportunity to move from the previous way to this new way of organizing pages in XWiki 7.2.
In an ideal world, going from the old model to the new one would imply a total rewrite of the model. However, in order not to break retro-compatibility with many existing features and applications we had to keep the concepts of "Page" and "Space" in XWiki while adapting them to emulate the Nested Pages feature. Here's what we've done to achieve this by default:
- We've hidden the parent-child feature
- When creating a new page, the system automatically creates Page.WebHome, which creates a Space, though this is hidden in the URL (you only see .../Page/)
- For advanced users, we added the ability to create "Terminal Pages" which are pages that are not Spaces (as before). This is meant mostly for Application creators.
Detailed Explanations
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 
) 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.
Note that the user has still the ability to create pages that does not have the WebHome name. As a consequence, such pages (that are not the WebHome of their space) cannot have sub-pages. That is why we call them Terminal Pages.
Issue with the Parent/Child relationship
Now, it is clear that we have 2 different hierarchies in the wiki. One, made of sub-pages (sub-spaces in the reality), and one made with the old parent/child relationship. Then, clearly, it becomes confusing for the user. Which hierarchy should be displayed in the breadcrumb? What is the parent of page, the "container" page or the parent set in the field?
The choice have been made to drop the notion of parent/child relationship, since we can now really have children pages, implemented as sub-pages (with inherited rights, preferences, etc...).
It means that when the user wants to change the parent of a page, she actually needs to move this page under the new parent.
This concept are good in theory. But, how can we handle existing content when an XWiki upgrade is made?
Migration
The idea is not convert existing pages (which most of them are terminal) to WebHome pages under their own space. We call this "convert terminal pages to nested pages". This allows you to create sub-pages under any converted pages, which is impossible while they were terminal.
But that would be a shame to lose the parent/child relationships that the user have created between its pages. The user might want to preserve its hierarchies. She might still want to have FrankCapra as parent of ItsAWonderfulLife.
To keep this information, the principle is to move all the pages under their parents, so the parent/child links becomes a real hierarchy between pages.
To perform this conversion, we have developed an application called Nested Pages Migrator Application.
Fix the hierarchy
However, the current hierarchy may be messy. For example, some 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/):
#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
Nested Pages Migrator Application
To use the migrator application, you first need to upgrade your XWiki instance to a recent version (7.4.2+). Indeed, the migrator cannot create nested pages in an old XWiki instance where this concept did not exist!
Go to the Extension Manager, and install Nested Pages Migrator Application. Then go to the page NestedPagesMigration.WebHome.
You will find the following page:
There are 2 actions:
- compute a plan: the migration first generate a plan of actions to perform. You can see what the migrator proposes to do and disable some actions, or modify the options, for example.
- execute the plan: when a plan has been computed and if you agree with its content, you can execute the plan: the pages will be moved as proposed.
Options
But first, let's talk about the options.
| Option | Description | Default value (recommended) |
|---|---|---|
| Exclude hidden pages | Check this option if you want to exclude hidden pages, that usually contain technical data, from the migration. | true |
| Exclude pages having a class | Check this option to not convert pages holding a class, because it can break applications based on these classes. | true |
| Do not move children | Convert pages into Nested Pages (so they can have children) without moving them under their parent. The old hierarchy will not be preserved, but the rights and the preferences will remain the same. | false |
| Add redirection | Add a redirection in the old location. So when the user will reach the old URL, she will be automatically redirected to the new one. It's good if you don't want to break bookmarks, for example. | true |
| Convert preferences | By moving pages under their parents, the inherited preferences might change. If this option is enabled, the migrator will copy the old inherited preferences to the new location. | true |
| Convert rights | By moving pages under their parents, the inherited rights might change. If this option is enabled, the migrator will try to set the same rights in the new location. | false |
| Exclude classes | Exclude pages holding some objects. | A list of classes that we have identified to be excluded. It's not complete, you should add classes of your own applications! |
| Exclude pages | Exclude a list of pages. | A list of pages that we have identified to be excluded. |
| Excluded spaces | Exclude a list of spaces. | A list of spaces that we have identified to be excluded. |
| Included spaces | Only pages containing in this list of spaces will be converted | empty |
Note: you can select the classes to exclude by clicking on the "excluded classes" field:
Plan
Once the options have been carefully set, you can start the computation of a plan. This operation usually lasts about 10 seconds, but it could be more depending of the number of the pages and the complexity of the preferences, rights, and hierarchies. The logs of the operation are displayed in the page. If error happens, you will have some error entries in the logs.
This is what a plan looks like:
A plan is a tree of actions to perform in order to convert your pages. The tree is ordered as the resulting hierarchy would look like. If you click on the strong page name of each action, you will open the tree and see the children actions. You can close the tree by clicking again the page name.
Each line displays the target document (the new location of the page) and the original page (the current location of the page). It is displayed like this:
You can click on the old location to open the page (in a new window). It could be useful to look at the page you are about to move.
Some actions have the mention: "(unchanged)". It means the page will not be moved. They are present in the tree only to display their children when some of them have changed.
Each action has a checkbox. Only checked actions will be perform. So if you notice some changes that you don't want to perform, you can easily uncheck them. When you uncheck an action, it also concern its children. But you can also select the children one by one if you need.
Other actions are available:
- exclude page: click on this button to add the page to the exclude list (in the options). The plan might be recomputed.
- exclude space: click on this button to add the space of that page to the exclude list (in the options). Then plan might be recomputed.
- set parent: click on this button to manually set a parent for that page.
Preferences
Some actions can contains preferences changes. You can check or uncheck any change one by one. If they are checked, the preferences will be set to the new location. The original preference is also mentioned. When a preference line is present, it means that the preferences of the new location are not the same than the preferences of the old location.
You can either let the migrator set the new preferences according to the plan, or manually modify some preferences before or after the migration. In case you modify them before, you should restart the computation of the plan.
Rights
Same as preferences, but for rights.
Execute the plan
When you are ready, you can execute the plan.
We highly recommend to perform migration tests on a staging server before doing it on a production instance.
What else?
Unfortunately, running the migrator is not enough. This is a list of actions that you need to perform:
- since the pages have been renamed, pages doing {{include reference="..."/}} or {{display reference="..."/}} might not work. You should identify them and fix them.
- if you use the "SpaceDocs" or the "Spaces" panels, you should replace them by "Navigation", "Siblings" and "Children Panels".
- Some existing code may break slightly and needs to be adapted: code taking some user input and creating Spaces based on that will most likely display "\.", "\:" and "
" in the UI. Unless the code already cleans the user input and removes ".", ":" and "\" characters. So for example if a user enter a Space name of "my.space":- before 7.2: the code would create/display a Space named "my.space"
- after 7.2: the code will create/display a Space named "my\.space"
- Various XWiki API that used to return a space name have been returning a space reference string (i.e. list of spaces separated by dots and escaped "\.", "\:" and "
" characters). Code using those API may need to be updated. See XWiki 7.2 release notes for more details (this content could be copied in a section of the migration guide).
