On Sat, Jul 7, 2018 at 8:55 PM, Eduard Moraru <[email protected]> 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 < > [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 > > >
