Customizing the draw.io interface in Confluence Server

About the Author:

2017-12-15T08:15:28+00:00 December 8th, 2017|draw.io, Tutorial, Videos|

You can make diagramming faster and easier by customizing the draw.io interface in Confluence server instances.

  • Do your diagrams need to match your corporate style?
  • Are you sick of having to constantly set specific fonts or add colors to the palette each time you create a new diagram?
  • Do you want to make a draw.io plugin available to your diagrammers by default?
  • Do you use a specific (non-default) shape or connector styling all the time?
  • Are you constantly using a shape library that isn’t displayed by default?
  • Do you add a copyright notice to each diagram?

You can save a lot of time, frustration and effort by customizing the draw.io interface to provide you with the shapes, fonts, colors and more that you consistently need, by default.

What can be customized in the draw.io interface?

As the Confluence administrator, you can set the following:

  • Fonts in the default font list.
  • The color schemes in the format panel and the more detailed color palette defaults.
  • Shape and connector styling defaults.
  • The default styles for shapes and connectors.
  • Built-in and custom shape libraries visible by default.
  • Custom CSS for both the draw.io menu and font styling in shapes. Styling the menu to match your Confluence instance’s style will make diagramming in draw.io feel more natural and will help users accept and adopt the tool more quickly and easily.
  • Custom fonts to be made available to people looking at your diagrams, even when the custom font is not installed on their computer.
  • draw.io plugins that should be enabled by default.
  • Diagram components (in XML format) that should be included in blank diagrams, for example, a copyright notice.
  • The default length of new connectors in your diagram.

All of this can be achieved by adding a combination of a JavaScript Object (JSON) and custom CSS to the Confluence stylesheets. You will also need to store your custom fonts, XML files and draw.io plugins (JavaScript files) in your Confluence instance.

Important: You must clear your browser’s cache before you will see any of the changes you make to the Confluence CSS stylesheets or draw.io app configuration.

Let’s take a look at a few examples.

Configure the color palette in draw.io

Making your corporate colors available by default in the color palette will help users create diagrams in your company’s official style faster and more reliably.

  1. In the Confluence administration section, click on draw.io > Add-on Configuration, found in the left hand panel.
  2. Click on the Add-on Configuration tab.
  3. In the UI Configuration field, you can add your list of colors using format as shown in the code below. There are three different color sets you can customize:
    • presetColors – changes the colors in the top color palette (two rows).
    • defaultColors – changes the colors in the lower large color palette.
    • defaultColorSchemes – changes the colors that are available at the top of the format panel, usually used to quickly style shapes.

In our example, we want to add two of the draw.io official orange colors to the start of the presetColors in the upper color palette by simply replacing the first two preset colors. If this was the only thing we wanted to change, we’d enter this code into the UI Configuration field:

{"presetColors": ["F08705", "E06D0C", "B5739D", "E1D5E7", "C3ABD0", "A680B8", "D4E1F5", "A9C4EB", "7EA6E0", "D5E8D4", "9AC7BF", "67AB9F", "D5E8D4", "B9E0A5", "97D077", "FFF2CC", "FFE599", "FFD966", "FFF4C3", "FFCE9F", "FFB570", "F8CECC", "F19C99", "EA6B66"]}

With both presetColors and defaultColors, simply enter the 6 digit color code numbers. Add a leading # to the color codes for the shapes and their outlines when changing the defaultColorSchemes, for example: {"fill": "#f5f5f5", "stroke": "#666666"}

draw.io - customized color palette

Set a default custom font

Not everyone may have your custom font installed, so you will also want to make it available to viewers through their browser.

Part 1 – Installing a custom font for draw.io in Confluence

  1. Attach the font file to a page within your Confluence instance.
  2. Right click on the attachment’s filename and copy the URL (link address) so you can paste it into the custom CSS stylesheet.
  3. In the Confluence administration, click on Look and Feel > Stylesheet in the left hand panel. On the Global Stylesheet page, click Edit, then enter the CSS for your custom font. In our example, the custom default font we want to use is Marvel, a TrueType font:

@font-face { font-family: 'Marvel'; src: url(/confluence/download/attachments/851969/Marvel-Regular.ttf?api=v2) format('truetype')}

draw.io customization - default font and plugin

Part 2 – Setting the default font

  1. In the Confluence administration left-hand panel, click on draw.io > Add-on Configuration, then click on the Add-on Configuration tab.
  2. In the UI Configuration field, add the code to customize the default fonts used by draw.io.In our example, we want to use our custom Marvel font as the default, both in the font list and in shapes and on connectors. We also have to include the details of our custom font that we have stored in our Confluence instance.

{"defaultFonts": ["Marvel", "Helvetica", "Verdana", "Times New Roman", "Garamond", "Comic Sans MS", "Courier New", "Georgia", "Lucida Console", "Tahoma"],"defaultVertexStyle": {"fontFamily": "Marvel"}, "defaultEdgeStyle": {"fontFamily": "Marvel"}, "fontCss": "@font-face { font-family: 'Marvel'; src: url(/confluence/download/attachments/851969/Marvel-Regular.ttf?api=v2) format('truetype')}"}

Different options for customizing default fonts:

  • defaultFonts – change the font selection list.
  • defaultVertexStyle – change the default font used in shapes by setting the font-family.
  • defaultEdgeStyle – change the default font used for labels on connectors by setting the font-family.
  • fontCSS – used to make custom fonts stored in your instance available to viewers who don’t have that font installed on their device – enter the font-family, URL and format.

Tip: Use a relative URL just in case you want to move your Confluence instance.

draw.io customization - use a custom font by default

Make a draw.io plugin available by default

Perhaps there is a draw.io plugin that you regularly use – animation, replaying changes or anonymizing data? No problems! Make the plugin available in the menu by default.

  1. Attach the plugin file (JavaScript file) to a page in your Confluence instance, and copy its URL (link address).
  2. In the Confluence administration section, click on draw.io > Add-on Configuration in the left hand panel, then on the Add-on Configuration tab.
  3. In the UI Configuration field, enter the plugin URL and details.

We want to make it easy for users to anonymize diagram data (delete potentially sensitive data from shapes, connectors and metadata), so they can submit their diagrams to us for debugging. If this were the only change we were making to the draw.io interface, we’d enter this into the UI Configuration field:

{"plugins": ["/confluence/download/attachments/851969/anonymize.js?api=v2"]}

We’ve used a relative URL just in case our Confluence instance moves – we don’t want to break our customizations!

Full list of available draw.io plugins

draw.io customization - default plugins

Combining customizations

The video below shows you how to combine multiple customizations, as in our three examples above. You will also see what happens (or doesn’t happen) when you don’t clear your browser’s cache! 😉

View the combined example JSON code as a text file, as entered into the UI Configuration field.

Please see the draw.io help desk for the full list of customization options, including their default values, as well as tips for debugging your JSON code.

Why customize the draw.io menu?

Intranets are more widely and quickly adopted, plus users are happier with them when they are styled to match their company’s corporate image. Providing users with a familiar menu color, matching your company’s custom Confluence interface will help them more quickly adapt to and enjoy using draw.io for diagramming.

You can style the draw.io menu by overriding the CSS. For example, we could add the following code in the UI Configuration field in the draw.io Add-on Configuration to turn the menu orange* to match the draw.io colors:

{"css": ".geMenubarContainer { background-color: #F08705 !important; } .geMenubar { background-color: #F08705 !important; }"}

* We wouldn’t do it, because orange is a horrid color for a menu background!

If you are using draw.io in multiple instances, changing the menu color will indicate quickly to users which instance they are currently working in.

draw.io - customized menu bar

Related information