7 Jul
2018
7 Jul
'18
7:55 p.m.
Great to hear you're progressing on this topic, Thomas!
My only note was also (as Vincent pointed out) on the link syntax. If we
went with "/" instead of "." was because people were more accustomed
to the
URL syntax and also that they would be more tempted to copy the URL as a
wiki link, instead of converting "/" to ".".
Now, why don't we apply the same logic to parameter separators (i.e.
instead of ";" to use "&" and, hopefully, instead of "?"
as the parameters
separator).
Also, are we considering anchors as well (i.e. using "#MyHeading" instead
of "|anchor='HMyHeading'")?
Ideally, it would be awesome if we could say that copy/pasting the exact
URL, right after the action part, would be supported when adding a wiki
link.
Slightly off-topic, but related to that last part, so it might not be a bad
idea to talk about it:
This actually gets me realising that we don't have a way to link in pure
wiki syntax to a page in a specified mode/action (i.e. not only view, but
also edit/create/delete/etc.). Sure, we have the "path:" type, but that's
not exactly designed for that, but for whatever else we might need, and it
require either writing, by hand, technical details or to use velocity (i.e.
$xwiki.getURL($doc, 'mode')).
Thanks,
Eduard
On Fri, Jun 29, 2018 at 7:20 PM, Thomas Mortagne <thomas.mortagne(a)xwiki.com>
wrote:
On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol
<vincent(a)massol.net>
wrote:
be closer
to URI/URL syntax?
This was my initial proposal but it was decided that ? was too common.
Need to finish with the TODO I listed first but for now I think the
idea is to use the page API as much as possible (but as an
experimental API so not in extensions yet) in new code and existing
code you work on that would benefit from it and improve it and
complete it along the way.
Hi Thomas,
Good work!
See below
> On 29 Jun 2018, at 14:29, Thomas Mortagne <thomas.mortagne(a)xwiki.com>
wrote:
>
> Hi xwikiers,
>
> Some of us discussed that for a while and created/improved
> http://design.xwiki.org/xwiki/bin/view/Proposal/
DeprecatingSpaceAndSpaceReference
and I
finally started working on it.
So here is what I pushed on master already:
= PAGE EntityType and Page*Reference classes
First thing first we now have a few new type in EntityType and the
corresponding typed Page*Reference helpers. One for each of the
element you can have in a page:
* PAGE
* PAGE_ATTACHMENT
* PAGE_OBJECT
* PAGE_OBJECT_PROPERTY
* PAGE_CLASS_PROPERTY
= Corresponding resolvers/serializer/providers
Each of the already existing DOCUMENT oriented resolvers and
serializers have their PAGE oriented implementation.
= Conversion from DOCUMENT to PAGE world
The entity resolvers automatically convert from/to DOCUMENT from/to
PAGE world references. Do yes using a resolver is the official way to
do that conversion.
= Model script service
The $services.model API also got his own new helpers to manipulate pages
= New syntax
Last but not least: pages reference have a very different syntax.
To summarize it's a filesystem path syntax with support for parameters.
Here is are a few examples:
wiki:page1/page2;param1=value1;param2=value2;en_US
wiki:page1/page2/attachment
../siblingpage
* separator: "/" between all elements except WIKI which is still ":"
* escaping: still "\"
* current, parent support: like in a filesystem you can refer to the
current page or parent page/wiki using "." and ".."
* parameters: we now have syntax to express the parameters of an
EntityReference. Each parameter is separated by a ";" at the end of
the entity name
Should we use “?” as the delimiter between reference and parameters to
<brainstorming>
Maybe we could even have a Page Reference be implemented as a
hierarchical URI?
(the wiki would be the scheme, the authority would be
empty and fragments would be empty).
In practice it would be hard since we need to have PageReference extends
EntityReference. But if we were starting from scratch we would maybe use a
URI or extend it.
Sill it might make sense to at least be closer on the syntax aspect and
thus use
“?” for the delimiter.
</brainstorming>
mean for example:
* default parameter: the syntax have the concept
of default parameter
which mean a parameter for which you don't need to indicate the name.
For example PAGE reference default parameter is “locale"
"a parameter for which you don't need to indicate the name” —> does that
wiki:page1/page2;en_US
Yes as you can see in the example I gave.
?
What is the need? I’d find "wiki:page1/page2;locale=en_US” to be more
explicit.
You can write the name if you want. The idea is that right now that's
actually our only really used parameter in reference and it's nicer to
not have to write "local=" all the time
= TODO
The next elements on the short term TODO list are:
* support for page references in XWiki#getDocument (which essentially
means add a fallback)
* support for page references in various macros (generally means
adding a "page" parameter as alternative to the existing "reference"
or "document" parameter)
What would be interesting now is to decide a usage strategy:
* Should we use the new page API for new code?
* Should we start converting old code to the page API? * Should we deprecate old Document-based APIs
(and move them to legacy
modules once we don’t use them anymore on our side)?
This is not going to happen so soon for sure, there is many places
which don't have page equivalent yet (just think about all the places
where we store document references).
It would be nice to have some doc/tutorial (maybe on
https://extensions.xwiki.org/xwiki/bin/view/Extension/Model%20Module) to
explain how to convert old code to new code and how to use the new APIs.
Of course, will work on documentation when I'm done with the tasks I
listed. Now most of the new PAGE API is very close to the DOCUMENT
related equivalent so it won't be hard for someone used to the
reference API in general to manipulate pages (that was one of the
goals).
Thanks
-Vincent
--
Thomas Mortagne
Thanks,
--
Thomas Mortagne