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

On Mon, Jan 9, 2012 at 18:37, Vincent Massol <vincent(a)massol.net> wrote: Our latest talk was just during the 3.3 release, and archived here: http://dev.xwiki.org/xwiki/bin/view/IRC/xwikiArchive20111216 It is around 15 o'clock, and you were there ? ;) Have you forgotten ? have I misunderstood ? Anyway, I am in favor of a vote to revert to the old behavior. This would be simple, and solve the current issue since the change was a mistake anyway and do not remember we have voted for it !

>> but I do not see the link with XWiki 3.2.1 release ? >> >> >> On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge &lt;guillaume(a)xwiki.com&gt; > wrote: >> >>> 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 > do >>>> 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 > my >>>>> 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 > same >>>> behavior between $doc.getURL() and [[ ]] is for me not acceptable, > since >>>> the >>>> included document author could no more count on the equality of these > to >>>> 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 > of >>>> the including document, he would be better if he could stay in control > of >>>> how links/image are accessed, protecting the way its own document > works, >>>> 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 > more >>>> 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 > links ? >>>> 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 > an >>>>> 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 > display >>>>> 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 > document. >>>>>>> >>>>>>> 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