Nested Documents

Last modified by Vincent Massol on 2024/02/26 17:56



Problem with nested spaces

From a UI perspective, differentiating pages `A.B.C.WebHome` and `A.B.C` could become very difficult.

Moreover, we know that a lot of users do not understand the notion of spaces, and they are lost when you look at them during usability sessions.

Problem with parent/child relationship

The situation is even worse if you consider the notion of parent/child documents, which is completely unrelated to the actual hierarchy. It creates confusion!

Idea: Concept of nodes a.k.a Nested Documents

To fix these problems, we propose to introduce the notion of "nested documents", i.e. the ability to create documents inside documents.

Say differently, if a page `A.B.C` exists, nothing should stop the user to create the document `A.B.C.D`.

In JCR[1], there is only one concept: the "node". A node can have a content, and a list of child nodes. In XWiki, documents could become a kind of nodes, and we do not need spaces anymore.

About Parent/Child relationship

Confusing. We deprecate it and put it as an option disabled by default.

About rights

If we don't have space anymore, we could ask ourselves: "How the rights will be propagated to the children documents? How do we distinguish rights applied to the documents and the rights applied to the children?"

I think the easiest solution is to inherit the rights from the parent to the children, unless an object prevent it. We already have this kind of mechanism with XWikiRights and XWikiGlobalRights. XWikiRights would be applied for the current document, and XWikiGlobalRights for the document and its children.

Nested Document as a UI trick

But changing the XWiki model is a lot of work, that we don't have time to achieve for 7.2. So we propose to make it step by step.

Create a space each time a page is created

The first step is to change the UI to hide the notion of space to the users. Concretely, each time a user wants to create a page called `A`, we actually create the document `A.WebHome`. So any child of this page would be created in the `A` space, like `A.Child`. But this child would be in a space too, so it would be `A.Child.WebHome` actually.

Hide 'WebHome'

Then, when we display the `A.WebHome` page, we remove all mentions to the `WebHome` name. In the UI, it will just be presented as the document `A`. This is a good point, knowing the fact that the term `WebHome` have no sense for the user, neither in English or in other languages.

Problems with applications

Again, these changes are only for the UI. For the applications, it is the developer's job to decide if the app will create documents like `Document.WebHome` or basic documents just as before.

The question of what to do with AWM comes up. When a user creates an entry, should it be a new-kind-of-document (`AppSpace.Entry.WebHome`) or an old-kind-of-document (`AppSpace.Entry`)? The first option is good for consistency and for the new possibilities it offers, but the second is better for retro-compatibility. And the question will be the same for all existing applications that create pages. I believe we should answer these questions on a case-by-case basis and deserve their own mail threads.

Problem: 2 kind of pages

Pages created with the new UI will actually be spaces where we can create "child" documents. But in the case of upgraded wikis, we will have pages that are not spaces and that are not able to create child documents. Same for pages created by application. How do we explain to the user that some page can have children and some not?

Future (implement the concept in the model)

Finally, after these steps are accomplished in 7.2 and polished until the end of the 7.x cycle, we will refactor the XWiki model (something we dream about for years).

Problems with this idea

  • Path enumeration as Unique ID: a lot of things get broken when a space (a document) in the hierarchy is renamed/moved.

Nested Documents in the UI as an option

  • Nested Documents in the UI is just a special view of Nested Spaces. A bit similar to the Simple/Advanced user feature or the Show Hidden Documents one.    
  • If the concept of spaces exists in the model (which is the case ATM), it will surface to the users when they start writing scripts for example.


  • 2 versions of the top level menu.
  • 2 versions of the create page form.
  • 2 versions of the create page panel.
  • What about the spaces macro? 2 different behaviours? If not, should the space macro be used in the default Dashboard?


  • Panels: most edited spaces.
  • Panels: space documents (display all documents of the current space)


Get Connected