SOLVED: Custom Component: How to use "requiredSysProps" and "requiredTranslationKeys"?

[aasch]

Hey,

I've been digging at custom Components for UI Builder.

The CLI reference for "Component Configuration" mentions two properties for the "now-ui.json" file:

• requiredSysProps
• requiredTranslationKeys

How do I work with these two properties?
How can I access the System Properties and Translation Keys inside a Component or inside the UI Builder interface?

---------
Context:

So far I can only guess how to apply the properties.
The translation keys might or might not have something to do with the translation service that's mention in the UI Framework reference for translations.
However it's never explicitly mentioned whether the translation keys you provide in now-ui.json will be preloaded or automatically wired to Component properties.

For the "requiredSysProps" I haven't found any chapter in the documentation that seems even remotely on topic.
After calling "snc ui-component deploy" I can see that the requiredSysProps I added in my now.ui-json were automatically added to the "UX Component Definition" record of my custom Component:

Unfortunately I have not found out how to wire it up so that the Component has access to it.
Is there some property of the createCustomElement function System Properties will be passed to?
Will it be automatically wired to a propery of the properties object, if I create a property with the same name?

Any help would be appreciated 🙂

Best regards,
Aaron

[aasch · Accepted solution]

There seems to be a global object "ux_globals" in the browser that has a "sysprops" property.
I can find my "my.sys.prop" System Property and its value in it.

Can anybody confirm whether this is the correct way to access System Properties with "requiredSysProps"?

-----

I'm now able to add the value of my System Property to my view.

You can't fetch it in the "properties" object you pass to the createCustomElement function, because System Property values won't be available there yet.
But if you do it in the "setInitialState" function, the value seem to be there.

My code now looks something like this:

And the function that constructs my view now has access to the value from the state:

Which happily results in this:

-----

To get to "ux_globals" was a small Odssey.

Using the Next Experience Developer Tools, I was able to make out that the Page component has a "nowSysProps" property:

Scrolling all the way down, I can see my System Property happily sitting there:

Having found out about nowSysProps, I started searching the DOM via the regular browser dev tools.
Eventually I found the ux_globals object.

Way after that I did find a reference to System Properties (and the "ux_globals" object) in the documentation.
The "Persisting Metric" part of the UI Framework reference casually drops a reference to ux_globals in a subclause.
It doesn't explain the object, nor its origins, now whether it's the proper way to access System Properties with.

It seems that all System Properties and their values listed in the "now-ui.json" file will be made into a property of the page component. That's in line with what I expect the now-ui.json to do.

Instead of using "ux_global" I suspect there should be a way to properly access System Properties in a Component on the Page. Via context or something else that gets passed down.

I really wish the "Component Configuration" part of the CLI reference would drop a hint about any of this.

[aasch · Accepted solution]

There seems to be a global object "ux_globals" in the browser that has a "sysprops" property.
I can find my "my.sys.prop" System Property and its value in it.

Can anybody confirm whether this is the correct way to access System Properties with "requiredSysProps"?

-----

I'm now able to add the value of my System Property to my view.

You can't fetch it in the "properties" object you pass to the createCustomElement function, because System Property values won't be available there yet.
But if you do it in the "setInitialState" function, the value seem to be there.

My code now looks something like this:

And the function that constructs my view now has access to the value from the state:

Which happily results in this:

-----

To get to "ux_globals" was a small Odssey.

Using the Next Experience Developer Tools, I was able to make out that the Page component has a "nowSysProps" property:

Scrolling all the way down, I can see my System Property happily sitting there:

Having found out about nowSysProps, I started searching the DOM via the regular browser dev tools.
Eventually I found the ux_globals object.

Way after that I did find a reference to System Properties (and the "ux_globals" object) in the documentation.
The "Persisting Metric" part of the UI Framework reference casually drops a reference to ux_globals in a subclause.
It doesn't explain the object, nor its origins, now whether it's the proper way to access System Properties with.

It seems that all System Properties and their values listed in the "now-ui.json" file will be made into a property of the page component. That's in line with what I expect the now-ui.json to do.

Instead of using "ux_global" I suspect there should be a way to properly access System Properties in a Component on the Page. Via context or something else that gets passed down.

I really wish the "Component Configuration" part of the CLI reference would drop a hint about any of this.

[aasch · Accepted solution]

I was able to find this out about translations:

The property "requiredTranslationKeys" refers to keys in the well-known Message table (sys_ui_message) that is used for regular translations.

For everything to work, you need to do a few things:

1. Create all Messages needed
2. List all required Message keys as strings in the "now-ui.json" file in the "requiredTranslationKeys" property
3. Install the "@servicenow/library-translate" package as mentioned in the UI Framework reference
4. Import the "t" function in your component
5. Use the t function insinde your view template and provide it with a message key

Details:

1.:

2.:

{
  "components": {
    "x-191581-example-translations": {
      "innerComponents": [],
      "uiBuilder": {
        "associatedTypes": [
          "global.core",
          "global.landing-page"
        ],
        "label": "Example translations",
        "tileIcon": "./tile-icon/generic-tile-icon.svg",
        "description": "A description of my component",
        "category": "primitives"
      },
      "requiredTranslationKeys":[
        "T_FOO",
        "T_BAR"
      ]
    }
  },
  "scopeName": "x_191581_example_0"
}

3.:

Install the translation package via "npm install @Servicenow/library-translate -E" as described in the framework reference.

4.:

Put this at the top of your component file, e.g. "index.js":

import {t} from '@servicenow/library-translate'

5.:

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

const view = (state, {updateState}) => (
	<div>
		<h1>Example translations</h1>
		<hr />
		<p>{t("T_FOO")}</p>
		<p>{t("T_BAR")}</p>
	</div>
);

createCustomElement('x-191581-example-translations', {
	renderer: {type: snabbdom},
	view,
	styles
});

Resulting Component on a test Page:

Important:

If you don't list the required translation keys in "now-ui.json", the t-function will not automatically pull in the Messages. It will just show the keys as strings instead, see below.

Troubleshooting:

The Component compiled and deployed perfectly fine, but the "@servicenow/library-translate" package gave me an error in the browser console, preventing the Component from rendering at all. I had to edit a source file to make it work.
I assume it's either a mistake in my setup, but I couldn't find any hint anywhere.

If you get a ReferenceError calling out the missing "process" variable, you might also have to do this fix.

In your project files, go to the "node_modules/@servicenow/library-translate/src" folder.
Open the "index.js" file and search for "process" at the bottom.

In the if clause we need to check for the type of the process variable instead of using it directly.
That way in case the variable doesn't exist, it will not throw a ReferenceError.

So change this:

if (process && ...) 

To this:

if (typeof process != 'undefined' && ...) 

 And then re-deploy (which automatically includes re-compiling) your Component.