Hi, > On 7 Jul 2018, at 19:55, 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). > > 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 <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 >>
