7 Jan
2016
7 Jan
'16
9:34 a.m.
Hi Edy,
On 6 Jan 2016 at 17:57:35, Eduard Moraru
(enygma2002@gmail.com(mailto:enygma2002@gmail.com)) 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:Page@file.ext]] => [[label>>attach:space:Page@file.ext]] ||
[[label>>attach:doc:Page@file.ext]]
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