First batch of the new experimental Page oriented APIs

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

First batch of the new experimental Page oriented APIs

Thomas Mortagne
Administrator
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
* 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"

= 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)

Thanks,
--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

vmassol
Administrator
Hi Thomas,

Good work!

See below

> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]> 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?

<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

?

What is the need? I’d find "wiki:page1/page2;locale=en_US” to be more explicit.

> = 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)?

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.

Thanks
-Vincent

>
> Thanks,
> --
> Thomas Mortagne

Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

Thomas Mortagne
Administrator
On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]> wrote:

> Hi Thomas,
>
> Good work!
>
> See below
>
>> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

Eduard Moraru
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 <[hidden email]>
wrote:

> On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]>
> wrote:
> > Hi Thomas,
> >
> > Good work!
> >
> > See below
> >
> >> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]>
> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

vmassol
Administrator
Hi,

> On 7 Jul 2018, at 19:55, Eduard Moraru <[hidden email]> 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).
>
> 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')).

Regarding this we have https://jira.xwiki.org/browse/XRENDERING-22

Thanks
-Vincent

>
> Thanks,
> Eduard
>
> On Fri, Jun 29, 2018 at 7:20 PM, Thomas Mortagne <[hidden email]>
> wrote:
>
>> On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]>
>> wrote:
>>> Hi Thomas,
>>>
>>> Good work!
>>>
>>> See below
>>>
>>>> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]>
>> 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
>>

Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

Marius Dumitru Florea
In reply to this post by Eduard Moraru
On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <[hidden email]> 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.


>
> 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 <
> [hidden email]>
> wrote:
>
> > On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]>
> > wrote:
> > > Hi Thomas,
> > >
> > > Good work!
> > >
> > > See below
> > >
> > >> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]>
> > 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
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

vmassol
Administrator
Hi Marius,

> On 9 Jul 2018, at 10:24, Marius Dumitru Florea <[hidden email]> wrote:
>
> On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <[hidden email]> 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 <
>> [hidden email]>
>> wrote:
>>
>>> On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]>
>>> wrote:
>>>> Hi Thomas,
>>>>
>>>> Good work!
>>>>
>>>> See below
>>>>
>>>>> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]>
>>> 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

Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

Eduard Moraru
On Mon, Jul 9, 2018 at 11:45 AM, Vincent Massol <[hidden email]> wrote:

> Hi Marius,
>
> > On 9 Jul 2018, at 10:24, Marius Dumitru Florea <
> [hidden email]> wrote:
> >
> > On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <[hidden email]>
> 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
>

First time I see this syntax. I was not aware of these path-segment
parameters in the URI definitiion, however, I do not really find them
useful in XWiki's model and feel that they would only complicate things.

Let's take an example (the only one I managed to find that manages to make
some kind of sense):

[[wiki:TopPage/ChildPage;fr_FR/FinalPage;en_US||queryString="param1=value1"]]

What would this mean? That we want a link to the English translation of
"FinalPage" that is a child of the French translation of "ChildPage",
which, in turn, is a child of the (default translation or simply "page")
"TopPage"... and, for FinalPage, add the query string parameters
"param1=value1".

This does not make much sense to me, as we currently only have locale
parameters to EntityReferences, AFAIK. Also, what URL would this wiki link
be generating, since right now we don't have support for path-based
parameters in the URL handler. Do we plan to add it? IMO, it would scare
users even more than they are now :)

And finally, I am not sure it would be a good idea to parametrize the
individual EntityReferences (actually PageReferences themselves) that make
up the final PageReference, as it would exponentially increase the
complexity of the branches that would be possible in order to reach the
same page. Actually, I would kind of be against that:

[[wiki:TopPage/ChildPage;fr_FR/FinalPage]]
[[wiki:TopPage/ChildPage;en_US/FinalPage]]
[[wiki:TopPage;ro_RO/ChildPage;fr_FR/FinalPage]]
[[wiki;p1=v1:TopPage/ChildPage;fr_FR/FinalPage]]
etc.
...
(potentially, each path being a completely different page/entity; e.g. fr
content differs from the en content or wiki with parameter is something
else than wiki without)

Maybe we are missing a bit of context here, as Thomas did not explain the
need that generated this feature, together with some better example. From
his only example, I only concluded that he was talking about a query string
parameters syntax, hence my remark, to which I am still sticking:

Example:
[[wiki:TopPage/ChildPage/FinalPage?param1=value1&param2=value2]]

Thanks,
Eduard


> ?
>
> 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 <
> >> [hidden email]>
> >> wrote:
> >>
> >>> On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]>
> >>> wrote:
> >>>> Hi Thomas,
> >>>>
> >>>> Good work!
> >>>>
> >>>> See below
> >>>>
> >>>>> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]
> >
> >>> 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
>
>
Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

Thomas Mortagne
Administrator
In reply to this post by vmassol
Yes each element can have parameter

Le lun. 9 juil. 2018 à 10:46, Vincent Massol <[hidden email]> a écrit :

> Hi Marius,
>
> > On 9 Jul 2018, at 10:24, Marius Dumitru Florea <
> [hidden email]> wrote:
> >
> > On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <[hidden email]>
> 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 <
> >> [hidden email]>
> >> wrote:
> >>
> >>> On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]>
> >>> wrote:
> >>>> Hi Thomas,
> >>>>
> >>>> Good work!
> >>>>
> >>>> See below
> >>>>
> >>>>> On 29 Jun 2018, at 14:29, Thomas Mortagne <[hidden email]
> >
> >>> 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
>
>
Reply | Threaded
Open this post in threaded view
|

Re: First batch of the new experimental Page oriented APIs

Thomas Mortagne
Administrator
In reply to this post by Eduard Moraru
The concept of parameter already exist in EntityReference, the point is
just to finally have an EntityReference syntax which fully supports it.

Also you are mixing different things as Marius already pointer out, this is
not a link syntax but a reference syntax so the anchor does does really
make sense here for example.

Le lun. 9 juil. 2018 à 14:07, Eduard Moraru <[hidden email]> a écrit :

> On Mon, Jul 9, 2018 at 11:45 AM, Vincent Massol <[hidden email]>
> wrote:
>
> > Hi Marius,
> >
> > > On 9 Jul 2018, at 10:24, Marius Dumitru Florea <
> > [hidden email]> wrote:
> > >
> > > On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <[hidden email]>
> > 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
> >
>
> First time I see this syntax. I was not aware of these path-segment
> parameters in the URI definitiion, however, I do not really find them
> useful in XWiki's model and feel that they would only complicate things.
>
> Let's take an example (the only one I managed to find that manages to make
> some kind of sense):
>
>
> [[wiki:TopPage/ChildPage;fr_FR/FinalPage;en_US||queryString="param1=value1"]]
>
> What would this mean? That we want a link to the English translation of
> "FinalPage" that is a child of the French translation of "ChildPage",
> which, in turn, is a child of the (default translation or simply "page")
> "TopPage"... and, for FinalPage, add the query string parameters
> "param1=value1".
>
> This does not make much sense to me, as we currently only have locale
> parameters to EntityReferences, AFAIK. Also, what URL would this wiki link
> be generating, since right now we don't have support for path-based
> parameters in the URL handler. Do we plan to add it? IMO, it would scare
> users even more than they are now :)
>
> And finally, I am not sure it would be a good idea to parametrize the
> individual EntityReferences (actually PageReferences themselves) that make
> up the final PageReference, as it would exponentially increase the
> complexity of the branches that would be possible in order to reach the
> same page. Actually, I would kind of be against that:
>
> [[wiki:TopPage/ChildPage;fr_FR/FinalPage]]
> [[wiki:TopPage/ChildPage;en_US/FinalPage]]
> [[wiki:TopPage;ro_RO/ChildPage;fr_FR/FinalPage]]
> [[wiki;p1=v1:TopPage/ChildPage;fr_FR/FinalPage]]
> etc.
> ...
> (potentially, each path being a completely different page/entity; e.g. fr
> content differs from the en content or wiki with parameter is something
> else than wiki without)
>
> Maybe we are missing a bit of context here, as Thomas did not explain the
> need that generated this feature, together with some better example. From
> his only example, I only concluded that he was talking about a query string
> parameters syntax, hence my remark, to which I am still sticking:
>
> Example:
> [[wiki:TopPage/ChildPage/FinalPage?param1=value1&param2=value2]]
>
> Thanks,
> Eduard
>
>
> > ?
> >
> > 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 <
> > >> [hidden email]>
> > >> wrote:
> > >>
> > >>> On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <[hidden email]>
> > >>> wrote:
> > >>>> Hi Thomas,
> > >>>>
> > >>>> Good work!
> > >>>>
> > >>>> See below
> > >>>>
> > >>>>> On 29 Jun 2018, at 14:29, Thomas Mortagne <
> [hidden email]
> > >
> > >>> 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
> >
> >
>