Skip to content

Redmine Wiki HTML Utility

by arlo on August 3rd, 2011  Tip

At work we use a project management system called Redmine. So far I have been very pleased with the ease of use, Git repository integration, issue tracking and wikis for all your projects.

Redmine offers a lot more than just Git integration, issue tracking and wikis. It is also open source! Visit the website for more information.

In Action

The Conflict

I had just finished adding some new styles to our company style.ui.css file. These new classes are to be used to create certain Web UI Components with ease. I started to document the use of these new UI components for my coworkers and took advantage of the textile formatting available in Redmine wikis, especially the syntax highlighting.

At the end, there was only one thing I REALLY wanted for this documentation, a demo (HTML/CSS). Now, I know I could have made a separate HTML file, host it on our server and then link to it from the wiki. That approach just seemed to lame and I really wanted this “demo” habit to stick with my fellow coworkers, so I needed something easy to use. Not being to familiar with wiki textiles I quickly abandoned my googling and started to create my own wiki macros. Here is what I came up with

The Plugin

The plugin can be found or cloned from my Github Repo. Let’s continue with how you would use the plugin.

Plugin Installation

Go to your Redmine plugin directory, for the bitnami Redmine VM it would be: 

~$ cd /opt/bitnami/apps/redmine/vendors/plugins/

Then use git to down load the plugin into a folder. 

~$ sudo git clone git://github.com/mexitek/redmine_wiki_html_util.git

Now, simply reset Redmine and you are done!

~$ sudo /etc/init.d/bitnami restart

Exposed Macros

Wiki HTML Utility exposes several macros to your Redmine Wikis:

  • css_url() : allows you to “inject” an external stylesheet into the current wiki page
  • js_url() : allows you to “inject” an external javascript file into the current wiki page
  • html() : allows you to “inject” RAW HTML into the Wiki page

HTML()

Embeds RAW HTML. 

{{html(
<ul>
   <li>option 1</li>
   <li>option 2</li>
   <li>option 3</li>
</ul>
)}}

If you use HTML like the example above, the wiki will convert all newlines with <br>. If you know of a way to access the unfiltered text let me know.

CSS_URL()

This injects an external CSS file into the DOM (current wiki page). Notice the single quotes around the URL, this is very important.

{{css_url('http://www.domain.com/css/styles.ui.css')}}

JS_URL()

This injects an external JS file into the DOM (current wiki page). Notice the single quotes around the URL, this is very important.

{{js_url('http://www.domain.com/js/widget.js')}}

Conclusion

At the end of the day, you can inject JQuery and your CSS file into a wiki page and show off your awesome widgets! Live demos on a freaking wiki page! The possibilities are endless, kinda.

See the code on Github.com

From → Redmine, Ruby

  • Steven

    Thanks for the plugin. I’m using it not quite as intended but rather as a wiki extension where I can add color and other formatting to my wiki pages.

  • http://www.arlocarreon.com Arlo Carreon

    That’s awesome! Glad it helped.

  • Jjreina

    Thanks soo much for the plugin. I’m tryning to do a hellow word whith JS but not work. I have my code JS in http://localhost:8080/redmine/javascripts/helloWorld.js, the code is:

    document.write(‘Hello
    World    ‘);

    and on redmine wiki edit as:

    {{js_url(‘http://localhost:8080/redmine/javascripts/helloWorld.js’)}} , but wiki no show Hello World.

    Please any suggestions.thanks very much.

  • http://www.arlocarreon.com Arlo Carreon

    When the plugin loads a JS file, it puts it into the <head> </head> section of the DOM.  So a document.write() will not show in your wiki page.  If you want to test, have only one line in your javascript file: alert(‘hello world’);

    If that works, then you know that the JS_URL() macro works.

  • Jjreina

     Thanks, now work fine.

    Thanks you very much.

  • William Rosa

    Audaces Team resolved the problem macro html, where it created before html code.
     
    Redmine::WikiFormatting::Macros.register do
        desc “Embed raw html”
        macro :html do |obj, args|
            #I also need to get rid of newlines here. How?
            result = CGI::unescapeHTML(args.join.gsub(”,”"))
            result
        end   
      end

  • William Rosa

    Audaces Team resolved the problem macro html, where it created
    before html code.
    ***changes the “*” to ‘ ‘ (single asps)  
     Redmine::WikiFormatting::Macros.register do
        desc “Embed raw html”
        macro :html do |obj, args|
            #I also need to get rid of newlines here. How?
            result = CGI::unescapeHTML(args.join.gsub(**,”"))
            result
        end   
      end

  • William Rosa

     *”*

  • Javi

    Thank you very much.
    It is very useful and very easy to install.

  • http://www.arlocarreon.com Arlo Carreon

    Awesome! would be great if we can get this as a pull request into the git repo.

  • http://www.arlocarreon.com Arlo Carreon

    Glad it helped!

  • Franco

    I am trying to generate a config generator using jquery on a wiki. I have already done so on a regular html + JS(JQuery). But when I import it, using the plugin, the JS portion does not work.

    Could you provide a wiki JQ example?

    Thanks in advance. Great Plugin!

  • Franco

    Already figured it out. Thanks for the plugin!

  • http://twitter.com/framandaniarivo Frédéric RAMANDA.

    Hi,
    Is it compatible with Redmine 2.x ?

  • arlo

    Do you have redmine available on a public server? I would not mind logging in, editing a wiki page and leaving the example on your installation. You can email me log in credentials. arlo.carreon@gmail.com

  • Charles

    Just out of curiosity I have been trying to use the wiki formatting inside the HTML is that possible? I can not seem to get it working for me so I was just wondering.

  • Franco

    Could you post the fix propperly? Just the line “result=CGI::……” It seems that the webpage is interpretating whats inside the ().

  • DrP

    I can’t seem to be able to use this on the welcome page or other little helper documents. I can only get this to work on the wiki pages of projects. Am I missing something?

  • Kartik

    Hi,

    I’ve been using this plugin for a while now, and just recently upgraded to the 2.1 series. Looks like the plugin isn’t working anymore. Any ideas why this is?

    Thanks in advance and thanks for the great plugin!

    Cheers,

    Kartik

  • Franco

    Hi, I have been trying to make it work with redmine (bitnami) 1.4 and 2.0, without luck.
    It seems as it does not show any of the code i put inside the {{html()}} macro.

    Could you point out how to correct the plugin for these versions?

    Great plugin and great suggestion from William Rosa.

  • Franco

    Sorry. It works on 1.4 (forgot to lock the wiki). Still no luck with 2.0.

  • Franco

    Arlo, is there any way I can contact you in order to send some changes I have made to the code in order to work with redmine 2.x?

    Thanks!!

  • Adam

    Hi Franco. Would it be possible that you could share your update? I upgraded redmine to latest redmine 2.1.2 and this plugin is nor working anymore.

  • Adam

    I figured it out. In order to make it work with Redmine 2.1 edit the init.rb file in following way:
    1. add html_safe when returning results
    return result.html_safe

    2. you may also want to comment out result = result.gsub(/]*>/, “”)

    3. Of course restart redmine

  • Franco

    Exactly. I have already given this to Arlo. Works great!!

  • Giovanni Juanes

    Does this also work for 2.2.2? I have tried your suggestions, but it does nothing. Anybody seeing the same issue?

  • http://www.arlocarreon.com Arlo Carreon

    I don’t know. If I ever get some time I will take a look at it.

  • Chuvy

    Hello. Does it work with 2.2.3?

    Thanks.

  • Chuvy

    Working for me. Redmine 2.2.3.
    My changes:
    1. macro :html do |obj, args, text|
    2. result = “#{text}”
    Result:

    {{html

    option 1

    option 2

    option 3

    }}

    And how wrote Adam:
    Added to all – return result.html_safe

  • DevMan

    Could you elaborate on what you’re second change was? Did you replace all assignments of result to “result = “#{text}”" ?