While working with UI Builder, sometimes you might need to show a message to a user. You can do it by simply using Add alert notifications handler. But sometimes it may be more convenient to add the notification through a script, though. Sadly, the documentation on this is rather scattered. You can find a few examples of how to do this but there is not much explanation on how the whole thing works. This post seeks to fill this gap.
First, let´s see an example of a script displaying a notification:
*******************************************************************
api.emit("NOW_UXF_PAGE#ADD_NOTIFICATIONS", {
items: [
{
id: "greeting_1",
status: "moderate",
icon: "info-circle-outline",
content: "Hello, world!",
action: {
"type": "open",
"label": "Explore",
"href": "https://example.com"
}
}
]
});
*******************************************************************
So, what are we doing in this script? We call api.emit() function that takes two arguments:
- the name of the event that we want to emit
- in our case: NOW_UXF_PAGE#ADD_NOTIFICATIONS => this is the system name of the event for showing a message to the user
- the object with attributes that will modify the properties of the event
- in our case, we only have one such attribute: items => this is an array of objects representing the messages we want to show
Every such item-object has its own attributes that influence the content and form of the message. The main attributes are: id, status, icon, content, action. There are actually more of them but these are the most common ones.
Let´s take a closer look at each of these attributes:
- id
- a string that serves as unique identifier of the message
- you can use any string you want (be it "alert1" or "mambo_jambo_93", it´s really up to you)
- just remember: if a message is already being displayed on the page and you add a new message with the same id, then the old message will be overwritten by the new one
- status
- based on the value, the message will have a certain color
- for example, if you choose "status": "moderate" => the message will be somewhat purplish
- you can choose from these values:
- critical (red)
- high (orange)
- moderate (purple)
- warning (yellow)
- info (blue; this one is the default value)
- positive (green)
- low (grey)
- icon
- determines what icon will be displayed at the left side of the message
- the usual choice is "info-circle-outline" but you can choose based on your own preferences; the complete list of the icons and their names is to be found right here
- content
- string that will be shown to the user as the message
- action
- another object with a few attributes
- in general, these control how the message should be closed and whether clicking the closing button will take the user to a link
Attributes of the action object:
- type
- determines the appearance of the closing button
- you can choose from these values:
- "dismiss"
- the closing button will be a classical one ("X")
- "acknowledge"
- the closing button will read: "OK"
- "open"
- the closing button will read: "OPEN"
- optionally, you can specify your own label (see bellow)
- label
- can be used only in combination with "open" type
- if you specify a value, then the closing button will take the value as its label
- href
- can be used only in combination with "open" or "acknowledge" type
- the value should be a URL; if you specify it, then clicking on the closing button will redirect the user to the link
Here is how the message would look like based on our example´s configuration:
