SVG Out Confluence plugin

Scope

This Wiki page is the basic user documentation for the SVG out Confluence plugin. It contains (hopefully) all necessary detail to use the plugin effectively.

Remark: this documentation only covers the most recent version of the plugin.

What is it?

Please read the security considerations first!

The SVG out Confluence plugin closes a gap you might have discovered when including SVGs in your Confluence pages. Confluence is able to show and scale SVGs but it is not possible to use the links which might be included in the SVG. This plugin renders the SVG such that the links are still working. Furthermore it allows you to replace the existing links in the SVG by Confluence links which are automatically updated when the content moves.

In addition the plugin offers the following functionality:

scale the SVG (independent in x- any y-direction)
cut out a region to show
align the image (left, center, right)
show/replace tool tips (only in case the link replacement functionality is used)
pan and zoom (including touch devices)
all the above functions for macros delivering SVGs such as Graphviz or PlantUML (via macro SVG out body injected)
export to PDF and Word (via transforming the SVG to a PNG using the Batik library)

Credits: thank you to the tensixtwo team for helping me getting Batik into my plugin.

Look and feel

The screenshot below shows how a SVG generated by the webpage draw.io renders in Confluence with working links.

How to get it?

There are two ways of getting the plugin:

Atlassian Marketplace
via the download section of this repository (you want to download the jar)

Privacy policy

Please refer to the our privacy policy.

Compatibility

Please refer to the versions listed on the Marketplace.

Security considerations

SECURITY WARNING: SVGs can be subject to cross-site-scripting (XSS). This means that an SVG can execute Javascript for example. Please select carefully which SVGs you are going to show!

The plug-in contains a basic security check which should minimize the risk of cross-site-scripting. However this check can't detect all possible threats in an SVG. The technical details of the security check are described here.

Configuration

Confluence administrators can configure the security settings of the plugin by navigating to Confluence administration / Manage add-ons / SVG Out / Configure. You can configure the following:

You can enable or disable the cross-site-scripting security check. Keep in mind that disabling the security check means that an SVG can basically do everything - e.g. executing javascript.
You may specify ONE additional group which is allowed to white-list SVGs additionally to admins.
In case the security check detects that an SVG is suspicious it will not be displayed. As an admin or a member of the group specified before you may white-list the SVGs by clicking the link shown when the security check is negative. In case you want all SVGs to undergo a security check you can enter forceWhiteListingOfAllSVGs to the white list. This will enforce that all SVGs are white listed regardless of the outcome of the security check.
In case you frequently bump into the security check because your SVGs contains regular expressions the security check is looking for you may white list those false negative expressions (after having checked them).
SVG Out internally uses Apache Batik to convert SVGs to PNGs prior to export. As Batik has some drawbacks you may use an alternative PhantomJS based conversion. For details please follow: using PhantomJS as alternative to the embedded Batik transcoder for export

White-listing an SVG

The following message is shown instead of the image in case the security check detected something:

svg-out: Sorry, the security check was negative! You may ask an administrator or another member of the appointed group to white-list your SVG.

An admin or any member of the specified group can now click on the link to white-list the SVG.

Macro "SVG Out"

Purpose

This macro is used to render SVGs provided as an attachment.

Parameters

The macro has to the following parameters:

Page: Confluence page where the SVG is attached to - in case it is empty the current page is used
SVG File: The filename of the SVG file to be rendered. The dropdown list shows all files on the specified page which end with svg or svgz.
Width in percent of the original size (%), absolute width in px (px) or percent of the available width (%%) (examples: 100%, 300px, 80%%). Tips: you can only specify the width - the height is adopted accordingly. In case you specify %% the image will automatically scale to the given percentage of the available width - e.g. it will shrink when the browser window shrinks.
Height in percent of the original size or absolute height in px (examples: 100%, 300px). Tip: you can only specify the height - the width is adopted accordingly.
Maximum with in px (example: 600px). This parameter only takes effect when used together with a width specified in %%. It prevents scaling above the specified limit.
Horizontal orientation of the image (left, center, right or right with text flow). In case you select right with text flow content following the image will render on the left next to the image.
Left edge: value in % of the width where the piece you want to see starts
Top edge: value in % of the height where the piece you want to see starts
Right edge: value in % of the width where the piece you want to see ends
Bottom edge: value in % of the height where the piece you want to see ends
Border: check this to show a black border around the image
Enable pan and zoom: check this to activate pan and zoom for the SVG
Pan and zoom active from start: when checked pan and zoom is already active when the user starts to watch a page. However when e.g. the mouse is in the region of SVG and the user uses the mouse wheel the image is zoomed rather than the page is scrolled. Therefore you can configure whether pan and zoom is active from the beginning. When not checked the user has to click inside the SVG (outside any link!) to activate pan and zoom or use a zoom button if present. As this is not a standard behavior you may need to provide instructional text in your Confluence page.
Show zoom buttons: show zoom buttons (+, - and reset) under the image. The zoom buttons are only shown in case pan & zoom is enabled.
Use mouse wheel: allow the user to use the mouse wheel for zooming.
Maximum zoom level: the maximum zoom level the user can zoom in
Minimum zoom level: the minimum zoom level the user can zoom out
Internet explorer tool tips: when checked tool tips in the SVG will also be shown in Internet Explorer 9-11
Highlight links on hover: highlight links embedded in the SVG on hover
Highlight links permanently: highlight links embedded in the SVG permanently
Export resolution: the relative resolution (in comparison to the standard Confluence resolution) used when rasterizing the SVG in PDF or Word export. Increase the value to get a better resolution (slower, bigger file) and decrease it to make the PDF smaller and faster in generation.

The following picture should help:

Tip: Negative values for the left edge or the top edge and values above 100% for the right edge or bottom edge will result in a frame around the SVG in the background color.

Replacing links in the SVG

In case you want to link to Confluence content within a SVG you will run into unnecessary update work when the content moves. In order to prevent this the macro contains a link-change-functionality. The hard links in the SVG can be changed to Confluence links which will be updated automatically when the content moves. To do so you have to write the link text to replace in the body of the macro and attach a link to this text which points to the new target. Example: in case you inserted a placeholder link like "check_link" in the SVG, type "check_link" in the body and add a link to it pointing to right place in your Wiki or somewhere else. You can type as many "link-replacers" as you want in the body - in the screenshot below there are three.

Remark: some SVG sources enforce the format http://example.com for links even when you only type example.com. In this case the proper text in the body would be http://example.com.

Replacing/adding tool tips

You may already include tool tips in the SVG when designing the SVG (tool tips are part of the link and are stored in the attribute xlink:title). Chrome and Firefox will show those tool tips. Internet Explorer 9-11 only shows the tool tips in case you active the "Internet Explorer tool tips" option in the macro.

In addition to the above you may also add/replace tool tips in Confluence. However you can only add or replace a tool tip in case you replace a link as shown the the chapter before. To add/replace a tooltip simply append "tooltip=xyz" behind the link like the following example shows:

In the sample above a tool tip is added to the start and analyse link.

Macro "SVG out body injected"

Purpose

This macro is used to render SVGs provided by other plugins like Graphviz or PantUML.

Parameters

The "SVG out body injected macro" has the same parameters as the SVG out macro except page and SVG file as the SVG image comes via the macro body.

Usage

The body of the "SVG out body injected macro" has to contain the macro delivering the SVG (like PlantUML or Graphviz). Please only insert one other macro in the body and ensure that you set the output of that macro to SVG. The following image shows an example:

wiki editor injected.png

Tip: the easiest way to add the "SVG out body injected macro" around an existing macro is to select the macro and then insert the "SVG out body injected macro". Confluence will automatically move the selected macro into the body.

SVG indexing

SVG out comes with a module which extracts the text elements of an SVG providing them to the Confluence search.

Tip: to index SVGs which were already present before you installed the version of SVG out which supports SVG indexing it might be necessary to rebuild the index.

What SVG sources have been tested?

Application	Special parameters	Outcome
Inkscape	no units in SVG	all fine
Inkscape	mm as width and size	all fine
draw.io		draw.io tends to include HTML in the SVGs. The SVGs render fine except for export. In case you want to export them follow this post.
Microsoft Visio		Visio has some issues with SVG export; however the issues are not related to this plugin; sometimes the SVG is shown correctly when you open it as SVG in the browser - however as soon as you embed the same SVG it into HTML it looks different - unfortunately there is currently nothing I can do about this
Adobe Illustrator		Adobe Illustrator does sometimes not set width and height of the image; the plugin uses the data of the so called viewBox then; as a result the image might render quite small; you have to increase the relative width and height to make it render bigger
Freemind		Freemind does not set links in the exported SVG; this issue is not related to the plugin
LibreOffice Draw	size in mm	sometimes fine; general: LibreOffice 4.3.x always includes a link in the form http://replace_xyz/ even when you only type replace_xyz; sometimes LibeOffice exports SVGs which do not render in any browser - however this is not related to the plugin
PlantUML	output as SVG	all fine
Graphviz	output as SVG	all fine
Matlab		working since version 2.2.3
Confluence roadmap macro		does NOT work as the output is not a pure SVG - it is a SVG with a HTML overlay which we can't handle properly

Known limitations

The following known limitations exist:

In the Confluence editor the macro renders like other macros and not as nice as regular images.
In case you refer to a page in another space which contains the svg and this page is renamed or moved you will get an error message that the plugin is not able to find the page. This is due to a bug in the Atlassian script responsible for the page/attachment functionality in the macro dialog.
Dynamic content (SVGs which contain Javascript) is generally supported. In case the embedded Javascript changes the outer dimensions of the SVG it will interfere with the maco however.

Trouble-shooting

Security check negative

In case you get a message similar to the following:

svg-out: Sorry, the security check was negative! You may ask an administrator or another member of the appointed group to white-list your SVG.

the security check of the SVG was negative. This might have two reasons:

you included an SVG which really is a threat as it e.g. contains scripting parts
you included an SVG which is safe but triggered the message anyhow - you may ask an admin to white-list your SVG as described in the configuration section in this document

The technical details of the security check are described here.

My SVG does not look as intended

First please check how the SVG looks when you open it with your favorite browser. In case it renders properly there but not using this macro please submit a bug report as stated below. In other cases you have to modify your SVG such that it looks good in the browser and then retry with this macro.

Older version of Internet Explorer

Older versions of Internet Explorer (like IE 8) do not render SVGs.

Out of memory exception

When exporting to PDF or Word you are more likely run into an out of memory exception compared to older versions of SVG out. This is because of the size of the Batik library used.

Confluence crashes due to 'java.lang.OutOfMemoryError Metaspace' error

Other error messages

In case you face any exceptions and the SVG looks good when you open it in the browser please submit a bug report as stated below.

Getting support

Please use out ticketing system to create a support request regardless wether you found a bug or have a feature request. Existing bugs or feature requests are here.