Hi Marius, > On 9 Jul 2018, at 10:24, Marius Dumitru Florea > <mariusdumitru.flo...@xwiki.com> wrote: > > On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <enygma2...@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.morta...@xwiki.com> >> wrote: >> >>> On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol <vinc...@massol.net> >>> wrote: >>>> Hi Thomas, >>>> >>>> Good work! >>>> >>>> See below >>>> >>>>> On 29 Jun 2018, at 14:29, Thomas Mortagne <thomas.morta...@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
