Hi Edy, On 6 Jan 2016 at 17:57:35, Eduard Moraru ([email protected](mailto:[email protected])) wrote:
Hi devs,
As XWIKI-12920 [1] mentions, we need to hide "WebHome" references in the wiki syntax for links and images (for now) in order to be consistent with what we did in the UI.
What this means is that [[label>>Page.WebHome]] should be equivalent to [[label>>Page]].
The plan is to apply the same logic as we did for URLs and detailed by Vincent in "Solution 2" in his comment on the issue [2].
In order to achieve this, Vincent proposed to introduce a new "space:" resource type and make this new type the default instead of "doc:" which is the current default.
Before: [[label>>Page]] => [[label>>doc:Page]] After: [[label>>Page]] => [[label>>space:Page]] if "Page.WebHome" exists, or => [[label>>doc:Page]] if ".Page" exists, or => wanted link to create "Page.WebHome" when clicked.
Using either the "doc:" or the "space:" versions manually will resolve the requested resource, without doing any fallback resolution (which is applied only for the no-prefix version).
For the same consistency reason, we need to apply the same fallback to the "attach:" resource type, e.g: [[attach:[email protected]]] => [[label>>attach:space:[email protected]]] || [[label>>attach:doc:[email protected]]]
However, a resource is defined as ((type:) resource) so for attachments we would need to extend the type's definition to allow it to contain ":" in the type name (i.e. "attach:doc" and "attach:space") so that more variations are tested when resolving a link reference before treating it as a generic/untyped reference (this is where the fallback mechanism kicks in).
There is also the image syntax that needs to be extended to support the same fallback logic, so something like: image:Page => image:space:Page || image:doc:Page
In all these cases: * link space: prefix, * link attach:doc and attach:space prefixes and * image space: and doc: prefix ... we would be breaking backwards compatibility in the sense that if a wiki with the name "space" (and/or "doc", depending on which case of the above you are) already existed in the wiki farm, any links pointing to documents in that wiki from other wikis will be broken, because, for example [[label>>space:Page]] no longer points to the document "space:Page.WebHome" (from wiki "space"), but to the document "Page.WebHome" from the current wiki (where the link is made). To fix this, one would have to write [[label>>space:space:Page]] instead.
I guess we could/should write a migrator to try to fix most of these cases automatically (like we fix links to a document that was renamed), but a couple of links will be unfixable if they are built programatically (e.g. by velocity scripts) and the process could prove to be extremely lengthy one (due to the parsing, processing, serialization and resaving of each document).
Please feel free to comment on the above described approach.
This looks good to me (I don’t see any real alternative anyway). My only comment is one that users have already given us: it’s about the WYSIWYG editor. If you currently use the WYSIWYG editor to edit a page that has, for example, [[label>>Space.Page]], make no modification and save it, you’ll get [[label>>doc:Space.Page]] if you check the wiki content. Basically the WYSIWYG editor normalizes the content (since it does a parsing/rendering). Some users have already complained that they didn’t understand this format of “doc:” and that’s normal since they didn’t enter it themselves. So once this is implemented they’ll get [[label>>space:Something1.Something2]], which is going to be slightly more complex since there’s no notion of “space” in the UI. But it’s about the same problem and similar complexity. What we probably need to implement (in some future, not saying we have to do this now :)) is to add some metadata to the Blocks so that Renderers can get some hint on how to render them in a certain way. So IMO this could wait and it’s ok for now.
Thanks, Eduard
P.S.: I did not mention macro parameter references which would also need a solution for hiding the "WebHome" part, but I`d prefer it if we handle that another time / in another thread.
I think one solution is to review the Macros that accept a reference as parameter and modify them. For macros that should support any reference (i.e. url:, space:, doc:, etc), they should use ResourceReference and we could introduce some EntityResourceReference for macros who should support only entity references (i.e. “space:” or “doc:” only). Or we could just use ResourceReference and have each macro perform the check to only handle the resource types it supports. The good part is that the conversion done between the String specified by the user and the Macro parameters is done automatically by the XWiki framework so even if we change a Macro Parameter type from, say, String to ResourceReference, we wouldn't break any API or any usage :) WDYT? Thanks -Vincent
---------- [1] http://jira.xwiki.org/browse/XWIKI-12920 [2] http://jira.xwiki.org/browse/XWIKI-12920?focusedCommentId=89129&page=com.atl...