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