@acoustic-content/ui-extensions

This module represents a Javascript library that can be used to create custom user interfaces for Elements and/or Content Types in Acoustic Content. Since Custom User Interfaces run within an iFrame, they can be built using any JS framework (e.g. Vanilla JS, JQuery, AngularJS, etc...).

Usage

This library depends on post-robot to enable cross domain messaging. You can use either of the following methods to get started writing your own UI extension:

Option 1: Add the following script tag to your Custom User Interfaces HTML file:

<script src="https://content-eu.goacoustic.com/auth/acoustic-content-ui-extensions.js"></script>

or

<script src="https://content-us.goacoustic.com/auth/acoustic-content-ui-extensions.js"></script>

NOTE: For Acoustic Content developers - If testing UI extensions on an internal environment, the above URL should be modified to point to the correct domain:

<script src="https://<Acoustic Content Domain>/auth/acoustic-content-ui-extensions.js"></script>

Option 2: Install the library as a node module through npm:

npm install --save @acoustic-content/ui-extensions

Examples

Some open source examples of Custom User Interfaces:

• Dropdown selection of songs from iTunes API
• Category selection from a custom taxonomy
• Color element
• Google map location selection
• Custom rich text editor
• Email element
• HTML editor on a file asset
• HTML editor on a text element

Creating your own Custom User Interface

Once the library has been added to your desired project, you will be able to access the variable wchUIExt which allows the extension to communicate with the Acoustic Content UI.

Methods

How to set element(s)

In order for the extension to set the JSON of an element, use the setElement and/or setElements methods. A more thorough list of the possible element types and corresponding JSON can be found here: https://developer.goacoustic.com/acoustic-content/docs/acoustic-content/ .

// Set values for different element types

// Text Element
wchUIExt.setElement(
    {
        elementType: "text",
        value: "Some text goes here"
    }
);

// Location Element
wchUIExt.setElement(
    {
        elementType: "location",
        latitude: 0.000000,
        longitude: 0.00000
    }
);

Custom User Interfaces can also be applied to a custom element or a content type.

NOTE: When setting the value of a Custom User Interface that is applied on a custom element, please remember to set the typeRef field as well. This can be retrieved from getDefinition() (refer to the example below).

For example, a map that stores a selected location:

// Set value for a CUSTOM ELEMENT that has a Custom User Interface applied with a location element

wchUIExt.getDefinition().then(definition => {
    wchUIExt.setElement({
        elementType: "group",
        typeRef: definition.typeRef,
        value: {
            "locationElementKey": {
                elementType: "location",
                latitude: 0.000000,
                longitude: 0.00000
            }
        }
    });
});

// Set value for a CONTENT TYPE that has a Custom User Interface applied with a location element

wchUIExt.setElement({
    "locationElementKey": {
        elementType: "location",
        latitude: 0.000000,
        longitude: 0.00000
    }
});

This behaviour can be extended to enable multiple fields to be encapsulated by the Custom User Interface. You can do this by calling the methods setElements and getElements.

For example, a map that stores both the location coordinates and country as a location and text element respectively:

// Set value for a CUSTOM ELEMENT that has a Custom User Interface applied with location and text elements

wchUIExt.getDefinition().then(definition => {
    wchUIExt.setElements({
        elementType: "group",
        typeRef: definition.typeRef,
        value: {
            "locationElementKey": {
                elementType: "location",
                latitude: 0.000000,
                longitude: 0.00000
            },
            "textElementKey": {
                elementType: "text",
                value: "Australia"
            }
        }
    });
});

// Set value for a CONTENT TYPE that has a Custom User Interface applied with location and text elements

wchUIExt.setElements({
    "locationElementKey": {
        elementType: "location",
        latitude: 0.000000,
        longitude: 0.00000
    },
    "textElementKey": {
        elementType: "text",
        value: "Australia"
    }
});

How to get element(s)

To get the element JSON of the elements that have been set using the setElement and/or setElements methods, you can use the getElement and/or getElements methods. These methods are used to prepopulate fields for saving drafts and for displaying the set values once a piece of content has been published.

// Get the text value that has been set

wchUIExt.getElement().then(element => {
    if (element.value) {
        // Do something with this value
    }
});

// Get value for a CUSTOM ELEMENT that has a Custom User Interface applied with a location element

wchUIExt.getElement().then(element => {
    if (element.value["locationKey"].longitude && element.value["locationKey"].latitude) {
        // Do something with this value
    }
});

// Get value for a CONTENT TYPE that has a Custom User Interface applied with a location element

wchUIExt.getElement().then(element => {
    if (element["locationKey"].longitude && element["locationKey"].latitude) {
        // Do something with this value
    }
});

If the user decideds to enable multiple fields to be encapsulated by the Custom User Interface, they will either have to set the custom user interface on the Content Type or a Custom Element. You can then retrieve the values for each element using getElements().

NOTE: If you are applying the Custom User Interface on a Content Type or Custom Element with multiple elements, then it is your responsiblity to implement the UI for each of these elements.

// Get value for a CUSTOM ELEMENT that has a Custom User Interface applied with a location element AND text element

wchUIExt.getElements().then(element => {
    if (element.value["locationKey"].longitude && element.value["locationKey"].latitude) {
        // Do something with this value
    }
    if (element.value["textElementKey"].value) {
        // Do something with the text value
    }
});

// Get value for a CONTENT TYPE that has a Custom User Interface applied with a location element AND text element

wchUIExt.getElements().then(element => {
    if (element["locationKey"].longitude && element["locationKey"].latitude) {
        // Do something with this value
    }
    if (element["textElementKey"].value) {
        // Do something with the text value
    }
});

How to get the full content

The content JSON provides information about the parent content item. This allows the element to know the properties and definitions of other elements in the content as well as metadata about the content itself. An extract of a sample content JSON is as follows:

{
    id: "925d1454-167b-431b-a54c-6cbf0354398d",
    rev: "25-2ba981d0661c3129c31cc4993e569e3f",
    name: "Sample Content",
    description: "An example description of the sample content",
    typeId: "b0798e67-3da2-48b4-b044-016495fa3ead",
    type: "Article",
    lastModified: "2016-11-02T06:28:47Z",
    lastModifierId: "63b800fa-51a7-4602-8cbe-ab3b9cee28b9",
    lastModifier: "Thomas Watson",
    created: "2016-11-02T06:28:47Z",
    creatorId: "8c622bbb-5f5b-45d4-89e1-fce1c054138f",
    creator: "Thomas Watson",
    elements: {
        datekey: {
            elementType: "datetime",
            value: "2016-11-07T10:09:00Z"
        },
        textkey: {
            elementType: "text",
            value: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"
        },
    },
    tags: [
        "news",
        "sample"
    ],
    links: {
        self: {
            href: "/authoring/v1/content/925d1454-167b-431b-a54c-6cbf0354398d"
        },
        linkedDoc: {
            href: "/authoring/v1/content/fd95f9a53edd5c2ae4ebdf2ba464a0f9"
        }
    }
}

wchUIExt.getContent().then(content => {
    // Your code
});

How to get the element definition

The definition of an element provides information about the properties of the element. A sample text element definition is as follows:

{
    elementType: "text",
    label: "text",
    key: "text",
    required: true,
    minLength: 1,
    disabled: false
}

wchUIExt.getDefinition().then(definition => {
    // Your code
});

The key is a unique identifier of the given element and can be used to distinguish elements when getting/setting multiple elements. The disabled field is set to true if the content has been published and set to false if the content is still a draft. You can use this field in order to display a different view for published content (e.g. disabled text input field).

How to get the content metadata

The content metadata provides information about the properties of the content that the element is a part of. A sample content metadata is as follows:

{
    id: "3e1a8bf6-ad09-4d38-a0b2-9875924dff44",
    name: "Content Name",
    status: "draft"
}

wchUIExt.getContentMetadata().then(contentMetadata => {
    // Your code
});

The id and name identify the content that the element which the ui-extension is applied to. The status refers to the current status of the content (e.g. draft, published).

How to set iFrame height

Since the Custom User Interface is displayed in the UI within an iFrame, it is important to set the desired height of this iFrame. E.g. dropdowns can have a shorter height set as default (100) and a taller height set when the dropdown is toggled open. The integer values are in pixels.

// Function to open dropdwon

function open() {
    // Code to trigger opening dropdown
    wchUIExt.requestResizeFrame(400);
}

// Function to close dropdown

function close() {
    // Code to trigger closing dropdwon
    wchUIExt.requestResizeFrame(100);
}

How to control validation of an element

The Custom User Interface can control what determines a valid entry. If the entry is invalid, a warning will be shown in the UI, and the content cannot be published.

For example, an email Custom User Interface would be based on a text element. The text element allows any text to be stored for the email address, but the Custom User Interface does not allow content to be published if the email address is not valid - eg., it does not contain an @ symbol

In order to declare whether the value entered in the Custom User Interface is valid, you can use the setValid method. The following are several use cases for the validate method:

// Declare the element to be valid
wchUIExt.setValid(true);

// Declare the element to be invalid but don't show the invalidation message in the UI
wchUIExt.setValid(false, false);

// Declare the element to be invalid and show a custom invalidation message in the UI
wchUIExt.setValid(false, true, "The input value is an invalid value");

How to get the tenant configuration

The tenant configuration provides details such as the tenantId and all other relevant URL endpoints. A sample tenant config is as follows:

{
    tenantId: "3e1a8bf6-ad09-4d38-a0b2-9875924dff44",
    apiUrl: "https://content-YY-X.content-cms.com/api/XXX",
    resourceUrl: "https://content-YY-X.content-cms.com/api/XXX",
    host: "content-YY-X.content-cms.com"
}

where YY is eu or us

wchUIExt.getTenantConfig().then(tenantConfig => {
    // Your code
});

How to get the current user information

The user object provides information such as the user-id, roles and external-id. A sample user object is as follows:

{
    externalId: "[email protected]",
    displayName: "User_Name",
    roles: ["admin"],
    id: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

wchUIExt.getUser().then(user => {
    // Your code
});

How to get the UI locale

The UI locale provides the current UI Locale of Acoustic Content. A sample UI Locale is as follows:

en-US

wchUIExt.getCurrentLocale().then(locale => {
    // Your code
});

Events

We support the ability to add a listener to events within the content form. Currently this support extends to content updates and element validations.

A user can subscribe to an event through the on() method. This method takes in the name of the event that you want to subscribe to and the callback method to execute when the event gets triggered. Currently the supported list of event names are:

1. contentUpdate
2. validate

Subscribing to content updates

This event will trigger when a content update has occured. The user can then make a request in order to get the updated content by calling getContent().

wchUIExt.on("contentUpdate", () => {
    // This callback will get triggered when content gets updated

    // User can then get the updated content
    wchUIExt.getContent().then(content => {
        console.log(content);
    });
});

Subscribing to element validate

This event will trigger when a validation check has been made on the content item. The user can then set the validation based on the users own validation checks in their custom user interface.

wchUIExt.on("validate", () => {
    // This callback will get triggered when validation check is done on the content item

    // User can then set validation
    wchUIExt.setValid(true);
});

back to top