ChiliProject is not maintained anymore. Please be advised that there will be no more updates.

We do not recommend that you setup new ChiliProject instances and we urge all existing users to migrate their data to a maintained system, e.g. Redmine. We will provide a migration script later. In the meantime, you can use the instructions by Christian Daehn.

Forums » Develop »

[Proposal] Replace wiki macros with Liquid

Added by Eric Davis at 2011-05-17 04:55 pm

I like the wiki macros but I feel they are too difficult to write and limited in power. You are only able to pass in specific parameters and are unable to use any other data that is present in the view (e.g. the current issue).

As part of some work for a client, I ported the wiki macros to use Liquid templates. I think they will make things a lot easier and would allow normal users to actually "program" their wiki pages themselves. They are also safe in that we only have to expose specific data and not worry about any custom Ruby code running.

Pros

  • Easier to create custom macros (called tags in Liquid)
  • Support for block tags. So you can wrap something in a div with a single tag instead of having to create two macros
  • Chaining: issue.project.name - show the project name
  • Filters: issue.subject | truncatewords 5 - show the first 5 words in the subject
  • Conditionals: if, case, for loops, variables
  • Since it's easy for a user to write some code, then it's wouldn't be that much more to have them share it and even "plugin"-ize their custom code
  • Data is exposed to the views on a model by model basis. So once Project is exposed, it can be used where ever that class is used (e.g. on issue pages and wiki pages).
  • Data associations work as expected once exposed. e.g. issue.assigned_user.projects

Cons

  • There is a syntax conflict since both macros and Liquid use double {
  • Backwards compatibility would be broken but I've got some hacks in place that might smooth over the major macros
  • Plugins with macros will need to be updated. I've already done one of mine and it's not that difficult. redmine_news_macros
  • Will need to revamp the wiki syntax and macro documentation, but I've been wanting to do this for a long time since barely anyone even knows about macros

The current code is on my github branch and is based on an older unstable. Post code-review I'll rebase and merge it. Since this is a breaking change it would need to be in a major release, I'd like to see it in 3.0 if possible.

Thoughts, feedback, code reviews?

More information:


Replies (10)

RE: [Proposal] Replace wiki macros with Liquid - Added by Muntek Singh at 2011-05-18 03:57 am

I agree the wiki macros are difficult to use and relatively unknown. The only times I've ever seen anyone use them is when either myself or you have said "Hey, you can do this in a macro, he's some sample code"

Liquid looks legit, much easier to use, and more useful. I checked out your branch and will have a go at it soon.

RE: [Proposal] Replace wiki macros with Liquid - Added by Jan Wedekind at 2011-05-18 08:43 am

Sounds very interesting. I don't think that most users would use it more than Macros (unless you include some tags/filters in a smart way in the editor), but it gives way more flexibility. Love the fact that I could use contextual information from e.g. the current issue

RE: [Proposal] Replace wiki macros with Liquid - Added by Holger Just at 2011-05-18 08:53 am

The main advantage I see is that it enables power-users to do limited programming inside the wiki and to enable them to create individual structures with which they can work themselves. This can be supported by plugin authors exposing additional functionality to liquid tags and blocks.

And finally, once we utilize cells (e.g. via Apotomo) we have almost endless possibilities to e.g. build dashboards and aggregated views inside the wiki. And all that by the users themselves, without the need to consult developers, IT managers and project folks to have them develop some extensions.

tl;dr: Awesome!

RE: [Proposal] Replace wiki macros with Liquid - Added by Felix Schäfer at 2011-05-18 03:17 pm

Haven't looked at the code yet, but on principle:

Holger Just wrote:

tl;dr: Awesome!

RE: [Proposal] Replace wiki macros with Liquid - Added by Eric Davis at 2011-05-20 06:15 pm

Jan Wedekind wrote:

(unless you include some tags/filters in a smart way in the editor)

I'm thinking that would be useful too...

Holger Just wrote:

And finally, once we utilize cells (e.g. via Apotomo) we have almost endless possibilities to e.g. build dashboards and aggregated views inside the wiki. And all that by the users themselves, without the need to consult developers, IT managers and project folks to have them develop some extensions.

Especially if we later standardize the "widgets" and "blocks" into Liquid objects. Then the My Page could just be a bunch of Liquid and we can embed those widgets in other places (Project overview), etc.

Anyone have any negative feedback? I'd like to add this but I want to make sure it's the right approach since it's a major change.

Eric Davis

RE: [Proposal] Replace wiki macros with Liquid - Added by Felix Schäfer at 2011-05-20 07:05 pm

I'm all for cells and templates, if you say liquid is the best way to get there, I'm all for it.

RE: [Proposal] Replace wiki macros with Liquid - Added by Holger Just at 2011-05-20 07:48 pm

Eric Davis wrote:

Especially if we later standardize the "widgets" and "blocks" into Liquid objects. Then the My Page could just be a bunch of Liquid and we can embed those widgets in other places (Project overview), etc.

Just to be safe here, Liquid is not a requirement for Cells (and vice-versa). I just think they could work great together. Having Liquid in the wiki alone (together with plugins) allows us to create things like wizards which guide users through various steps (e.g our install process with choices like "Which database are you using?", "Packages or RVM?".) With some form builders (which could e.g. point to REST endpoints) you could also define forms to template stuff (e.g. issues, wiki pages, even whole projects). This is something which I loved from the TWiki engine which allows similar features to liquid in its markup.

That said, I think that the My Page should work roughly the same as it does now. We just need more (and more flexible) widgets/cells/blocks/whatever. Liquid tags / blocks are advanced features which are not going to be used by all users but some selected power users. Those however are going to greatly appreciate them.

Anyone have any negative feedback? I'd like to add this but I want to make sure it's the right approach since it's a major change.

I still want to have a more thorough look at the include stuff which I think is a make-or-break feature. Liquid itself has a "Filesytem" concept to load its templates. And I think the access to wiki pages should be done by using such a Filesystem implementation and using the original include tag.

RE: [Proposal] Replace wiki macros with Liquid - Added by Eric Davis at 2011-07-01 09:30 pm

Had another thought about this. We might be able to take all of the custom syntax ([[..]], version#n) and also convert these to liquid. Then we could (re)move a bunch of the parsing code in ApplicationHelper. I don't propose we change the actual syntax on the frontend, just swap out how it works in the code.

Eric Davis

RE: [Proposal] Replace wiki macros with Liquid - Added by Eric Davis at 2011-07-13 05:09 pm

I've just rebased the code onto unstable again (2.0.0). Unless there are any objections, I'd like to get ready to merge it into the official unstable (I'll create an issue and send it through the pull request review process).

Holger: ChiliProject::Liquid::Legacy will map the old include macro to the new include_page liquid tag automatically (as well as any other macros defined in ChiliProject). If you want to see about using the built in include keyword and Liquid Filesystem, I'd be happy to review a patch. I don't think we have to do it right away though.

Eric Davis

(1-10/10)