Lost in space ;-)

I want to do my first steps with velocity, but I have problems to understand the absolute basic terms.
I want to use the

public  createDocumentReference( wiki,  space, page)

method, of the ModelScriptService class, but what are the reference name of wiki, space and page or how can I see them in my existing xwiki for a exiting page?
And what means the term “space” at all?
Is there any basic documentation giving information to these basics?

Regards Rainer

That can indeed be a tricky one for newcomers. You can find a bit of history on the subject on https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/ContentOrganization/NestedPagesMigration/.

Note that to be a bit closer to what you have in the UI you can use Page related APIs instead Document ones in many case (in your example, that would be #createPageReference).

Even the link Bitloom - An overview of the XWiki’s RESTful API is about Rest API but it describes in small details what’s Space, page in XWiki data model heading. Visually you’ll understand it.

Ok, your answers are in the right direction and the links too, but all much to unspecific for me.
The simple questions

  1. where can I get the spaces ref names and the page name of a existing page
  2. who can I use the below method with these references
    are not answered.
ModellScriptService.createDocumentReference(String wiki,
                       List<String> spaces,
                       String page)

After a lot of trail and error, I can answer the questions myself and maybe it is helpful for other beginners:
At the page information the page reference is shown (e.g.:Sandbox.SubSand.WebHome)
This string contains all space references and the page reference separated by dots.
So in the above example the references are:
page “WebHome” is contained in space “SubSand” which is contained in space “Sandbox”
! so in my xwiki all pages have the same page reference “WebHome” and the name of the page is the space in the deepest containment level.

To get the right document reference the spaces has to be provided as a list. So the method call should look like this:

$services.model.createDocumentReference('', ['Sandbox', 'SubSand'],'WebHome'))

I’m no sure if all details are right, but maybe some of the experts can give some hints for correctness.

Regards Rainer

2 Likes

That’s pretty much it, but let’s set some vocabulary straight:

First of all, note that the “reference” is a generic concept in XWiki, of an object that uniquely identifies a resource in XWiki. Most of the times, the resources you’ll care about are pages in XWiki (although they can also be other stuffs, but less frequent).
References are a tree-like concept, built as a linked list: a reference will be made of “segments” that will always have a name and a parent; the parent also has a name and a parent and so on. It stops when the parent is null. Depending on what they identify, these resources will also have differeny types. You can think of these references as you think of the URLs of things: in the same way in which an URL is made of segments (separated by / ) and allows to address things on the internet, references are made of segments and allow to uniquely identify a resource in XWiki (actually, the segments from the references will be used to produce the URL of a page in XWiki, but it’s not relevant to this topic).

As Thomas mentioned there are actually 2 types of references that can be used to identify a page with content in XWiki:

  • a DocumentReference, where the page will always have the name ‘WebHome’ and it will have one space parent (which can have another space parent and so on); In this case we use the terminology “document name” for “WebHome” and “space name” for the names of the parent spaces.
    Indeed, what you will see on the screen is the name of the last space presented as the “page name”. This is the ‘old’ model, sort of say, which is why the code concepts don’t match that well what you see on the UI. The “reference” of the page in this case, what makes it unique amongst all other pages from the wiki is the whole DocumentReference, that includes the space names list and the page name. You can think of this as a filesystem structure, where the spaces are the folders and the documents (pages) are the files.
    Sometimes, for legacy reasons, we will also use the vocabulary “page name” to designate the document name (the ‘WebHome’ segment). This may add confusion, but it should be rather clear from the context whether we’re talking about the last segment from the DocumentReference or whether we’re talking about the page name as it’s displayed on the UI (actually, if we want to be strict here the “page name” will never be displayed on the UI, it’s the page title that is displayed on the screen; for a page creation the last space reference name is generated automatically from the title but they can diverge afterwards).
  • a PageReference, which has the name that you see on the UI (the one generated from the page title on creation) and has as a parent another page which will have a name and a parent page, etc. This is strictly for reference names, the relation between the last reference segment and page title is the same as in the case of DocumentReferences: it’s generated automatically upon creation but can diverge afterwards).
    This corresponds very well to what you see on the UI in terms of terminology. The only issue is that we don’t display this page reference on the UI anywhere as a reference, contrary to the DocumentReference that is visible in the information tab, as you noticed.

Note that both these types of references allow to address the same resources (pages with content), it’s just 2 different ways to address the same data from the database, one old and one new. A simplified way to express the relation between the DocumentReferences and PageReferences is that basically the “WebHome” doesn’t exist anymore in PageReferences and all spaces names from a DocumentReference become page names in PageReferences. See the links from tmortagne, they should explain this and also https://extensions.xwiki.org/xwiki/bin/view/Extension/Model%20Module .

So, basically, in order to use these concepts, you need to attentively check the APIs that you’re using to see whether they expect a DocumentReference or a PageReference for refering the resource you’re trying to refer, and build the type of reference you need. Spoiler: most APIs will use DocumentReference, the migration to PageReferences is not yet complete.

Hope this helps, even if it’s a bit more general concepts and less practical.

1 Like