On Tue, Jan 10, 2012 at 1:30 PM, 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
>
> 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
+1
>
> We need to find a volunteer to implement this ASAP. If anyone has some time
> for this please step forward :)
I can take care of this. I don't have much time in theory but I think
this has a higher priority than my current work.
>
> 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
--
Thomas Mortagne
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
