UI Builder - Adding Properties to a Custom Component

#UI Builder , #UI Builder Bytes , #Quebec , #Now Experience

Brad Tilton

4 minute read

The developer advocate team is currently ramping up on the Rome release features so we can start bringing you great Rome release developer content, but I wanted to pause and write this post because it’s been a little while since we’ve had a UI Builder Bytes post. I had someone reach out via the community the other day because they had seen my UI Builder - Adding a Customer Component with Events post, and they were wondering what they needed to do to get their components’ properties exposed in UI Builder in addition to the events. It is a very straightforward process (and much easier than events) that I want to document here.

Setting up your initial component

This assumes you have already installed and configured the Quebec version of the ServiceNow CLI and UI Component extension.

  1. First, I created a local directory, then I ran the following to create my project in that directory.

        $ snc ui-component project --name @btt/properties-blog

  2. Next, I installed dependencies.

        $ npm i

Adding Properties to your Component

  1. Now that the component was scaffolded with dependencies installed, I opened the src/x-85636-properties-blog/index.js file and added a property named text that I then called within the div tag.

    Original:

    import {createCustomElement} from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';
import styles from './styles.scss';

const view = (state, {updateState}) => {
    return (
        <div></div>
    );
};

createCustomElement('x-85636-properties-blog', {
    renderer: {type: snabbdom},
    view,
    styles
});

    New version:

    import {createCustomElement} from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';
import styles from './styles.scss';

const view = (state, {updateState}) => {
    const {properties} = state;
    return (
        <div>{properties.text}</div>
    );
};

createCustomElement('x-85636-properties-blog', {
    renderer: {type: snabbdom},
    view,
    properties: {
        text: {default: 'Hello Brad'}
    },
    styles
});

  2. I then tested by running a $ snc ui-component develop and looking to see if my Hello Brad message displayed in the browser window.

  3. The next part is where I was able to tell my component that it should expose this property within UI Builder. I opened the now-ui.json file and change it from:

    {
    "components": {
        "x-85636-properties-blog": {
            "innerComponents": [],
            "uiBuilder": {
                "associatedTypes": ["global.core", "global.landing-page"],
                "label": "Properties Blog",
                "icon": "document-outline",
                "description": "Component used for the UI Builder properties blog",
                "category": "primitives"
            }
        }
    },
    "scopeName": "x_85636_btt_prop_2"
}

    to:

    {
    "components": {
        "x-85636-properties-blog": {
            "innerComponents": [],
            "uiBuilder": {
                "associatedTypes": ["global.core", "global.landing-page"],
                "label": "Properties Blog",
                "icon": "document-outline",
                "description": "Component used for the UI Builder properties blog",
                "category": "primitives"
            },
            "properties": [
                {
                    "name": "text",
                    "label": "Text",
                    "description": "",
                    "readOnly": false,
                    "fieldType": "string",
                    "required": true,
                    "defaultValue": "Here is some default text"
                }
            ]
        }
    },
    "scopeName": "x_85636_btt_prop_2"
    }

    You can see that I just added a properties object to the x-85636-properties-blog object.

Deploying the Component and using it in UI Builder

  1. After all of my local development was done I committed it to git here (because it’s the best way to backup local component development and share with colleagues).

  2. I then deployed the component to my PDI by using $ snc ui-component deploy.

  3. Lastly, I opened a blank page I had created in UI Builder, added the component, and tested the property as you can see in the gif below.

    Adding a component gif

As you can see, the process of exposing a component’s properties is pretty straightforward by editing the now-ui.json file in the component. I tried to use the simplest use case possible here, but you can expose multiple properties and are not limited to the string type.

More Resources

Make sure to check out the previous posts in this UI Builder series, and stay tuned for more posts.

Have a UI Builder topic you’d like me to hit in a future post? Let me know on Twitter, LinkedIn, or sndevs.com slack (@btilton).

Comments