npm package: @ibm-wch/ui-extensions
Description: This module represents a Javascript library that can be used to create custom user interfaces for Elements and/or Content Types in Watson Content Hub (WCH). Since custom user interfaces run within an iFrame, they can be built using any JS framework (e.g. 
Latest version: 1.3.3
Deprecated: This package has been renamed to @acoustic-content/ui-extensions.


# ibm-wch-custom-user-interfaces

This module represents a Javascript library that can be used to create custom user interfaces for Elements and/or Content Types in Watson Content Hub (WCH). 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](https://github.com/krakenjs/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:
```html
<script src="https://www.digitalexperience.ibm.com/auth/ibm-wch-ui-extensions.js"></script>
```

**NOTE:** If testing Custom User Interfaces on a different environment, the above URL **must** be modified to point to the correct domain:

```html
<script src="https://www.<WCH-DOMAIN>/auth/ibm-wch-ui-extensions.js"></script>
```

#### Option 2: Install the library as a node module through npm:
```bash
npm install --save @ibm-wch/ui-extensions
```

## Examples

Some open source examples of Custom User Interfaces:

- [Dropdown selection of songs from iTunes API](https://github.com/ibm-wch/sample-custom-element-ui/tree/master/sample-ui-extension-dropdown)
- [Category selection from a custom taxonomy](https://github.com/ibm-wch/sample-custom-element-ui/tree/master/sample-ui-extension-category)
- [Color element](https://github.com/ibm-wch/sample-custom-element-ui/blob/master/sample-ui-extension-colorpicker)
- [Google map location selection](https://github.com/ibm-wch/sample-custom-element-ui/tree/master/sample-ui-extension-map)
- [Custom rich text editor](https://github.com/ibm-wch/sample-custom-element-ui/tree/master/sample-ui-extension-rte)
- [Email element](https://github.com/ibm-wch/sample-custom-element-ui/tree/master/sample-ui-extension-email)
- [HTML editor on a file asset](https://github.com/ibm-wch/sample-custom-element-ui/blob/master/sample-ui-extension-htmleditorv2)
- [HTML editor on a text element](https://github.com/ibm-wch/sample-custom-element-ui/blob/master/sample-ui-extension-htmleditorv1)

## 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 WCH 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.ibm.com/customer-engagement/docs/wch/authoring-content/ .

```javascript
// 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:

```javascript
// 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
            }
        }
    });
});
```

```javascript
// 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:

```javascript
// 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"
            }
        }
    });
});
```

```javascript
// 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.

```javascript
// Get the text value that has been set

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

```javascript
// 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
    }
});
```

```javascript
// 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.

```javascript
// 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
    }
});
```

```javascript
// 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:

```javascript
{
    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"
        }
    }
}
```

```javascript
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:

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

```javascript
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:

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

```javascript
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`.

```javascript
// 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:

```javascript
// 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:

```javascript
{
    tenantId: "3e1a8bf6-ad09-4d38-a0b2-9875924dff44",
    apiUrl: "https://myX.digitalexperience.ibm.com/api/XXXX",
    resourceUrl: "https://myX.digitalexperience.ibm.com/api/XXXX",
    host: "myX.digitalexperience.ibm.com"
}
```

```javascript
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:

```javascript
{
    externalId: "user@email.com",
    displayName: "User_Name",
    roles: ["admin"],
    id: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}
```

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

### How to get the UI locale

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

```javascript
en-US
```

```javascript
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()`. 

```javascript
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`.

```javascript
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](#ibm-wch-custom-user-interfaces)