[xwiki-devs] [VOTE] New {{display}} macro and changes to the {{include}} macro
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
+1 (strangely :)) On Thu, Oct 6, 2011 at 2:58 PM, Vincent Massol <[email protected]> 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
On Thu, Oct 6, 2011 at 14:58, Vincent Massol <[email protected]> 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).
I do not remember this change. Does not this depends on the context=new ? If you have a link to the previous discussion, it could help.
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! ;)).
This is not rare, but this could be solved using velocity anyway.
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.
Does not this new macro exists already in 1.x syntax under name '#Topic' ? Was it a mistake to have not kept this one in 2.x ?
* 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.
Since I have really thought it was depending on the context parameter, why use a new parameter for this ?
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).
Is this reference parameter already support, and is this only the deprecation for future ? Why not deprecate right now ?
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
Hi Denis, On Oct 6, 2011, at 3:22 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 14:58, Vincent Massol <[email protected]> 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).
I do not remember this change. Does not this depends on the context=new ?
No. Context = new is only about isolating the execution context. It's not about deciding against what to resolve the links/attachments.
If you have a link to the previous discussion, it could help.
Related Issues are: http://jira.xwiki.org/jira/browse/XWIKI-5902 http://jira.xwiki.org/jira/browse/XWIKI-5807 http://jira.xwiki.org/jira/browse/XWIKI-5808 http://jira.xwiki.org/jira/browse/XWIKI-4802 http://jira.xwiki.org/jira/browse/XWIKI-6196 http://jira.xwiki.org/jira/browse/XWIKI-6874
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! ;)).
This is not rare, but this could be solved using velocity anyway.
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.
Does not this new macro exists already in 1.x syntax under name '#Topic' ? Was it a mistake to have not kept this one in 2.x ?
Probably.
* 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.
Since I have really thought it was depending on the context parameter, why use a new parameter for this ?
See above. They're 2 separate things.
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).
Is this reference parameter already support
No. right now there's only a document parameter supported.
, and is this only the deprecation for future ? Why not deprecate right now ?
We would need to agree about it first and it's not the subject of this mail ;) (let's go step by step!). Thanks -Vincent
WDYT?
Here's my +1
Thanks -Vincent
On Thu, Oct 6, 2011 at 15:38, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Oct 6, 2011, at 3:22 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 14:58, Vincent Massol <[email protected]> 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).
I do not remember this change. Does not this depends on the context=new ?
No. Context = new is only about isolating the execution context. It's not about deciding against what to resolve the links/attachments
If you have a link to the previous discussion, it could help.
Related Issues are: http://jira.xwiki.org/jira/browse/XWIKI-5902 http://jira.xwiki.org/jira/browse/XWIKI-5807 http://jira.xwiki.org/jira/browse/XWIKI-5808 http://jira.xwiki.org/jira/browse/XWIKI-4802 http://jira.xwiki.org/jira/browse/XWIKI-6196 http://jira.xwiki.org/jira/browse/XWIKI-6874
I do not see discussion about how relative links has to be resolved their. I do not feel confortable with the facts that based on context=new, $doc.getURL() obviously change its behavior, and that the equivalent XWiki syntax could follow a different path based on resolved=current|source. This seems to me introducing additional complexity, and therefore potential confusion.
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! ;)).
This is not rare, but this could be solved using velocity anyway.
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.
Does not this new macro exists already in 1.x syntax under name '#Topic' ? Was it a mistake to have not kept this one in 2.x ?
Probably.
* 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.
Since I have really thought it was depending on the context parameter, why use a new parameter for this ?
See above. They're 2 separate things.
Why separating them so much ? What are the use cases ? {{display}} replacing context=new sounds good to me since it clarify a parameter that many do not understand. But, the resolve parameter seems to me putting back confusion. {{display}} implies resolve=source why {{include}} does not implies resolve=current ? If you consider all use cases, there will be situation when you want to access both source and current attachment, no ? So the global resolve parameter seems inappropriate IMO, and having the default above could be simpler. If you really want a specific resolution, it should be on a link by link basis.
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).
Is this reference parameter already support
No. right now there's only a document parameter supported.
, and is this only the deprecation for future ? Why not deprecate right now ?
We would need to agree about it first and it's not the subject of this mail ;) (let's go step by step!).
Not that I want to mix stuffs, but since {{display}} will replace {{include context=new}}, having the first with a reference parameter only and the second with a document parameter only, is somewhat inconsistant. We should consider either supporting document in {{display}} or reference in {{include}} IMO.
Thanks -Vincent
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
On Oct 6, 2011, at 4:21 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 15:38, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Oct 6, 2011, at 3:22 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 14:58, Vincent Massol <[email protected]> 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).
I do not remember this change. Does not this depends on the context=new ?
No. Context = new is only about isolating the execution context. It's not about deciding against what to resolve the links/attachments
If you have a link to the previous discussion, it could help.
Related Issues are: http://jira.xwiki.org/jira/browse/XWIKI-5902 http://jira.xwiki.org/jira/browse/XWIKI-5807 http://jira.xwiki.org/jira/browse/XWIKI-5808 http://jira.xwiki.org/jira/browse/XWIKI-4802 http://jira.xwiki.org/jira/browse/XWIKI-6196 http://jira.xwiki.org/jira/browse/XWIKI-6874
I do not see discussion about how relative links has to be resolved their. I do not feel confortable with the facts that based on context=new, $doc.getURL() obviously change its behavior
It doesn't! The link resolving has nothing to do with context=new or not.
, and that the equivalent XWiki syntax could follow a different path based on resolved=current|source. This seems to me introducing additional complexity, and therefore potential confusion.
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! ;)).
This is not rare, but this could be solved using velocity anyway.
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.
Does not this new macro exists already in 1.x syntax under name '#Topic' ? Was it a mistake to have not kept this one in 2.x ?
Probably.
* 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.
Since I have really thought it was depending on the context parameter, why use a new parameter for this ?
See above. They're 2 separate things.
Why separating them so much ? What are the use cases ? {{display}} replacing context=new sounds good to me since it clarify a parameter that many do not understand. But, the resolve parameter seems to me putting back confusion.
You need a way to express how relative links/attachments are resolved.
{{display}} implies resolve=source
Correct
why {{include}} does not implies resolve=current ?
Because there are 2 valid use cases. If we had resolve=current the default (which is the opposite to what we want IMO) then how would users implement the following use case: * I have Page1 with following content: image:my.png * I include Page1 in Page2: {{include document="Page1"/}} * Result: when I view Page1 the image is broken since it doesn't exist in Page1 Thanks -Vincent
If you consider all use cases, there will be situation when you want to access both source and current attachment, no ? So the global resolve parameter seems inappropriate IMO, and having the default above could be simpler. If you really want a specific resolution, it should be on a link by link basis.
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).
Is this reference parameter already support
No. right now there's only a document parameter supported.
, and is this only the deprecation for future ? Why not deprecate right now ?
We would need to agree about it first and it's not the subject of this mail ;) (let's go step by step!).
Not that I want to mix stuffs, but since {{display}} will replace {{include context=new}}, having the first with a reference parameter only and the second with a document parameter only, is somewhat inconsistant. We should consider either supporting document in {{display}} or reference in {{include}} IMO.
Thanks -Vincent
WDYT?
Here's my +1
Thanks -Vincent
On Thu, Oct 6, 2011 at 16:42, Vincent Massol <[email protected]> wrote:
On Oct 6, 2011, at 4:21 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 15:38, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Oct 6, 2011, at 3:22 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 14:58, Vincent Massol <[email protected]> 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).
I do not remember this change. Does not this depends on the context=new ?
No. Context = new is only about isolating the execution context. It's not about deciding against what to resolve the links/attachments
If you have a link to the previous discussion, it could help.
Related Issues are: http://jira.xwiki.org/jira/browse/XWIKI-5902 http://jira.xwiki.org/jira/browse/XWIKI-5807 http://jira.xwiki.org/jira/browse/XWIKI-5808 http://jira.xwiki.org/jira/browse/XWIKI-4802 http://jira.xwiki.org/jira/browse/XWIKI-6196 http://jira.xwiki.org/jira/browse/XWIKI-6874
I do not see discussion about how relative links has to be resolved their. I do not feel confortable with the facts that based on context=new, $doc.getURL() obviously change its behavior
It doesn't! The link resolving has nothing to do with context=new or not.
, and that the equivalent XWiki syntax could follow a different path based on resolved=current|source. This seems to me introducing additional complexity, and therefore potential confusion.
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! ;)).
This is not rare, but this could be solved using velocity anyway.
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.
Does not this new macro exists already in 1.x syntax under name '#Topic' ? Was it a mistake to have not kept this one in 2.x ?
Probably.
* 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.
Since I have really thought it was depending on the context parameter, why use a new parameter for this ?
See above. They're 2 separate things.
Why separating them so much ? What are the use cases ? {{display}} replacing context=new sounds good to me since it clarify a parameter that many do not understand. But, the resolve parameter seems to me putting back confusion.
You need a way to express how relative links/attachments are resolved.
{{display}} implies resolve=source
Correct
why {{include}} does not implies resolve=current ?
Because there are 2 valid use cases. If we had resolve=current the default (which is the opposite to what we want IMO) then how would users implement the following use case:
Why do you say the opposite to what you want ? If you are using {{include}} and not {{display}}, you are probably doing something like a sheet, and the most common situation would be to use stuffs from the including document and not the include one, so to use the equivalent of resolve=current as a default. What I say basically, is that you may have a default behavior globally, but you will never solve all use case with it, and providing a global parameter to change the default will not either, and is for me a added complexity. Changing the global default should be more at the link level than the global level. Introducing a appropriate link syntax to refer explicitely to either the source document or the current document in the link would probably be the best way to solve all use case. Now regarding the global default, when none of the above syntax is used, I would resolve against current for {{include}} and against source for {{display}}. This seems to me the best default, that would be consistent with the content of the $doc in these two ways to include documents. So I am +1 for two macro with the above default. I am almost -1 to provide one of them a way to divert the way links are solve from the way $doc.getURL() would respond. I am +1 to introduce a syntax in links to explicitly refer to the current or source document (using your definitions). I am almost -1 for using current and source, the seems confusing, but I have not think enough about it to provide alternatives right now.
* I have Page1 with following content: image:my.png * I include Page1 in Page2: {{include document="Page1"/}} * Result: when I view Page1 the image is broken since it doesn't exist in Page1
Thanks -Vincent
If you consider all use cases, there will be situation when you want to access both source and current attachment, no ? So the global resolve parameter seems inappropriate IMO, and having the default above could be simpler. If you really want a specific resolution, it should be on a link by link basis.
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).
Is this reference parameter already support
No. right now there's only a document parameter supported.
, and is this only the deprecation for future ? Why not deprecate right now ?
We would need to agree about it first and it's not the subject of this mail ;) (let's go step by step!).
Not that I want to mix stuffs, but since {{display}} will replace {{include context=new}}, having the first with a reference parameter only and the second with a document parameter only, is somewhat inconsistant. We should consider either supporting document in {{display}} or reference in {{include}} IMO.
Thanks -Vincent
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
On Thu, Oct 6, 2011 at 6:24 PM, Denis Gervalle <[email protected]> wrote:
On Thu, Oct 6, 2011 at 16:42, Vincent Massol <[email protected]> wrote:
On Oct 6, 2011, at 4:21 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 15:38, Vincent Massol <[email protected]> wrote:
Hi Denis,
On Oct 6, 2011, at 3:22 PM, Denis Gervalle wrote:
On Thu, Oct 6, 2011 at 14:58, Vincent Massol <[email protected]> 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).
I do not remember this change. Does not this depends on the context=new ?
No. Context = new is only about isolating the execution context. It's not about deciding against what to resolve the links/attachments
If you have a link to the previous discussion, it could help.
Related Issues are: http://jira.xwiki.org/jira/browse/XWIKI-5902 http://jira.xwiki.org/jira/browse/XWIKI-5807 http://jira.xwiki.org/jira/browse/XWIKI-5808 http://jira.xwiki.org/jira/browse/XWIKI-4802 http://jira.xwiki.org/jira/browse/XWIKI-6196 http://jira.xwiki.org/jira/browse/XWIKI-6874
I do not see discussion about how relative links has to be resolved their. I do not feel confortable with the facts that based on context=new, $doc.getURL() obviously change its behavior
It doesn't! The link resolving has nothing to do with context=new or not.
, and that the equivalent XWiki syntax could follow a different path based on resolved=current|source. This seems to me introducing additional complexity, and therefore potential confusion.
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! ;)).
This is not rare, but this could be solved using velocity anyway.
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.
Does not this new macro exists already in 1.x syntax under name '#Topic' ? Was it a mistake to have not kept this one in 2.x ?
Probably.
* 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.
Since I have really thought it was depending on the context parameter, why use a new parameter for this ?
See above. They're 2 separate things.
Why separating them so much ? What are the use cases ? {{display}} replacing context=new sounds good to me since it clarify a parameter that many do not understand. But, the resolve parameter seems to me putting back confusion.
You need a way to express how relative links/attachments are resolved.
{{display}} implies resolve=source
Correct
why {{include}} does not implies resolve=current ?
Because there are 2 valid use cases. If we had resolve=current the default (which is the opposite to what we want IMO) then how would users implement the following use case:
Why do you say the opposite to what you want ? If you are using {{include}} and not {{display}}, you are probably doing something like a sheet, and the most common situation would be to use stuffs from the including document and not the include one, so to use the equivalent of resolve=current as a default.
What I say basically, is that you may have a default behavior globally, but you will never solve all use case with it, and providing a global parameter to change the default will not either, and is for me a added complexity. Changing the global default should be more at the link level than the global level. Introducing a appropriate link syntax to refer explicitely to either the source document or the current document in the link would probably be the best way to solve all use case.
Now regarding the global default, when none of the above syntax is used, I would resolve against current for {{include}} and against source for {{display}}. This seems to me the best default, that would be consistent with the content of the $doc in these two ways to include documents.
So I am +1 for two macro with the above default. I am almost -1 to provide one of them a way to divert the way links are solve from the way $doc.getURL() would respond. I am +1 to introduce a syntax in links to explicitly refer to the current or source document (using your definitions). I am almost -1 for using current and source, the seems confusing, but I have not think enough about it to provide alternatives right now.
I agree with Denis. If the behavior of the include macro is similar to a PHP/C include in the sense that it copies the content of the included content in the current content (as Vincent said in a previous mail) then it seems natural to me to resolve references from the included document relative to the current document (as if they were written in / copied to the current document). Thanks, Marius
* I have Page1 with following content: image:my.png * I include Page1 in Page2: {{include document="Page1"/}} * Result: when I view Page1 the image is broken since it doesn't exist in Page1
Thanks -Vincent
If you consider all use cases, there will be situation when you want to access both source and current attachment, no ? So the global resolve parameter seems inappropriate IMO, and having the default above could be simpler. If you really want a specific resolution, it should be on a link by link basis.
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).
Is this reference parameter already support
No. right now there's only a document parameter supported.
, and is this only the deprecation for future ? Why not deprecate right now ?
We would need to agree about it first and it's not the subject of this mail ;) (let's go step by step!).
Not that I want to mix stuffs, but since {{display}} will replace {{include context=new}}, having the first with a reference parameter only and the second with a document parameter only, is somewhat inconsistant. We should consider either supporting document in {{display}} or reference in {{include}} IMO.
Thanks -Vincent
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
So display will just be include context="new" if I understand this correctly. include with context not-new only makes sense when it's used for including sheets. Now since as far as I understood, the sheet mechanism is deprecated (I am still to find out in which way), I think we should reevaluate this need in the light of that. On 10/06/2011 02: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! ;)).
can be fixed indeed with velocity. So unless we keep this way of using document sheets, it's not such a big deal. I really need to look at the new sheet mechanism before being able to have an opinion about this. If it's not needed, although it's beautiful, I prefer we won't do it because it involves migration.
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).
only if we've made up our mind and we're sure that this will be the 'future', correct way of displaying object properties in wiki 2.0 syntax. if there's a chance we might use another macro for that, I prefer we don't change things. Thanks, Anca
WDYT?
Here's my +1
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Hi Anca, On Oct 6, 2011, at 3:32 PM, Anca Luca wrote:
So display will just be include context="new" if I understand this correctly.
include with context not-new only makes sense when it's used for including sheets.
It makes sense whenever you want to include a page in the same execution context (ie do an include in the real sense of include, think of include like a PHP include or a C include - ie it copies the content of the included content in the current content).
Now since as far as I understood, the sheet mechanism is deprecated (I am still to find out in which way), I think we should reevaluate this need in the light of that.
The sheet mechanism is definitely not deprecated. The usage of {{include}} is indeed deprecated in favor of sheet objects (to make it short). That doesn't change the need for an include macro. Users will still want to be able to include stuff.
On 10/06/2011 02: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! ;)).
can be fixed indeed with velocity. So unless we keep this way of using document sheets, it's not such a big deal.
I really need to look at the new sheet mechanism before being able to have an opinion about this. If it's not needed, although it's beautiful, I prefer we won't do it because it involves migration.
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).
only if we've made up our mind and we're sure that this will be the 'future', correct way of displaying object properties in wiki 2.0 syntax.
We talked about having displayer macros several times in the past. Yes it's the correct way because the displayer need to return XDOM and not HTML. Otherwise that breaks up the promise that wiki content can be rendered in any syntax (be it PDF, docbook or other). Note that this doesn't preclude having an API (the display module API).
if there's a chance we might use another macro for that, I prefer we don't change things.
Sure, the reason we proposed this is only because we see its alignment with the "future", i.e. the usage of XWiki syntax 2.0 display macros for displaying entities. Do you see another possible direction? (I don't). Thanks -Vincent
Thanks, Anca
WDYT?
Here's my +1
Thanks -Vincent
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-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
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
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 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
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
2012/1/10 Vincent Massol <[email protected]>
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 suggest Thomas since he followed this issue
Ludovic
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
-- Ludovic Dubost Founder and CEO Blog: http://blog.ludovic.org/ XWiki: http://www.xwiki.com Skype: ldubost GTalk: ldubost
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
+1 Thanks, Marius On Tue, Jan 10, 2012 at 2: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
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
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/
6 +1 and no other votes, lets do it. 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
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
-- Thomas Mortagne
+1 Thanks, Marius On Fri, Oct 7, 2011 at 1:13 PM, Vincent Massol <[email protected]> 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-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
* 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
+1 (with the previous note)
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
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior:
** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
* 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already. Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable. Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax. If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ? Denis
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
+1 (with the previous note)
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
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
Hi guys, can we please finish and/or close this vote so that Sergiu can act on it and we can release XE 3.2.1? Thanks in advance, Guillaume On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle <[email protected]> wrote:
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <
[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior:
** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
* 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already.
Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable.
Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax.
If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ?
Denis
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
+1 (with the previous note)
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
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Seems to me that there has been an agreement to revert to the old behavior has soon as possible, but I do not see the link with XWiki 3.2.1 release ? On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge <[email protected]> wrote:
Hi guys,
can we please finish and/or close this vote so that Sergiu can act on it and we can release XE 3.2.1?
Thanks in advance,
Guillaume
On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle <[email protected]> wrote:
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <
[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior:
** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
* 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already.
Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable.
Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax.
If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ?
Denis
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
+1 (with the previous note)
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
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
Oups, sorry I should have read your other mail before replying. Maybe the best would be to split this vote, and propose a vote to revert to the old behavior starting from 3.2.1. Denis On Mon, Jan 9, 2012 at 18:26, Denis Gervalle <[email protected]> wrote:
Seems to me that there has been an agreement to revert to the old behavior has soon as possible, but I do not see the link with XWiki 3.2.1 release ?
On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge <[email protected]>wrote:
Hi guys,
can we please finish and/or close this vote so that Sergiu can act on it and we can release XE 3.2.1?
Thanks in advance,
Guillaume
On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle <[email protected]> wrote:
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <
[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior:
** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
* 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already.
Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable.
Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax.
If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ?
Denis
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
+1 (with the previous note)
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
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO
On Jan 9, 2012, at 6:26 PM, Denis Gervalle wrote:
Seems to me that there has been an agreement to revert to the old behavior has soon as possible,
Where? I don't remember seeing this (since I was on holiday at some point maybe I missed it). Thanks -Vincent
but I do not see the link with XWiki 3.2.1 release ?
On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge <[email protected]> wrote:
Hi guys,
can we please finish and/or close this vote so that Sergiu can act on it and we can release XE 3.2.1?
Thanks in advance,
Guillaume
On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle <[email protected]> wrote:
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <
[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior:
** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
* 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already.
Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable.
Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax.
If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ?
Denis
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
+1 (with the previous note)
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
On Mon, Jan 9, 2012 at 18:37, Vincent Massol <[email protected]> wrote:
On Jan 9, 2012, at 6:26 PM, Denis Gervalle wrote:
Seems to me that there has been an agreement to revert to the old behavior has soon as possible,
Where? I don't remember seeing this (since I was on holiday at some point maybe I missed it).
Our latest talk was just during the 3.3 release, and archived here: http://dev.xwiki.org/xwiki/bin/view/IRC/xwikiArchive20111216 It is around 15 o'clock, and you were there ? ;) Have you forgotten ? have I misunderstood ? Anyway, I am in favor of a vote to revert to the old behavior. This would be simple, and solve the current issue since the change was a mistake anyway and do not remember we have voted for it !
Thanks -Vincent
but I do not see the link with XWiki 3.2.1 release ?
On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge <[email protected]> wrote:
Hi guys,
can we please finish and/or close this vote so that Sergiu can act on it and we can release XE 3.2.1?
Thanks in advance,
Guillaume
On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle <[email protected]> wrote:
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <
[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior:
** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
* 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already.
Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable.
Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax.
If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ?
Denis
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
+1 (with the previous note)
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
+1 Envoyé de mon iPhone Le 9 janv. 2012 à 20:29, Denis Gervalle <[email protected]> a écrit :
On Mon, Jan 9, 2012 at 18:37, Vincent Massol <[email protected]> wrote:
On Jan 9, 2012, at 6:26 PM, Denis Gervalle wrote:
Seems to me that there has been an agreement to revert to the old behavior has soon as possible,
Where? I don't remember seeing this (since I was on holiday at some point maybe I missed it).
Our latest talk was just during the 3.3 release, and archived here:
http://dev.xwiki.org/xwiki/bin/view/IRC/xwikiArchive20111216
It is around 15 o'clock, and you were there ? ;) Have you forgotten ? have I misunderstood ?
Anyway, I am in favor of a vote to revert to the old behavior. This would be simple, and solve the current issue since the change was a mistake anyway and do not remember we have voted for it !
Thanks -Vincent
but I do not see the link with XWiki 3.2.1 release ?
On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge <[email protected]> wrote:
Hi guys,
can we please finish and/or close this vote so that Sergiu can act on it and we can release XE 3.2.1?
Thanks in advance,
Guillaume
On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle <[email protected]> wrote:
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <
[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior: > ** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) > ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
> * 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already.
Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable.
Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax.
If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ?
Denis
> 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
+1 (with the previous note)
> > 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
On Jan 9, 2012, at 7:29 PM, Denis Gervalle wrote:
On Mon, Jan 9, 2012 at 18:37, Vincent Massol <[email protected]> wrote:
On Jan 9, 2012, at 6:26 PM, Denis Gervalle wrote:
Seems to me that there has been an agreement to revert to the old behavior has soon as possible,
Where? I don't remember seeing this (since I was on holiday at some point maybe I missed it).
Our latest talk was just during the 3.3 release, and archived here:
http://dev.xwiki.org/xwiki/bin/view/IRC/xwikiArchive20111216
It is around 15 o'clock, and you were there ? ;) Have you forgotten ? have I misunderstood ?
Anyway, I am in favor of a vote to revert to the old behavior. This would be simple, and solve the current issue since the change was a mistake anyway and do not remember we have voted for it !
Well unless I don't understand something I clearly don't see it as a mistake. I need to re-read all the thread to try to understand the issue and why you think it was a mistake (I've planned to talk about it with Thomas too tomorrow). The only potential mistake I can see ATM is not to have set a compatibility flag in the configuration to make it easy for people who wish to keep the old behavior. For me the mistake was to have the old behavior. But again I need to refresh my memory by re-reading the whole thread and talking to Thomas tomorrow. Give me half a day and it's very possible I'll agree with you all :) Thanks -Vincent
Thanks -Vincent
but I do not see the link with XWiki 3.2.1 release ?
On Mon, Jan 9, 2012 at 17:59, Guillaume Lerouge <[email protected]> wrote:
Hi guys,
can we please finish and/or close this vote so that Sergiu can act on it and we can release XE 3.2.1?
Thanks in advance,
Guillaume
On Mon, Oct 10, 2011 at 10:13 AM, Denis Gervalle <[email protected]> wrote:
On Mon, Oct 10, 2011 at 09:31, Thomas Mortagne <
[email protected]>wrote:
On Fri, Oct 7, 2011 at 12:13 PM, Vincent Massol <[email protected]> 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)
+1, this is simpler and clearer
* Have a compatibility mode for the {{include}} macro with the following behavior: > ** {{include}} in non-compatiiblity mode is equivalent to context=current and resolve=current (ie links resolve on the including document) > ** {{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
-0, this is for me useless, since I doubt many understand that and have notice this change in 3.x. I was unaware myself of this change, and I do not remember any discussion about it in the past. If you have a ML thread about the rational behind this mistake, I am still interested, but I it could have been introduce without notice, it could be removed as well. At least, this should not be in compatibility mode by default.
So you propose to get back to previous behavior by default, right ? Given the fact that it has been changed very recently maybe we should have the property false right away and say it was a mistake ?
I agree.
> * 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".
+1
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.
I am still -1 on this last point. First, it is precisely because it is very difficult to understand the differences between the context and the resolve parameter that I am against it. I repeat myself, but not having the same behavior between $doc.getURL() and [[ ]] is for me not acceptable, since the included document author could no more count on the equality of these to resolution methods. If I have been aware of that change in 3.x I would have veto it already.
Moreover, if the writer of the included document is the not the writer of the including document, he would be better if he could stay in control of how links/image are accessed, protecting the way its own document works, and not leaving this to the including document author. This is why I have proposed to move the resolve parameter on individual links, which is more flexible and understandable.
Currently, AFAIK, during an {{include}} (without context=new), using velocity, the included document do not have an easy access to itself (without knowing its own name), but you want this possibility for links ? and you want it globally ? This seems to me curious that something difficult to do by code would be easy by syntax.
If you still want to convince me, please explain why you need $doc and relative links to diverge, especially without the included document author to be aware of this. What cannot you do with {{display}} that would be possible by {{include resolve=source}}; and that would not be better served by giving the control to the included document author ?
Denis
> 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
+1 (with the previous note)
> > 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
participants (8)
-
Anca Luca -
Denis Gervalle -
Guillaume Lerouge -
Ludovic Dubost -
Marius Dumitru Florea -
Sergiu Dumitriu -
Thomas Mortagne -
Vincent Massol