SVG Out for Confluence Data Center

What is it?

The SVG Out Confluence app closes a gap you might have discovered when including SVGs in your Confluence pages. Confluence is sometimes able to show and scale SVGs as images but it is not possible to use the links which might be included in the SVG. This app renders the SVG such that the links are still working. Furthermore it allows you to add links or 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)

• dynamic content within the SVGs (with some limitations)

• export to PDF and Word

Legal and policy documents

Look and feel

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

Open

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:

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:

Open

:bulb: 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 http://example.com . In this case the proper text in the body would be http://example.com.

Open

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:

Open

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:

Open

:bulb: 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.

:bulb: 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.

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.

• With Confluence 9.0 Atlassian introduced some significant changes us to use the bundled rasterization libraries for export to Word/PDF. We therefore output the SVG directly which works for some SVGs for others it doesn't - currently there is nothing we can do to fix that issue.

Trouble-shooting

Security check negative

In case you get a message similar to the following:

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

1. you included an SVG which really is a threat as it e.g. contains scripting parts

2. 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 whether you found a bug or have a feature request. Existing bugs or feature requests are here.