JiriLojda/integration-diagrams-net

Kontent.ai and diagrams.net integration

Kontent.ai integration with diagrams.net

This integration contains a custom element that you can use in Kontent.ai to create and edit diagrams in diagrams.net directly from the Kontent.ai app. The custom element stores the created diagram in the xml format and a data url to use it on your site.

Getting Started

The integration is created with Create React App.

First you will need to install npm dependencies with npm install. Then use npm run build to build the integration or npm run start to start a local development server. See https://create-react-app.dev/docs/available-scripts for more scripts.

You can also provide a configuration to the element, but it is entirely optional.

The diagrams.net editor is opened in a new tab so that you have enough space for your diagram. Changes in the editor are auto-saved to Kontent.ai. However, if you leave the item editing or switch to a different content group in the Kontent.ai tab, the connection breaks and further changes to the diagram won't be saved.

Configuration

You can provide an optional configuration. See the example bellow.

integration-diagrams-net/src/constants/readmeSnippets.ts

Lines 3 to 22 in 71cf868

	export const exampleConfiguration: Required<Config> = {
	previewBorder: { // if defined, show a border around the diagram preview
	color: "#000000", // border color
	weight: 1, // border width
	},
	previewImageFormat: {
	format: "png", // one of "svg" or "png". Set this to png when you use custom font as diagrams.net includes the font in the generated preview data-url which makes it too large.
	// customFont: { // this can only be used with format: "svg"
	// customFontConfigType: "nameAndUrl", // alternatively this can also be "fontFaceDefinition"
	// fontUrl: "<url to our custom font>", // this must only be used with customFontConfigType: "nameAndUrl"
	// fontName: "<name of our custom font, this must be used inside the svg elements>", // this must only be used with customFontConfigType: "nameAndUrl"
	// // fontFaceDefinition: "<font face definition>", // this must only be used with customFontConfigType: "fontFaceDefinition"
	// }
	},
	configuration: { // diagrams.net configuration, see https://www.diagrams.net/doc/faq/configure-diagram-editor for available keys
	colorNames: {
	"000000": "Our color",
	},
	},
	};

Deploy

To use the custom element you need to deploy it.

Netlify has made this easy. If you click the deploy button below, it will guide you through the process of deploying it and leave you with a copy of the repository in your account as well.

The repository has the continuous delivery configuration using GitHub Actions being triggered by the new release and releasing to gh-pages branch. This setup is used for internal purposes. If you want to use the custom element, the recommended way is to fork the repository, make a code review, and deploy the repository on your own.

Saved value

This is an example of a value saved in the custom element that can be used on your site. Keep in mind that it is serialized into string.

integration-diagrams-net/src/constants/readmeSnippets.ts

Lines 24 to 31 in 71cf868

	export const exampleValue: Value = {
	xml: "...", // the diagram in xml format used by diagrams.net
	dataUrl: "...", // data-url of svg preview of the diagram for preview
	dimensions: { // dimensions of the diagram calculated by diagrams.net
	width: 100,
	height: 100,
	},
	};

Known Issues

Value is too large for Kontent.ai with a custom font used in the diagram.

When using the "previewImageFormat": { "format": "svg" } and a custom font in the diagram, diagrams.net includes the whole font in the data-url for preview. This makes it (and the value as the data-url is saved as well) too large. To avoid the problem, you can do one of the following:

• Set "previewImageFormat": { "format": "png" } in your configuration. PNG's don't have this problem, but are usually bigger and don't scale so the SVG is the default.
• Make the integration replace the custom font in the SVG with your font's url. You will need to provide the url in the configuration. Please, keep in mind that SVGs with links to external sources won't load the source in the <img /> tag. You will need to use the <object /> tag to display such an SVG.

{
  "previewImageFormat": { 
    "format": "svg",
    "customFont": {
      "customFontConfigType": "nameAndUrl",
      "fontName": "<your font name>",
      "fontUrl": "<your font url>"
    }
  },
  // or
  "previewImageFormat": { 
    "format": "svg"
    "customFont": {
      "customFontConfigType": "fontFaceDefinition",
      "fontFaceDefinition": "@font-face { font-name: 'your-font-name'; src: 'your-font-url'; }" // this allows more flexibility, you can have multiple @font-face definitions and custom font-face properties
    }
  }
}

Contributing

For Contributing please see CONTRIBUTING.md for more information.

License

Distributed under the MIT License. See LICENSE.md for more information.