<
From version < 10.2 >
edited by Vincent Massol
on 2016/03/25
To version < 11.1 >
edited by Vincent Massol
on 2016/03/25
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -1,7 +1,42 @@
1 +{{box cssClass="floatinginfobox" title="**Contents**"}}
1 1  {{toc/}}
3 +{{/box}}
2 2  
3 -= A bit of history =
5 += History =
4 4  
7 +== Executive Summary ==
8 +
9 +Up to XWiki 7.1, there has been 2 ways to organize content in XWiki:
10 +* Wiki > Space > Page (which includes rights inheritance and administration features)
11 +* Page > Child Page > Child Page of child Page > ... (which is used for hierarchical navigation purposes)
12 +
13 +Note that both are independent: a page can have a parent Page in a different Space/Wiki than its own .
14 +
15 +While this was working, we've found that it could create confusion for users, leading to questions such as:
16 +* Should I create a sub-Wiki or a Space for my team?
17 +* Which navigation should I put on my home page: list of Spaces or tree view of Pages?
18 +* Can I set rights on a page that is under a space?
19 +
20 +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
21 +Nested Spaces, offering the following features:
22 +* Unified way to handle hierarchical navigation (Page > Sub-page > Sub-sub-page >...)
23 +* Navigation reflected in URLs (.../PageA/PageB/PageC)
24 +* Inheritance of access rights (rights on PageA apply to PageB and PageC, unless defined otherwise. Rights on PageB supersede those on PageA
25 +and also apply to PageC, and so on.)
26 +
27 +In the end, we took the opportunity to move from the previous way to this new way of organizing pages in XWiki 7.2.
28 +
29 +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:
30 +* We've hidden the parent-child feature(((
31 +{{info}}
32 +Even though it's hidden you can still turn it back on if you need it while you migrate your content to use Nested Spaces: set the ##core.hierarchyMode## property to ##parentchild## in the ##xwiki.properties## configuration file.
33 +{{/info}}
34 +)))
35 +* 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/)
36 +* 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.
37 +
38 +== Detailed Explanations ==
39 +
5 5  Before the introduction of the Nested Pages concept (in 7.2), the content in a wiki was organized like this:
6 6  
7 7  * we had some **Spaces**, that you can see as "folder"
... ... @@ -11,13 +11,13 @@
11 11  
12 12  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").
13 13  
14 -== Parent/Child relationship ==
49 +=== Parent/Child relationship ===
15 15  
16 16  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//.
17 17  
18 18  Some applications used this parent/child relationship to organized their data. For them, this relationship is crucial.
19 19  
20 -== The introduction of the Nested Pages concept ==
55 +=== The introduction of the Nested Pages concept ===
21 21  
22 22  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.
23 23  
... ... @@ -41,7 +41,7 @@
41 41  
42 42  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**.
43 43  
44 -== Issue with the Parent/Child relationship ==
79 +=== Issue with the Parent/Child relationship ===
45 45  
46 46  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?
47 47  
... ... @@ -51,7 +51,7 @@
51 51  
52 52  This concept are good in theory. But, how can we handle existing content when an XWiki upgrade is made?
53 53  
54 -= Principle =
89 += Migration =
55 55  
56 56  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.
57 57  
... ... @@ -63,7 +63,7 @@
63 63  
64 64  To perform this conversion, we have developed an application called [[Nested Pages Migrator Application>>extensions:Extension.Nested Pages Migrator Application]].
65 65  
66 -= Fix the hierarchy =
101 +== Fix the hierarchy ==
67 67  
68 68  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/).
69 69  
... ... @@ -81,7 +81,7 @@
81 81  #end
82 82  {{/code}}
83 83  
84 -= Install Nested Pages Migrator Application =
119 +== Nested Pages Migrator Application ==
85 85  
86 86  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!
87 87  
... ... @@ -101,14 +101,13 @@
101 101  
102 102  You will find the following page:
103 103  
104 -image:Migrator1.png
139 +{{image reference="Migrator1.png"/}}
105 105  
106 -There is 2 actions:
107 -
141 +There are 2 actions:
108 108  * **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.
109 109  * **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.
110 110  
111 -== Options ==
145 +=== Options ===
112 112  
113 113  But first, let's talk about the options.
114 114  
... ... @@ -129,9 +129,9 @@
129 129  
130 130  Note: you can select the classes to exclude by clicking on the "excluded classes" field:
131 131  
132 -image:excludedClasses.png
166 +{{image reference="excludedClasses.png"/}}
133 133  
134 -== Plan ==
168 +=== Plan ===
135 135  
136 136  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.
137 137  
... ... @@ -140,8 +140,9 @@
140 140  {{/info}}
141 141  
142 142  This is what a plan looks like:
143 -image:plan.png
144 144  
178 +{{image reference="plan.png"/}}
179 +
145 145  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.
146 146  
147 147  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:
... ... @@ -162,13 +162,13 @@
162 162  * **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.
163 163  * **set parent**: click on this button to manually set a parent for that page. {{warning}}Note: this action will be performed immediately, not when the plan will be executed. It is a shortcut to help you changing the parent without going to the page.{{/warning}}
164 164  
165 -=== Preferences ===
200 +==== Preferences ====
166 166  
167 167  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.
168 168  
169 169  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.
170 170  
171 -=== Rights ===
206 +==== Rights ====
172 172  
173 173  Same as preferences, but for rights.
174 174  
... ... @@ -180,11 +180,11 @@
180 180  However, you can use this plan to identify where rights will be changed by the migration. Indeed, even if the proposed actions to fix them are bad, the algorithm is able to identify where rights problems happens. Save this list and you will be able to fix the rights issues by yourself after the migration.
181 181  {{/info}}
182 182  
183 -== Execute the plan ==
218 +=== Execute the plan ===
184 184  
185 185  When you are ready, you can execute the plan.
186 186  
187 -image:PlanExecuting.png
222 +{{image reference="PlanExecuting.png"/}}
188 188  
189 189  {{warning}}
190 190  Be patient. The process could be very long. It will use a lot of server resources, so we recommend to don't let users accessing the wiki during the process. (For example, you can temporary forbid remote connections to your servlet container and access XWiki through an SSH tunnel for yourself.)
... ... @@ -196,7 +196,7 @@
196 196  
197 197  **We highly recommend to perform migration tests on a staging server before doing it on a production instance.**
198 198  
199 -= What else? =
234 +== What else? ==
200 200  
201 201  Unfortunately, running the migrator is not enough. This is a list of actions that you need to perform:
202 202  

Get Connected