On Tue, Jan 10, 2012 at 13:30, Vincent Massol <[email protected]> wrote:
> Hi again, > > After discovering http://jira.xwiki.org/browse/XWIKI-7301 and after > discussing this more with Ludovic, Denis and Thomas, here's what we propose: > > For 3.2.1 and 3.3.1: > - revert behavior of include as it was before 3.0 (i.e. 1 year ago) i.e. > have include with context = current be the default and no relative > resolution of links/images > - Big warning in release notes about the change and explain that in 3.4+ > there's a new "display" macro for the context=new use case (see below) > > For 3.4: > - revert behavior of include as it was before 3.0 (i.e. 1 year ago) i.e. > have include with context = current be the default and no relative > resolution of links/images > - new display macro (equivalent to include context = new) > - Big warning in release notes about the change > - deprecate the "context" param in include macro > - deprecate the "document" param in include macro and add "reference" + > "type" (with default type being documents) > - also use "reference" and "type" params in new "display" macro > > Future: > - possibly add a resolve=current|source parameter in the include macro in > the future if we find a valid use case for it > - possibly add a parameter on the link syntax to allow individual link to be always resolved relative even when used in an inclusion. > > The idea is to release 3.2.1, 3.3.1 ASAP so that user move back to the old > behavior ASAP. > > Here's my +1 > Big +1, of course :) > We need to find a volunteer to implement this ASAP. If anyone has some > time for this please step forward :) > > Thanks > -Vincent > > PS: We discussed the idea of a backward compatibility param but we decided > against since it would think complex and not help that much in the end. > > On Oct 7, 2011, at 2:16 PM, Vincent Massol wrote: > > > > > On Oct 7, 2011, at 12:13 PM, Vincent Massol 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) > >> * Have a compatibility mode for the {{include}} macro with the > following behavior: > >> ** {{include}} in non-compatibility mode is equivalent to > context=current and resolve=current (ie links resolve on the including > document) > > > > 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. > > > > Thanks > > -Vincent > > > >> ** {{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 > >> * 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". > >> > >> 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 > >> > >> 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 > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > -- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
