@acoustic-content/ui-extensions 中文文档教程

Question

@acoustic-content/ui-extensions

此模块代表一个 Javascript 库，可用于为声学内容中的元素和/或内容类型创建自定义用户界面。 由于自定义用户界面在 iFrame 中运行，因此可以使用任何 JS 框架（例如 Vanilla JS、JQuery、AngularJS 等）构建它们。

Usage

该库依赖于 post-robot 来启用跨域消息传递。 您可以使用以下任一方法开始编写您自己的 UI 扩展

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>

或

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

： 正确的域：

<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

自定义用户界面的一些开源示例：

• 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

将库添加到所需项目后，您将能够访问变量 wchUIExt，它允许扩展与声学内容通信用户界面。

Methods

How to set element(s)

为了让扩展设置元素的 JSON，请使用 setElement 和/或 setElements 方法。 可在此处找到可能的元素类型和相应 JSON 的更详尽列表：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
    }
);

自定义用户界面也可以应用于自定义元素 或内容类型。

注意：在设置应用于自定义元素 的自定义用户界面的值时，请记住同时设置typeRef 字段。 这可以从 getDefinition() 中检索（请参阅下面的示例）。

例如，存储选定位置的地图：

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

可以扩展此行为以允许自定义用户界面封装多个字段。 您可以通过调用方法 setElements 和 getElements 来完成此操作。

例如，将位置坐标和国家/地区分别存储为位置和文本元素的地图：

// 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)

获取已使用 setElement 和/或 setElements 设置的元素的元素 JSON 方法，您可以使用 getElement 和/或 getElements 方法。 这些方法用于预填充字段以保存草稿并在发布内容后显示设置值。

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

如果用户决定启用自定义用户界面封装多个字段，他们将必须在 Content Type 或 Custom Element 上设置自定义用户界面。 然后，您可以使用 getElements() 检索每个元素的值。

注意：如果您在内容类型或具有多个元素的自定义元素上应用自定义用户界面，那么您有责任实施每个元素的 UI。

// 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

内容 JSON 提供有关父内容项的信息。 这允许元素知道内容中其他元素的属性和定义以及关于内容本身的元数据。 示例内容 JSON 的摘录如下：

{
    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

元素的定义提供有关元素属性的信息。 示例文本元素定义如下：

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

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

key 是给定元素的唯一标识符，可用于在获取/设置多个元素时区分元素。 如果内容已被发布，则disabled字段设置为true，如果内容仍未发布，则设置为false 草稿。 您可以使用此字段为已发布 内容显示不同的视图（例如禁用的文本输入字段）。

How to get the content metadata

内容元数据提供有关元素所属内容的属性的信息。 示例内容元数据如下：

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

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

id 和 name 标识应用 ui-extension 的元素的内容。 status 是指内容的当前状态（例如draft、published）。

How to set iFrame height

由于自定义用户界面显示在 iFrame 内的 UI 中，因此设置此 iFrame 的所需高度非常重要。 例如，下拉菜单可以将较短的高度设置为默认值 (100)，并在打开下拉菜单时设置较高的高度。 整数值以像素为单位。

// 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

自定义用户界面可以控制确定有效条目的内容。 如果条目无效，将在 UI 中显示警告，并且无法发布内容。

例如，电子邮件自定义用户界面将基于文本元素。 文本元素允许为电子邮件地址存储任何文本，但自定义用户界面不允许在电子邮件地址无效时发布内容 - 例如，它不包含 @ 符号

为了声明是否在自定义用户界面中输入的值有效，您可以使用 setValid 方法。 以下是验证方法的几个用例：

// 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

租户配置提供详细信息，例如 tenantId 和所有其他相关的 URL 端点。 示例租户配置如下：

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

其中 YY 是 eu 或 us

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

How to get the current user information

用户对象提供信息，例如 user-id、角色 和 external-id。 示例用户对象如下：

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

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

How to get the UI locale

UI 语言环境提供了当前的声音内容 UI 语言环境。 示例 UI Locale 如下：

en-US

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

Events

我们支持向内容表单中的事件添加侦听器的能力。 目前，此支持扩展到内容更新 和元素验证。

用户可以通过 on() 方法订阅事件。 此方法接受您要订阅的事件的名称，以及当事件被触发时要执行的回调方法。 当前支持的事件名称列表是：

1. contentUpdate
2. validate

Subscribing to content updates

此事件将在发生内容更新时触发。 然后，用户可以通过调用 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

当对内容项进行验证检查时，将触发此事件。 然后，用户可以在其自定义用户界面 中根据用户自己的验证检查来设置验证。

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);
});

返回顶部