[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/DeprecatingSpaceAndSpaceRefe... 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.
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"). 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
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.
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/DeprecatingSpaceAndSpaceRefe... 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
participants (3)
-
Eduard Moraru -
Guillaume Delhumeau -
Vincent Massol