Hi devs,
I've started implementing XRENDERING-290 (I've spent already 1 day on it and
have most of it done) but as I progressed I've realized we need to decide on
something.
It's an interesting problem! :)
So the issues asks for support a "user" prefix in links to link to user
profiles such as in: [[label>>user:evalica]]
Explanation of Problem
==================
I started with implementing a new Reference Type Parser to add support for the
"user" prefix. I soon realized that we cannot implement this in XWiki Syntax
2.1 since it means if a user currently has [[label>>user:evalica]] it means
pointing to the "user" wiki and to the page named "evalica".
Thus we need to add this in a new syntax only (i.e. XWiki Syntax 2.2).
Now the problem is that currently Reference Type Parsers are components and
implementing a new component means it's going to be available to XWiki Syntax
2.1. So I spent a substantial amount of time to allow syntaxes to specifically
specify the list of prefixes that they support. This is done, I just need to
push it.
Now this all looked good till I started implementing the
UserXHTMLLinkTypeRenderer… I realized that I would need to be able to transform
a String (supposed to represent a username) into a User reference and even
though we don't have an API for this ATM this would normally mean to depend on
the Platform User module… which is a big no go since Rendering cannot depend on
Platform.
Side Note:I also realized that XRENDERING-290 could also be extended to support
displaying the user's avatar with image:user:evalica. This is currently done
with the {{useravatar}} macro (which is also wrongly located in Rendering and
should be in platform for the reason explained!!).
So I thought I could just have the UserResourceReferenceTypeParser and
UserXHTMLLinkTypeRenderer classes implemented in the Platform User module but
that still meant that the XWiki Syntax 2.2 needs to reserve the "user" prefix.
Then I realized that any time we will want to add support for a new prefix we
would need to introduce a new Syntax version which is a huge PITA and a pity.
I thought about several solutions.
Solution 1
========
* Consider that each syntax can reserve prefix type namespaces and this just
means that if the user wants to write a link to a document a wiki named after
one of these prefixes then he needs to use the full format:
[[label>>doc:<wikiname>:….]]
* Thus XWiki Syntax 2.2 would just add the "user" prefix to the reserved list
of prefix type namespaces.
PRO:
* I have this code ready to be pushed on my computer
* Doesn't change the current XWiki Syntax notation
CONS:
* Requires a new syntax whenever a new type parser is added (after a syntax has
been released as final)
* Creates a relationship between the syntax and implementations (the User
module will provide an impl. for supporting the reserved "user" namespace).
Solution 2
========
* Don't implement support for linking to users using resource types and add a
{{userlink}} macro and move both macros in platform.
PRO:
* Simple, no need for a new XWiki Syntax
CONS:
* Not integrated in the syntax
* Not very logical since as a user you would want to write:
[[label>>user:evalica]]
Solution 3
========
Force XWiki Syntax 2.2 to *ALWAYS* use the full form when creating a link, i.e.
all links to doc would need to be written: [[label>>doc:reference]]
PRO:
* Solves all future needs for new reference types and makes the syntax
extensible for this.
CONS:
* Harder to write links to documents and users will need to get used to it
Solution 4
========
Invent a new syntax when you wish to write links using a type prefix and keep
the current link syntax for references to documents:
* Ref to a doc: [[label>>docref]] (e.g. [[label>>xwiki:Main.WebHome]])
* Ref to anything but using the type prefix: [[label>>>prefix:reference]] (e.g.
[[label>>>doc:doc:Main.WebHome]]: link to a wiki named "doc")
PRO:
* Still easy to make refs to documents
* Makes the syntax extensible by allowing new types to be added
CONS:
* Changes the syntaxes since it means introducing a new link notation
[[label>>>ref]]. Also means that references to docs cannot start with ">"
anymore (but that's not a real issue IMO)
* A bit more complex to implement obviously since it needs a change to the
javacc parser
Conclusion
==========
My POV:
* The more correct solution is solution 3 but it makes harder to write links to
documents so I believe that's going to be a problem since it's the main use
case.
* Solution 1 is already implemented on my computer and I just need to make a
push to have it so the simplest for me. I think it could be acceptable since we
don't introduce new type parsers all the time. But it's not perfect obviously.
* Solution 4 is the most tempting for me even though it's more work. I've
suggested ">>>" but we could imagine a different notation. Other ideas include
using [[label>>doc:doc:Main.WebHome||typed="true"]] (ie setting a "type" param
to mention that it's referring to a typed reference). It has the advantage of
not requiring changes to the javacc parser but it has more chars to type for
the user and is thus more complex for the user.
Do you have an opinion? WDYT? Should I push what I have for now and make
changes later?
Thanks
-Vincent
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
