If we go in that direction (which seems dangerous to me), you should also consider the Query Module. In a lot of queries you need to know the difference between terminal/non terminal documents. For example, if you need to get the list of all pages holding an XObject of the XClass "MyClass.WebHome" (note the WebHome part of the class name).
What should we do for this use-case? Putting more documentation in that specific module so the user knows that she needs to add the "WebHome" part in the class name? Rewrite the queries dynamically? Implement http://design.xwiki.org/xwiki/bin/view/Proposal/DeprecatingSpaceAndSpaceReference ASAP? Thanks, 2016-08-26 12:21 GMT+02:00 Vincent Massol <[email protected]>: > > > On 26 Aug 2016, at 12:18, Eduard Moraru <[email protected]> wrote: > > > > Hi, > > > > On Fri, Aug 26, 2016 at 11:19 AM, Vincent Massol <[email protected]> > wrote: > > > >> 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) > >> > > > > Just a reminder that this would not be consistent with what we do in the > UI > > (view mode URLs and untyped syntax link resolution), as in those cases we > > default to a new non-terminal page instead. > > > > > >> > >> 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? > >> > > > > Not sure we should cross this line, at the current state that we are. I > > personally find it easier to explain it that the UI does this "trick", > but > > the platform works with what you give it, instead of having to explain > all > > the new tricks from the platform as well (which will eventually probably > > turn into "pitfalls”). > > How do you explain that on xwiki.org everywhere we show an example with a > reference? > > How do you explain it in XE itself? (when a user uses the include macro > and needs a reference for example and in countless other use cases) > > Thanks > -Vincent > > > Thanks, > > Eduard > > > >> > >> Thanks > >> -Vincent > >> > >> PS: Related to this is http://design.xwiki.org/xwiki/ > >> bin/view/Proposal/DeprecatingSpaceAndSpaceReference 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. > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > -- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
