Edgewall Software
Modify

Opened 13 years ago

Closed 13 years ago

#4139 closed defect (fixed)

Formatter argument for macros

Reported by: jpereira@… Owned by: Christian Boos
Priority: normal Milestone: 0.11
Component: wiki system Version: 0.10.1
Severity: normal Keywords: macros
Cc: Branch:
Release Notes:
API Changes:

Description

Hi,

We've ran into a problem, where inside a macro provider we must know what kind of formatter has been used. More specifically, this occured when using the WikiTemplate plugin, it has to return unformatted wiki text for the OutlineFormatter, or formatted text for a Formatter.

In Trac's source, I found TODO comments, stating that you intend to pass the formatter to the macro renderer. One could easily pass an extra argument to the WikiProcessor constructor, but it seems like from there to the macro renderer, you'd have to break the API by adding an extra argument (or alternatively, adding an extra property to one of the objects passed into the function, like req).

We really don't want to break compatibility with your code, so what's your plan on this situation? Would there be any interest in an extra pair of hands working on this?

Thanks in advance,

  • Jorge Pereira

Attachments (0)

Change History (6)

comment:1 by Christian Boos, 13 years ago

Keywords: macros added
Milestone: 0.11
Owner: changed from Jonas Borgström to Christian Boos
Summary: Formatter option for macrosFormatter argument for macros

Well, right now the macros aren't even called in other formatters (only in Formatter).

But I agree that once the formatter is given to the macros as an argument, this can change. The API need to change, no question about that, so suggestions and requirements are welcomed at this point.

in reply to:  1 ; comment:2 by jrp@…, 13 years ago

Hi,

Sorry for the delay in replying, but I'm not getting a warning email from the ticket system. We did have to hack so that macros would get called for the OutlineFormatter. Some thoughts about this:

  • Macros that generate content, like WikiTemplate, really need to be called for other formatters. In our case, we needed it so we could break down the main Wiki page in multiple Included pages.
  • Would it make more sense to pass the current formatter object as part of the enviroment? That'd mean no API change, but it doesn't look as "clean".
  • Given the formatter object or its .flavor, the macro itself should know how to behave.
  • It could be interesting that a macro would indicate to the processor that it'd be returning wiki text, and not formatted html. In the case of included files, that's quite important.

Thanks for listenning,

in reply to:  2 ; comment:3 by Christian Boos, 13 years ago

With 0.11, macros have now access to the formatter instead of the request, as their first argument. That was part of the WikiContext refactoring, checked in in r4452. The request itself can still be obtained from the formatter, of course.

Replying to jrp@eufinity.com:

We did have to hack so that macros would get called for the OutlineFormatter.

Some thoughts about this:

  • Macros that generate content, like WikiTemplate, really need to be called for other formatters. In our case, we needed it so we could break down the main Wiki page in multiple Included pages.

In 0.11, the WikiTemplate should render the wiki content relative to the parent (i.e. the current) content, I guess. So relative links within the template are relative to the page embedding the template, not to the template itself…

  • Would it make more sense to pass the current formatter object as part of the enviroment? That'd mean no API change, but it doesn't look as "clean".

No, that doesn't work. Environment is "global", whereas the formatter is tied to some specific transaction (= thread).

An API change was the cleanest thing to do, in the long run (remember, this is still pre-1.0, so we don't need to add fancy methods like render_macro2 in order to preserve backward compatibility ;) ).

  • Given the formatter object or its .flavor, the macro itself should know how to behave.

Well, the .flavor is one thing. There will be probably a output mime-type as well in the near future, so that, e.g. a LaTeX macro can simply pass its content through when rendering the Wiki page to LaTeX…

  • It could be interesting that a macro would indicate to the processor that it'd be returning wiki text, and not formatted html. In the case of included files, that's quite important.

Yes, that's an approach worth considering.

Altough the Formatter argument for macros was done in r4452, I'm not yet closing the ticket, as the above shows that there are remaining open points here.

Also, see related #4431 and #3089.

comment:4 by Christopher Lenz, 13 years ago

See also #4568.

in reply to:  3 ; comment:5 by Christopher Lenz, 13 years ago

Replying to cboos:

An API change was the cleanest thing to do, in the long run (remember, this is still pre-1.0, so we don't need to add fancy methods like render_macro2 in order to preserve backward compatibility ;) ).

I tend to disagree here. While 0.11 is breaking backwards compatibility left and right already, we shouldn't use the “not 1.0 yet” argument for cases where providing backwards compatibility would not be hard to do.

In this case, I think it would've been better to add a second extension point interface or method, although I'm not yet sure about the naming (render_macro2 is admittedly ugly.)

in reply to:  5 comment:6 by Christian Boos, 13 years ago

Resolution: fixed
Status: newclosed

Ok, API reverted in r4621. render_macro keeps using a req as before (0.9 and 0.10) and there's now a new method expand_macro which takes the formatter as its first parameter.

render_macro itself is now deprecated and will be removed in a later release (probably 0.12).

I'll carry on with the few remaining details mentioned in comment:3 in #4431. The major point addressed by this ticket has been implemented.

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The owner will remain Christian Boos.
The resolution will be deleted. Next status will be 'reopened'.
to as closed The owner will be changed from Christian Boos to the specified user.

Add Comment


E-mail address and name can be saved in the Preferences .
 
Note: See TracTickets for help on using tickets.