Re: [xwiki-devs] [VOTE] New {{display}} macro and changes to the {{include}} macro - Second Try

Seems to me that there has been an agreement to revert to the old

has soon as possible,

but I do not see the link with XWiki 3.2.1 release ? On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge <guillaume(a)xwiki.com>

> Hi guys, > > can we please finish and/or close this vote so that Sergiu can act on it > and we can release XE 3.2.1? > > Thanks in advance, > > Guillaume > > On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle &lt;dgl(a)softec.lu&gt; wrote: > >>> >>> On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne < >> thomas.mortagne(a)xwiki.com&gt;wroteote: >> >> On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol &lt;vincent(a)massol.net&gt; >> wrote: >>>> Hi guys, >>>> >>>> Ok here's second version taking into account Denis and Marius > comments: >>>> >>>> * Have a {{display}} macro which is equivalent to context=new and >>> resolve=source (ie links resolved on the reference being displayed) >>> >> >> +1, this is simpler and clearer >> >>> * Have a compatibility mode for the {{include}} macro with the > following >>> behavior: >>>> ** {{include}} in non-compatiiblity mode is equivalent to >> context=current >>> and resolve=current (ie links resolve on the including document) >>>> ** {{include}} in compatiiblity mode is equivalent to context=current >> and >>> resolve=source (the default we have now and which we need to not break >>> people) >>> >>> * We would have a rendering.macro.include.compatibility configuration >>> property >> >>> * We would set that property to true by default for 3.3 to give some > time >>> for people to adjust >>>> * We would set that property to false by default for 3.4 >> >> >> -0, this is for me useless, since I doubt many understand that and have >> notice this change in 3.x. I was unaware myself of this change, and I

>> not >> remember any discussion about it in the past. If you have a ML thread > about >> the rational behind this mistake, I am still interested, but I it could >> have >> been introduce without notice, it could be removed as well. >> At least, this should not be in compatibility mode by default. >> >> >>> So you propose to get back to previous behavior by default, right ? >>> Given the fact that it has been changed very recently maybe we should >>> have the property false right away and say it was a mistake ? >>> >> >> I agree. >> >> >>>> * Deprecate "document" parameter for the include macro and add a new >>> "reference" parameter + a new "type" parameter (I forgot that one in

>>> first email). The "type" parameter represents the Entity Reference > Type. >>>> * Also add a "type" parameter for the display macro (I forgot that > one >> in >>> my first email) >>>> * Have the "type" parameter default to "document". >>> >> >> +1 >> >> >>> I forgot to mention the following point: >>> ** The {{include}} macro has a new "resolve" parameter (the "context" > one >>> is deprecated) which can be "current" or "source". >>> This is needed since there are use cases both resolve=current and >>> resolve=source for the include macro. Once again the context param has >>> nothing to do with how links/images are resolved. And again the writer >> of a >>> page isn't necessarily the same as the person who's going to include > your >>> page. >> >> >> I am still -1 on this last point. First, it is precisely because it is > very >> difficult to understand the differences between the context and the > resolve >> parameter that I am against it. I repeat myself, but not having the

>> behavior between $doc.getURL() and [[ ]] is for me not acceptable,

>> the >> included document author could no more count on the equality of these

>> resolution methods. If I have been aware of that change in 3.x I would > have >> veto it already. >> >> Moreover, if the writer of the included document is the not the writer

>> the including document, he would be better if he could stay in control

>> how links/image are accessed, protecting the way its own document

>> and >> not leaving this to the including document author. This is why I have >> proposed to move the resolve parameter on individual links, which is

>> flexible and understandable. >> >> Currently, AFAIK, during an {{include}} (without context=new), using >> velocity, the included document do not have an easy access to itself >> (without knowing its own name), but you want this possibility for

>> and you want it globally ? This seems to me curious that something >> difficult >> to do by code would be easy by syntax. >> >> If you still want to convince me, please explain why you need $doc and >> relative links to diverge, especially without the included document > author >> to be aware of this. What cannot you do with {{display}} that would be >> possible by {{include resolve=source}}; and that would not be better > served >> by giving the control to the included document author ? >> >> Denis >> >>> >>>> Some additional notes: >>>> * The person writing a page is not necessarily the same as the person >>> writing an include. >>>> * With the new sheet mechanism there are a lot less use cases for the >>> include in compatibility mode. >>>> >>>> Please vote again. >>>> >>>> Here's my +1 >>> >>> +1 (with the previous note) >>> >>>> >>>> Thanks >>>> -Vincent >>>> >>>> On Oct 6, 2011, at 2:58 PM, Vincent Massol wrote: >>>> >>>>> Hi devs, >>>>> >>>>> As you know in XE 3.0 we've changed the behavior for resolving local >>> links/attachments when they're included using the {{include}} macro >> (they're >>> now resolved against the included document instead of the including >>> document). >>>>> >>>>> Now there might be some use cases (pretty rare IMO but they exist) >> where >>> you'd want the links to be resolved against the including document. >> Here's a >>> use case: you have a sheet document that references an image called >>> image.png and you want that the including document provides it (like

>>> Abstract in Java! ;)). >>>>> >>>>> So we've brainstormed with Thomas and here's our proposal: >>>>> >>>>> * Introduce a new {{display reference="…"/}} macro. This macro will >>> *execute* the passed reference in its own context (it'll do what >> {{include >>> context="new"…}} was doing before). It'll be located in the new

>>> module. >>>>> * Deprecate the "context" parameter of the {{include}} macro. The >> reason >>> is that calling with context=new is not an include, it's a display. >>>>> * Add a new "resolve" parameter for the {{include}} macro with >> possible >>> values = "current" | "source", with a default value of "source". >>> resolve=source means that the links/attachments are resolved against > the >>> source (ie the document being included). Using resolve=current means > that >>> you want the links/attachments resolved against the including

>>>>> >>>>> Pros: >>>>> * Clearly separate the 2 use cases: display and include >>>>> * Make the include macro simple (a single "resolve" parameter) >>>>> * Use the new display module as it should be and start the direction >> of >>> having displayer macros for displaying all types of entities >>>>> >>>>> Note: In the future we'll also want to deprecate the "document" >>> parameter of the include macro in favor of a more generic "reference" >>> parameter, which will allow the macro to include other types of > entities >>> (such as an object property for ex). >>>>> >>>>> WDYT? >>>>> >>>>> Here's my +1 >>>>> >>>>> Thanks >>>>> -Vincent