On 01/10/2012 07:30 AM, Vincent Massol 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)
+1
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
I'm not sure {{display}} is the best name for this macro. For me, on a
fresh mind {{include}} means {{include context=new}}. and {{display}} is
something graphical. The best way to avoid any confusion is to make
things explicit, and use something like includeContent and
includeDisplayer for the macro names.
Anyway, +1 for the changes.
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
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
--
Sergiu Dumitriu
http://purl.org/net/sergiu/
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
