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