New subject: [xwiki-devs] [xwiki-users] Panels backward compatibility

14 Jun 2012

On 06/13/2012 06:09 PM, Sergiu Dumitriu wrote:
...
  On 06/13/2012 09:17 AM, Vincent Massol wrote:

 On Jun 13, 2012, at 2:52 PM, Anca Luca wrote:

> On 06/13/2012 02:44 PM, Vincent Massol wrote:
>> On Jun 13, 2012, at 2:39 PM, Anca Luca wrote:
>>
>>> On 06/13/2012 01:52 PM, Raluca Stavro wrote:
>>>> Hi,
>>>>
>>>> On Wed, Jun 13, 2012 at 2:15 PM, Vincent 
>>>> Massol&lt;vincent(a)massol.net&gt;   wrote:
>>>>
>>>>> On Jun 13, 2012, at 12:44 PM, Raluca Stavro wrote:
>>>>>
>>>>>> I'm resending this mail by using the right subject pattern.
>>>>>>
>>>>>> Hello,
>>>>>>
>>>>>> I am trying to upgrade an old XEM to 3.5.1.
>>>>>> In this XEM there are some custom panels which have been 
>>>>>> converted to 2.0
>>>>>> syntax and contain code like this:
>>>>>>
>>>>>> {{velocity}}
>>>>>>   {{html}}
>>>>>>     #panelheader("...")
>>>>>>     ...
>>>>>>     #panelfooter()
>>>>>>   {{/html}}
>>>>>> {{/velocity}} 
 Do the panels really need the {{html}} wrapper?
 If no, then you must remove it.
 If yes, then you should consider rewriting them using wiki syntax 
 only, then remove the {{html}} wrapper.
 If you can't do that, then just move the wrapper inside the 
 panelheader/footer.

 You can do that automatically with a script.

 >>>>>> Because since 2.7.2 panel
macros were converted to 2.0 syntax, 
>>>>>> because
>>>>>> panel macros from inside macros.vm were modified by calling 
>>>>>> {{html}} wiki
>>>>>> macro and because we can't use nested {{html}} macros without

>>>>>> wiki="true"
>>>>>> parameter, I don't know how to fix this issue besides
modifying 
>>>>>> panel
>>>>> code. 
 I don't understand this. Are you saying that in macros.vm #panelheader 
 uses {{html}}? That's not true, the panelheader/footer macros only use 
 wiki syntax, not {{html}}. The problem isn't that nested {{html}} 
 macros don't work, but that wiki syntax doesn't work in {{html}} 
 without wiki="true".

 >>>>>> This XEM has more than 70
wikis and this I can't just modify 
>>>>>> all custom
>>>>>> (converted to 2.0 syntax) panels manually.
>>>>>> Is there a nice solution to this problem ?
>>>>> Idea 1:
>>>>> ======
>>>>>
>>>>> Add a new #panelheaderold macro in macros.vm and replace all 
>>>>> calls of
>>>>> #panelheader to #panelheaderold in your panels (easy to do with 
>>>>> a XWQL
>>>>> query and 3 lines of scripts).
>>>>>
>>>>> Slowy migrate panels to new syntax.
>>>>>
>>>>> Note:
>>>>> =====
>>>>>
>>>>> Actually in the future we need to add a new {{panel}} macro, 
>>>>> something
>>>>> like:
>>>>>
>>>>> {{panel style=".." title="…"}}
>>>>> … content here …
>>>>> {{/panel}}
>>>>>
>>>>> Idea 2:
>>>>> ======
>>>>>
>>>>> Create a custom Panel wiki macro (give it a name other than 
>>>>> "panel"!),
>>>>> search for:
>>>>> {{velocity}}{{html}}#panelheader….#panelfooter{{/html}}{{/velocity}}

>>>>> (use
>>>>> a regex)
>>>>>
>>>>> Replace with your panel macro.
>>>>>
>>>>>> Should I open an issue on Jira ?
>>>>> Nope
>>> So this means that none of the macros in macros.vm are API?
>>> Which means that there is no API to make a panel header consistent 
>>> with the panel headers of the default panels?
>> Good point. Macros in macros.vm are supposed to be APIs and it 
>> means we broke the backward compatibility at some point in the past 
>> (2.7 as suggested by Raluca). 
 The macros still work for both xwiki/1.0 and xwiki/2.x panels. What 
 doesn't work is putting the whole panel content inside a {{html}} 
 block, without any wiki parsing.

 The problem was that there was a misunderstanding of the macros 
 behavior. The macros were supposed to work well in wiki syntax. 
 Initially, that meant the only xwiki syntax, which did mix HTML with 
 the rest of the wiki and velocity syntax. When new wiki syntaxes were 
 introduced and the macros were updated, the behavior remained the 
 same: the #panelheader/footer macros work well in both xwiki/1.0 and 
 xwiki/2.x syntaxes. But pure HTML isn't really a wiki syntax. The fact 
 that for a few releases the macros worked in pure HTML embedded in an 
 xwiki/2.0 document, but not directly in a xwiki/2.0 document, was a 
 bug, not a contract. 
 Unfortunately some developers did rely on this bug. 
I wouldn't call it a bug, because if we do so, then we can argue that 
it's a bug that has been there for at least one major cycle, and that 
macros.vm is still not stable according to 
http://jira.xwiki.org/browse/XWIKI-6062 so we might still have "bugs" 
about it (and that is for about 2.5 major cycles, which is a bit too 
much from my point of view).

What I would say about this is that apparently we don't know / have a 
convention about how should the macros in macros.vm be used: with syntax 
interpreted or not, in an html macro or not. This is where the confusion 
comes from: while the old panelheader macro _needed_ html macro 
(potentially with syntax activated), the current one needs _only wiki 
syntax_ (potentially in an html macro). There is a context which 
satisfies both (html macro with wiki syntax activated) but it was not 
documented anywhere, I'm not even sure it is _the rule_ for macros in 
macros.vm, so people used "what it worked", in this case a plain simple 
html macro whose wiki parameter defaults to false.

The wysiwyg macros in macros.vm, for example, I would say they need to 
be called in a html macro with syntax switched off, but it's just a 
guess, looking at the code.

I think we need to:
1/ make a decision about what is API from macros.vm
2/ make a decision about what _was_ API from macros.vm and keep it 
working as it used to
3/ document how an API macro should be used, either by having a rule or 
by at least writing in its own documentation in macros.vm what context 
it expects (note that even if we document it, if we cannot enforce it, 
chances are that people will use "what it works"...)

To me, all these above are unclear and until they are, from how it feels 
to me, it's very hard to call something a bug or a backwards 
compatibility break.

Thanks,
Anca

...

   3.2 M1 
 https://github.com/xwiki/xwiki-platform/commit/2e4b54267b9bf4048c14fdf14b6a… 
 http://jira.xwiki.org/browse/XWIKI-6504
 It's interesting that the API Breakage section of the 3.2M1 release 
 notes says only "[TODO]" 

http://www.xwiki.org/xwiki/bin/view/ReleaseNotes/ReleaseNotesXWikiEnterpris…

 ... :) 
 bad bad…

 Who was the RM? :)

 -Vincent

> Anca
>
>>
>> We should probably have introduced new macros instead when we 
>> introduced the conversion to 2.0 syntax.
>>
>> Now since this is very old we need to decide what we want to do at 
>> this point.
>>
>> Thanks
>> -Vincent
>>
>>> Thanks,
>>> Anca
>>>
>>>> So there is no other way to fix this issue but by modifying the 
>>>> code inside
>>>> panels.
>>>> Thank you, Vincent.
>>>>
>>>> Raluca.
>>>>
>>>>
>>>>> Thanks
>>>>> -Vincent 

Re: [xwiki-devs] [xwiki-users] Panels backward compatibility