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? <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 ? What is the need? I’d find "wiki:page1/page2;locale=en_US” to be more explicit. > = 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? * Should we deprecate old Document-based APIs (and move them to legacy modules once we don’t use them anymore on our side)? 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. Thanks -Vincent > > Thanks, > -- > Thomas Mortagne
