[xwiki-devs] [Brainstorming] Problems for users with nested page when using references in APIs

Hi devs, We have a known issue with users starting with XWiki and reading documentation on xwiki.org and trying out stuff. Like yesterday morning someone was following the SSX tutorial and couldn’t make it work. The issue was that the page he was creating to put his SSX xobject in, had been created as a non terminal page (our default) and the tutorial was telling him to do: $xwiki.jsx.use(‘XWiki.SkinExt”)… We’ll have this issue everywhere and starting with XWiki 7.4+ we’ve made it very hard for users to start using the programming features of XWiki because of this (without mentioning that having to suffix with “WebHome” is not nice and natural). So I was wondering if we could help our users with this. Here’s one idea: * At the store API level (or just above in XWiki.getDocument()) do the following: ** try to load the passed reference as is and if it exists return it ** if it doesn’t exist and the passed reference doesn’t end with “WebHome", try to load the reference by adding “WebHome” to it ** if it doesn’t exist, return an empty doc (isNew = true) for the original reference asked (to be as backward compatible as possible) What this means is that if a WebHome page exists it won’t be possible to create a terminal page of the same name as its space by using getDocument(). There won’t be problems for existing duplicates (ie a space and a terminal page named the same). To solve this we could either introduce a new signature for getDocument() or introduce a TerminalDocumentReference class (that extends DocumentReference) and that the current getDocument() would understand as wanting a terminal document (we could use another name). And thus we could use the new TerminalDocumentReference class for example in the Create Page UI when the “terminal” checkbox is checked, thus allowing users to be able to create both types for the same name. I have the feeling that the small downside is really small compared to the advantages it would offer. For example it would solve the issue we have now with using a reference in macro. For example: {{include reference=“A.B.C.Mypage”/}} would work when MyPage is a NestedPage (i.e. A.B.C.MyPage.WebHome). WDYT? Thanks -Vincent PS: Related to this is http://design.xwiki.org/xwiki/bin/view/Proposal/DeprecatingSpaceAndSpaceRef… but that’s a lot more complex to implement and not for just now. The goal of this mail is to brainstorm about what we can do now.