Redmine draw.io plugin
draw.io is free online diagramming tool.
This plugin will allow embedding draw.io diagrams into Redmine wiki pages, issues descriptions and issue notes.
Requirements
- Requires Redmine v2.6+. Tested with Redmine v3.1.4, v3.2.4 and v3.3.2.
Installation
-
install
redmine_drawio
plugin:cd $REDMINE_HOME/plugins git clone https://github.com/mikitex70/redmine_drawio.git
-
restart Redmine to load the new plugin
-
for macro
drawio_attach
make sure to enable Rest API of Redmine -
for macro
drawio_dmsf
make sure to install the DMSF plugin and to enable the module for the project -
if you have troubles with the embedded editor using Internet Explorer, try a more recent version (Internet Explorer 11 should work fine) or, better, use another browser, such as Firefox or Chrome.
Usage
There are three macros that can be used to embed diagrams in wiki pages/issues; use what best fits your needs.
drawio
macro
This macro draws diagrams saved in attachments. This is for compatibility with 0.1.x
versions of the plugin and is now a bit obsolete. To use it:
-
save your draw.io diagram locally and upload it as attachment to a Wiki or issue page.
-
in Wiki (or issue) pages use the
drawio
macro to load the widget, specifying the name of the attachment. For example:{{drawio(activity.xml, options)}}
-
the following macro options are available (default values are shown):
lightbox=false
: enable lightbox usageresize=false
: enable zoom control boxzoom=100
: initial zoom of diagram (percentage of original diagram)fit=true
: fit page width (only ifresize=false
)hilight=#0000ff
: color to hilight hyperlinks
With this macro diagrams are drawn using SVG (or maybe Canvas) so they are interactive: they are navigable,
they respond to over
and click
actions. Hyperlinks can be used to navigate to other items.
This macro render diagrams as SVG, so diagrams are interactive and navigable (link can be used to navigate to other pages).
This macro is now obsolete: you can now use SVG diagrams with the other two macros (draio_attach
and drawio_dmsf
)
but you must import the the diagram in the draw.io editor and then export as SVG with an included copy of the diagram
(see the Export as SVG function of the draw.io editor).
drawio_attach
macro
This macro handles diagrams saved as attachments of issues or wiki pages.
With this macro the attachments are in PNG+XML, a special format consisting in an PNG image of the diagram plus the XML diagram source embeded as a field of the image.
With an.svg
attachment name extension the image format is handled as SVG+XML; like the PNG+XML, this is an SVG image
with an embedded XML source of the diagram (the diagram must be created with the draw.io editor, normal SVG are displayed but cannot be edited).
Usage is very simple:
-
make sure
REST
API are enabled in Redmine global settings; this is need to be able to save diagrams as attachments -
in Wiki or issue pages use the
drawio_attach
macro to specify the name of attachment containing the diagram. For example:{{drawio_attach(myDiagram)}}
If the diagram doesn't exists, a predefined diagram will be used as a placeholder, like this:
Double click on the diagram to start editing with the embedded editor. When you save the the diagram the editor will close, the diagram will be saved in a new attachment and the reference in the wiki/issue page is updated.
The diagram attachments are versioned by suffixing the name with a counter. This is necessary because is not possible to update an existing attachment. Moreover, is not possible to delete attachments throught rest API (seems to be possible from Redmine 3.3.0, but I need to experiment), so the old versions of an attachment must be explicitly (manually) deleted from the Redmine web interface.
-
the following macro options are available (default values are shown):
size=number
: force image width, in pixels (default, show in original size)
In the toolbar editor there is a button with icon that can be used to insert a macro for a new diagram to be saved as attachment (for lazy people).
drawio_dmsf
macro
This macro handles diagrams saved in the DMSF repository as PNG+XML or SVG+XML images. The DMSF module must be enabled for the project to be able to use this macro. Usage is very simple:
-
enable the WebDAV functionality of the DMSF plugin in
Read/Write
mode; this is necessary to be able to save the diagram from the embedded editor. If you prefer you can disable WebDAV after all editings are done. -
in Wiki or issue pages use the
drawio_dmsf
macro to specify the path of the diagram, relative to the DMSF documents of the current project. For example:{{drawio_dmsf(diagrams/myDiagram)}}
The path is optional, but if specified then it must exists in the DMSF managed repository. If the diagram doesn't exists a predefined diagram will be used as a placeholder, like this:
Double click on the diagram to start editing with the embedded editor. When you save the the diagram the editor will close, the diagram will be saved (versioned) in the specified DMSF documents path for the current project, and the diagram will be automatically updated.
-
the following macro options are available (default values are shown):
size=number
: force image width, in pixels (default, show in original size)
Like for the drawio_attach
macro, in the toolbar editor there is a button with icon that can be used to insert a macro for a new diagram to be saved as DMSF document.
Some note on the drawio editor
Someone can be concerned about security in sending own diagrams to the draw.io site.
The diagrams aren't sent to draw.io for editing/rendering, but all the operations are done by the browser using only Javascript and HTML5. The only things loaded externally are the scripts and the editor page, when the diagram editor is opened. The diagram source remains local to browser/redmine site.
Using a personal installation of draw.io
If you like, you can configure this plugin to use your own installation of the draw.io site.
The build of the war
file is a bit problematic because the drawio
macro needs a script dinamically produced by the EmbedServlet2
servlet, which is deployed in the draw.io site but not built from the default sources.
This servlet is excluded from build because of a missing library from Google, maybe because of copyright issues.
If you are planning to use only the drawio_attach
and drawio_dmsf
macros you can use the source as is without troubles, but if you want/need the drawio
macro it is necessary to apply the embed2js.patch
patch (included in this plugin sources).
The build steps are:
git clone https://github.com/jgraph/draw.io.git
cd draw.io
patch -p1 < PATH_TO_DRAWIO_PLUGIN/embed2js.patch
cd etc/build
ant war
cd ../../build
If the build ends without errors, in the build
directory you should find a working version of the war file that you can deploy in your favourite servlet container (like Tomcat); be sure to enable the HTTPS
protocol because is is required.
Then enter your Redmine installation, go to Administration
-> Plugins
-> Redmine Drawio plugin
, click on the Configure
link and then specify your address for the draw.io
site.
Known issues
-
Diagrams are rendered on the browser so they aren't visible inside a PDF export. As workaround you can print the web page as PDF document (easy with Linux, a bit more problematic in Windows), or export the diagram in PNG format and include it as image.
-
There can be a browser limit on the embedded diagram size. For example Opera 11 limits Data URIs size to 65000 characters. If the diagram is too big, use the
draio
macro to render the diagram from an XML source. -
The
drawio_attach
macro doesn't completly work with issue notes: Redmine APIs allow to create new issue notes, but not to change them, so the issue note must be changed manually. As alternative use thedrawio
anddrawio_dmsf
macros, which work fine.
TODO
-
Allow specify diagrams from other other sources:
use a file managed by the DMSF plugin- embed diagram as macro body
- use GoogleDrive, Dropbox and OneDrive as possible diagram sources.
- implement tests
- make diagram images exportable in PDF
Contributing
Any code contribution is well accepted. There are only a few rules that I would like to be respected to easy merging:
- work on
develop
branch and leave themaster
branch untouched. This is importat to keep the released versions stable. - I would prefer comments in the style used by gitchangelog; this will simplify generation of the
CHANGELOG.md
. It isn't fondamental, I can edit comments and insert prefixes, or edit manually theCHANGELOG.md
, but it would be nice if you can help me.