Package sys.ui | Slingr platform documentation

Describes utilities to interact with the UI.

sys.ui

It is possible to interact with the UI by sending messages from server side scripts. This messages can tell the UI to perform different actions, like navigate to a view, reload the UI, show a message or trigger an action.

There are a few important things you need to take into account when working with UI messages:

Even though you can call this method from any script we recommend to use it only on scripts that are associated to views, like event scripts in views. This makes it more clear when they will be executed.
If you call this method from a script that is not associated to a view (for example, an action script) the message might not be sent to the UI and will be lost. For example if the action is executed in the background or the action is executed as part of another process that isn’t UI related (like an external REST API call).
You can send multiple messages to the UI and they will be executed in order. However it is important to understand that some messages could discard others. For example if you reload the page, any message after that command will be lost.
Messages might not be sent to the UI immediately; that’s implementation-specific based on the features available at the UI. UI messages might be executed only when the request has been completed.

All messages have at least two fields:

scope: indicates what’s the scope of the message and which elements in the UI should process them. Currently there are three, global, view, plugin and action.
name: this is the name of the message. It is unique inside each scope.
target: this is used to define the message addressee. The possibles values are caller: the user who initialize the ui request, users send the message to all users defined in targetUsers in all their tabs and allUsers a broadcast. Default value is caller.
targetUsers: addressee list just when target users is defined. It is an array of emails or ids. The default value is the current user.
views: this is a list of view names. It is only required on the scope view.
recordId: this is a list of view names. It is only required on the scope view.

Then each message could default additional options. Here is the list of available messages:

Scope Name Parameters

global

reload

Name Type Required Default Description

goToDefaultView

boolean

false

If true when the app is reloaded, the user will be taken to the default view (the view displayed when the app is loaded after login). Otherwise current page will be reloaded.

global

navigate

Name	Type	Required	Default	Description
view	`string`	yes		ID or name of the view to navigate to.
recordId	`string`	no		ID of the record. When this field is set the app navigates to the detail read-only view of the record.
viewType	`string`	no	readOnly	In case of grid or workflow views define the view type to redirect. Possible values `edit` or `create`.
filters	`object`	no		In case of grid or workflow views define some view filters to be applied. This filter example apply 2 filters for the view: `{ name: 'ACME', address.state: 'New' }`
parameters	`object`	no		In case of custom views you can define some view parameters to be applied. Those parameters are transformed into URL query parameters. For example, the following parameters: `{ name: 'ACME', status: 'New' }` Are going to be transformed to the following URL query parameters: `?name=ACME&status=New`

global

openExternalLink

Name Type Required Default Description

url

string

yes

External URL to open.

newTab

boolean

true

If true external URL is opened in a new tab of the browser. Otherwise the URL will be opened in same tab.

global

historyBack

Name	Type	Required	Default	Description

global

showMessage

Name	Type	Required	Default	Description
title	`string`	yes		The title to be shown on message.
message	`string`	yes		The message content to be shown. It supports some basic HTML tags.
type	`string`	no	info	Defines the style for the message. Possible values are `info`, `success`, `warning` or `error`.
keepVisible	`boolean`	no	false	If true the message won’t be closed automatically and the user has to close it manually.

global

downloadFile

Name Type Required Default Description

fileId

string

yes

The ID of the file to download.

global

addBackgroundJob

Name Type Required Default Description

jobId

string

yes

The ID of the background job in charge of executing.

global

startTask

Name Type Required Default Description

taskId

string

yes

The ID of the task to be displayed on tasks menu in the top-right.

taskTitle

string

yes

The message to be displayed on tasks menu in the top-right.

taskMessage

string

The compliment message to be sent as subtitle on tasks menu in the top-right.

global

updateTask

Name	Type	Required	Description
taskId	`string`	yes	The ID of the task to be updated on tasks menu in the top-right.
taskTitle	`string`	no	The message to be updated on tasks menu in the top-right.
taskMessage	`string`	no	The compliment message to be sent as subtitle on tasks menu in the top-right.
taskStatus	`string`	no	The status of the tasks. Can be updated to running, success or error. At the beginning the status is running.

view

recordChanged

Name Type Required Default Description

recordId

string

The id of the record that has been changed.

views

object

yes

The list of view names that will be notified by the event. The view types that can process this event are: grid, card, calendar and read only views.

view

recordCreated

Name Type Required Default Description

recordId

string

The id of the record that has been created.

views

object

yes

The list of view names that will be notified by the event. The view types that can process this event are: grid, calendar and card views.

view

recordDeleted

Name Type Required Default Description

recordId

string

The id of the record that has been deleted.

views

object

yes

The list of view names that will be notified by the event. The view types that can process this event are: grid, calendar and card views.

view

refresh

Name Type Required Default Description

views

object

yes

The list of view names that will be refreshed. The view types that can process this event are: grid, calendar and card views.

widgetContainers

object

In case to dashbaord view you can send the array a list to containers to be refresh. This can be an array of string or can be specify an object with container name and query parameters. Check widgets documentation for more information.

plugin:pluginName

anyEvent

Name	Type	Required	Default	Description

action

anyEvent

Name	Type	Required	Description
entity	`string`	yes	ID or name of the entity the action belongs too.
recordId	`string`	no	The ID of the record the action will be executed over. This is optional in case it is a global action.
recordIds	`object`	no	The IDs array of the record the action will be executed over. This is optional in case it is a global action.
actionView	`string`	no	Name or ID of the action view.
action	`string`	no	If actionView is not provided, you can send only action with the name or ID of the action and the default view will be used.
success	`function`	no	Callback when the action is executed successfully.
error	`function`	no	Callback when there is an error executing the action.
canceled	`function`	no	Callback when the action execution is canceled.

sendMessage(message)

Allows to send a message to the UI. This message is a command that the UI will follow. For example it could be to navigate to another view, reload the current view, show a message, etc.

Please check the available messages here.

Parameters

Name Type Required Default Description

Name	Type	Required	Default	Description
message	`object`	yes		This is the message to send to the UI. You must indicate the `scope` and `name`. Other fields depends on the message. For example: `{ scope: 'global', name: 'reload', goToDefaultView: true }`

message

object

yes

This is the message to send to the UI. You must indicate the scope and name. Other fields depends on the message. For example:

{
  scope: 'global',
  name: 'reload',
  goToDefaultView: true
}

Exceptions

badRequest

If the message is does not exist or there are validation errors.

Samples

// reload current page

sys.ui.sendMessage({
  scope: 'global',
  name: 'reload',
  target: 'caller'
});

// reload and go to default view

sys.ui.sendMessage({
  scope: 'global',
  name: 'reload',
  goToDefaultView: true,
  target: 'caller'
});

// send a custom message

sys.ui.sendMessage({
  scope: 'global',
  name: 'showMessage',
  target: 'users',
  targetUsers: ['id1', 'id2', 'user@test.com'],
  title: 'Heads up!',
  message: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor.
    Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.',
  type: 'warning',
  keepVisible: true
});

// start downloading a file

sys.ui.sendMessage({
  scope: 'global',
  name: 'downloadFile',
  target: 'caller',
  fileId: record.field('file').id()
});

// send a notification

sys.ui.sendMessage({
  scope: 'global',
  name: 'showMessage',
  target: 'allUsers',
  title: 'title message',
  message: 'body message here...'
});

// Notify to all users that are currently on views `contacts` and `contactsReadOnly` that the record `57fd2d65e4b0ce322b0c8665` has been updated

sys.ui.sendMessage({
  scope: 'view',
  name: 'recordChanged',
  target: 'allUsers',
  views: ['contacts','contactsReadOnly'],
  recordId: '57fd2d65e4b0ce322b0c8665'
});

// Refresh view `contacts` to all users that are currently on that view

sys.ui.sendMessage({
  scope: 'view',
  name: 'refresh',
  target: 'allUsers',
  views: ['contacts']
});

// Notify to some users that are currently on view `tasksCards` that a record has been created

var record = sys.data.createRecord('tasks');// create an empty record of entity task
record.field('status').val('NEW');// filling the new necord with the corresponding field values...
record.field('description').val('Example created on script');
record.field('title').val('New task created from script');
record.field('area').val({id:"5506fc3cc2eee3b1a7025bff"});
record.field('project').val({id: "5506fc44c2eee3b1a7026959", label: "Point-to-point link"});
record = sys.data.save(record);// saving the created record
sys.ui.sendMessage({
  scope: 'view',
  views: ['tasksCards'],
  target: 'users',
  targetUsers: ['id1', 'id2', 'user@test.com'],
  name: 'recordCreated',
  recordId: record.id()
});

// Notify to all users that are currently on view `contacts` that the record `57fd2d65e4b0ce322b0c8665` has been deleted

sys.ui.sendMessage({
  scope: 'view',
  name: 'recordDeleted',
  target: 'allUsers',
  views: ['contacts'],
  recordId: '57fd2d65e4b0ce322b0c8665'
});

// dispatch `event1` in `sample` plugin

sys.ui.sendMessage({
  scope: 'plugin:sample',
  name: 'event1',
  companyId: record.id(),
  callbacks: {
    callback1: function(originalMessage, callbackData) {
      sys.logs.debug("Here is the original message for callback 1");
      sys.logs.debug(JSON.stringify(originalMessage));
      sys.logs.debug("Here is the callback data for callback 1");
      sys.logs.debug(JSON.stringify(callbackData));
    },
    callback2: function(originalMessage, callbackData) {
      //do something
    }
  }
});

// Send UI message in order to trigger an action from server side so the user can enter the parameters and execute it.

sys.ui.sendMessage({
  scope: 'action',
  entity: 'myCompany',
  target: 'allUsers',
  recordIds: ['5be99071b10c3e09893300d2', '5be99082b10c3e09893300e2'],
  action: 'setCompanyType',
  success: function() {
    sys.logs.debug("> Success!");
  },
  error: function() {
    sys.logs.debug("> ERROR");
  },
  canceled: function() {
    sys.logs.debug("> Canceled...");
  }
});