Embedding the SDK in a page¶

The SDK can be embedded by loading the Javascript code and stylesheet.

Assuming the SDK is hosted on https://example.com/sdk/1.0.0/, two resources need to be loaded.

Before you embed a particular version of the SDK, please familiarize yourself with the versioning policy.

Loading static assets¶

The default stylesheet

<link rel="stylesheet" href="https://example.com/sdk/1.0.0/open-forms-sdk.css" />

The Javascript code

<script src="https://example.com/sdk/1.0.0/open-forms-sdk.js"></script>

Calling the SDK¶

Once the Javascript is loaded, the module OpenForms is available. To initialize a form, use the constructor and initialize the form:

const form = new OpenForms.OpenForm(element, options);
form.init();

Where element is a valid DOM node and options an options Object, see Available options.

Available options¶

baseUrl:: Required. The API root of the Open Forms backend server. Note that this server must be configured to allow Cross Origin requests (CORS) from the domain where the SDK is used.
formId:: Required. The UUID or slug of the form to embed. This can be obtained via the Open Forms admin interface.
basePath:: Optional, but highly recommended. The SDK considers this as the base URL and builds all URLs relatively to this URL. If not provided, window.location.pathname is used.
CSPNonce:: Recommended. The page’s CSP Nonce value if inline styles are blocked by your Content Security Policy. The Open Forms SDK renders HTML in a number of places that may contain inline styles (as the result of a WYSYWIG editor). If a nonce is provided, the inline styles receive the value. Otherwise the styles will be blocked. This is not required if you have style-src 'unsafe-inline' as part of your policy.
lang:: Optional language to use for internationalizing. By default, this is looked up from the lang attribute of the html element in the DOM - if this is not set, the default value of 'nl' is used.
sentryDSN:: Optional Sentry DSN to monitor the SDK.
sentryEnv:: The label of the Sentry environment to use, for example 'production'. Used in combination with sentryDSN. Defaults to an empty string. Should be filled if sentryDSN is used but it’s not required.

Content Security Policy (CSP)¶

When you are embedding the SDK on your page, it must behave according to your Content Security Policy.

Certain components have specific CSP requirements.

Examples¶

Let’s assume these examples are hosted on: example.com/some-cms-page

Minimal example¶

<html>
<head>
    <!-- Required for icons used by Open Forms -->
    <meta charset="utf-8">

    <!-- Load stylesheet and SDK bundle -->
    <link rel="stylesheet" href="https://openforms.example.com/sdk/1.0.0/open-forms-sdk.css" />
    <script src="https://openforms.example.com/sdk/1.0.0/open-forms-sdk.js"></script>
</head>

<body>
    <!-- Load an Open Forms form and render it -->
    <div
        id="openforms-root"
        data-base-url="https://openforms.example.com/api/v1/"
        data-form-id="0d2f5453-8987-43dd-952e-aad3dd8f2318"
        data-base-path="/some-cms-page"
    ></div>
    <script>
        var targetNode = document.getElementById('openforms-root');
        var form = new OpenForms.OpenForm(targetNode, targetNode.dataset);
        form.init();
    </script>
</body>
</html>

Full example¶

<!-- Optional to render Open Forms in the proper language -->
<html lang="nl">
<head>
    <!-- Required for icons used by Open Forms -->
    <meta charset="utf-8">

    <!-- Load stylesheet and SDK bundle -->
    <link rel="stylesheet" href="https://openforms.example.com/sdk/1.0.0/open-forms-sdk.css" />
    <script src="https://openforms.example.com/sdk/1.0.0/open-forms-sdk.js"></script>
</head>

<body>
    <!-- Load an Open Forms form and render it -->
    <div
        id="openforms-root"
        data-base-url="https://openforms.example.com/api/v1/"
        data-form-id="0d2f5453-8987-43dd-952e-aad3dd8f2318"
        data-base-path="/some-cms-page"
        data-csp-nonce="OSUzOHNqqL9HzWU0CVSC/w\u003D\u003D"
        data-lang="nl"
        data-sentry-dsn="https://a45b81b258d462ae4ec474c10b6430cb@sentry.example.com/1"
        data-sentry-env="example"
    ></div>
    <script nonce="OSUzOHNqqL9HzWU0CVSC/w==">
        var targetNode = document.getElementById('openforms-root');
        var form = new OpenForms.OpenForm(targetNode, targetNode.dataset);
        form.init();
    </script>
</body>
</html>

Deploying the SDK¶

The SDK is published as container image on Docker Hub, containing the static Javascript and CSS assets:

open-forms-sdk.js and
open-forms-sdk.css

When you’re deploying the latest tag, these assets are available in the webroot, e.g. http://localhost:8080/open-forms-sdk.js.

When you’re using a pinned version, such as 1.0.0, the assets are available in that directory: http://localhost:8080/1.0.0/open-forms-sdk.js.

The SDK follows semantic versioning.