Re: [xwiki-devs] First batch of the new experimental Page oriented APIs

On 7 Jul 2018, at 19:55, 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). 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 &lt;thomas.mortagne(a)xwiki.com&gt; wrote: > On Fri, Jun 29, 2018 at 3:10 PM, Vincent Massol &lt;vincent(a)massol.net&gt; > wrote: >> Hi Thomas, >> >> Good work! >> >> See below >> >>> On 29 Jun 2018, at 14:29, Thomas Mortagne &lt;thomas.mortagne(a)xwiki.com&gt; > 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 >