On 9 Jul 2018, at 10:24, Marius Dumitru Florea
<mariusdumitru.florea(a)xwiki.com> wrote:
On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <enygma2002(a)gmail.com> wrote:
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).
You are mixing the query string with the URL path parameters
https://doriantaylor.com/policy/http-url-path-parameter-syntax . The query
string is for the entire URL/path while each path segment can have its
parameters. In our case each entity reference from the chain can have its
own parameters.
That’s a good rationalization :) I like it!
Does Thomas’s implementation allows each entity reference in the chain to have parameters,
such as for example:
wiki:page1;a=b/page2;c=d/image.png;e
?
Thanks
-Vincent
>
> 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:
>>> 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
>> be closer to URI/URL syntax?
>>
>> This was my initial proposal but it was decided that ? was too common.
>>
>>>
>>> <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>
>>>
>>>> * 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
>> mean for example:
>>>
>>> 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?
>>
>> 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.
>>
>>> * 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
>>>
>>>>
>>>> Thanks,
>>>> --
>>>> Thomas Mortagne
>>>
>>
>>
>>
>> --
>> Thomas Mortagne