10 Jan
2012
10 Jan
'12
1:38 p.m.
On Tue, Jan 10, 2012 at 13:30, Vincent Massol <vincent(a)massol.net> 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:
--
Denis Gervalle
SOFTEC sa - CEO
eGuilde sarl - CTO
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
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs