Explanation of custom views. Settings and API available for custom views.

Custom views allow to put a completely custom HTML page in your app. This is useful when you need to do something that isn’t supported for built-in view types.

These custom views will be displayed as an iframe in the main content area of your app. This means you are free to include any CSS and libraries you want without having to worry about conflicts with the app.

Custom views provides a Javascript API to make it easy to interact with the app to fetch information, perform operations and redirect to other views.

Keep in mind that in order to use the Javascript API it’s necessary to include jQuery on the view. This can be done by adding the following line on html header block:

<html>
<head>
...
<script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
...
</head>
...

In case you haven’t included jQuery you will see the following console warning on your browser: UI API won't be available because jQuery is not loaded

You can find different versions of jQuery here.

Label

This is a human-readable name of the view. You can use spaces, special characters and mix upper case and lower case letters.

This label will be displayed at the top of the grid view, so make sure you use something users will understand.

Name

This is the internal name of the view. It cannot hold special characters or spaces.

Usually you will use the name of the view in scripts and the REST API, so changing it might affect your app and you will need to make some manual adjustments.

Available REST API variables

The following variables are available in your custom view’s scripts and are needed to access the REST API of your app:

  • sys.ws.TOKEN: token needed to make calls to the REST API. It has to be sent in the token header.
  • sys.ws.API_URL: this is the URL to access the REST API of the app. Something like https://<app>.slingrs.io/<env>/runtime/api.

Keep in mind that it might take a few milliseconds for these variables to be set, so if your Javascript executes right after the view is loaded, these variables might be null.

In most cases you won’t need to use this variables directly as you probably use the utils provided for the REST API.

REST API utils

These are utilities to easily access the REST API of your app from script in the custom view. You can find more information about the REST API for the app here.

get(urlOrParameters, done, error)

Performs a GET operation to the given URL, sending the correct headers and doing the needed conversions.

Parameters

Name Type Required Default Description

urlOrParameters

string or object

yes

Can be either a simple string with the URL like this /data/companies or an object with parameters:

{
  url: '/data/companies',
  params: {state: 'active', _size: 100}
}

It is important to note that the URL is the path after /api. The base of the URL and headers are calculated automatically so you don’t need to worry about it.

Parameters will be encoded automatically.

done

function

no

A callback that will be called if the request succeed and will send one parameter with the result of the call. The REST API returns a JSON string, but this method will convert it to a Javascript object automatically.

Please check the REST API docs to see the response.

error

function

no

A callback that will be called if the request fails. An object will be sent as parameter with the error code and error message.

Please check the REST API docs to see the response.

Samples

// logs the label of the app

sys.ws.get('/data/companies', function(res) {
    console.log('Total companies: ' + res.total);
    res.items.forEach(function(company) {
        console.log('Company: ' + company.name);
    });
}, function(errorInfo) {
    console.log('There was an error getting companies. Code: ' + errorInfo.code + ', message: ' + errorInfo.message);
});

post(urlOrParameters, data, done, error)

Performs a POST operation to the given URL, sending the correct headers and doing the needed conversions.

Parameters

Name Type Required Default Description

urlOrParameters

string or object

yes

Can be either a simple string with the URL like this /data/companies or an object with parameters:

{
  url: '/data/companies'
}

It is important to note that the URL is the path after /api. The base of the URL and headers are calculated automatically so you don’t need to worry about it.

Parameters will be encoded automatically.

data

object

no

The body of the request. You can pass a Javascript object and it will be converted to JSON automatically.

done

function

no

A callback that will be called if the request succeed and will send one parameter with the result of the call. The REST API returns a JSON string, but this method will convert it to a Javascript object automatically.

Please check the REST API docs to see the response.

error

function

no

A callback that will be called if the request fails. An object will be sent as parameter with the error code and error message.

Please check the REST API docs to see the response.

Samples

// logs the label of the app

var company = {
    name: 'test company',
    state: 'active'
};
sys.ws.post('/data/companies', company, function(company) {
    console.log('Company created successfully: ' + JSON.stringify(company));
}, function(errorInfo) {
    console.log('Error creating company. Code: ' + errorInfo.code + ', message: ' + errorInfo.message);
});

put(urlOrParameters, data, done, error)

Performs a PUT operation to the given URL, sending the correct headers and doing the needed conversions.

Parameters

Name Type Required Default Description

urlOrParameters

string or object

yes

Can be either a simple string with the URL like this /data/companies or an object with parameters:

{
  url: '/data/companies/56e81f68e4b0001caf8837a4'
}

It is important to note that the URL is the path after /api. The base of the URL and headers are calculated automatically so you don’t need to worry about it.

Parameters will be encoded automatically.

data

object

no

The body of the request. You can pass a Javascript object and it will be converted to JSON automatically.

done

function

no

A callback that will be called if the request succeed and will send one parameter with the result of the call. The REST API returns a JSON string, but this method will convert it to a Javascript object automatically.

Please check the REST API docs to see the response.

error

function

no

A callback that will be called if the request fails. An object will be sent as parameter with the error code and error message.

Please check the REST API docs to see the response.

Samples

// logs the label of the app

sys.ws.put('/data/companies/' + company.id, {name: 'new name'}, function(company) {
    console.log('Company updated successfully: ' + JSON.stringify(company));
}, function(errorInfo) {
    console.log('Error updating company. Code: ' + errorInfo.code + ', message: ' + errorInfo.message);
});

delete(urlOrParameters, done, error)

Performs a DELETE operation to the given URL, sending the correct headers and doing the needed conversions.

Parameters

Name Type Required Default Description

urlOrParameters

string or object

yes

Can be either a simple string with the URL like this /data/companies or an object with parameters:

{
  url: '/data/companies/56e81f68e4b0001caf8837a4',
  params: {async: true}
}

It is important to note that the URL is the path after /api. The base of the URL and headers are calculated automatically so you don’t need to worry about it.

Parameters will be encoded automatically.

done

function

no

A callback that will be called if the request succeed and will send one parameter with the result of the call. The REST API returns a JSON string, but this method will convert it to a Javascript object automatically.

Please check the REST API docs to see the response.

error

function

no

A callback that will be called if the request fails. An object will be sent as parameter with the error code and error message.

Please check the REST API docs to see the response.

Samples

// logs the label of the app

sys.ws.del('/data/companies/' + company.id, function(company) {
    console.log('Company deleted successfully: ' + JSON.stringify(company));
}, function(errorInfo) {
    console.log('Error delting company. Code: ' + errorInfo.code + ', message: ' + errorInfo.message);
});

createRecord(entityName, data, done, error)

Uses the post method previously described to create a new record to a given entity and then informs back to the platform.

Parameters

Name Type Required Default Description

entityName

string

yes

The name of the entity where the new record will be created. This can be obtain from the context sent to the custom view after fully rendered.

data

object

no

The body of the request. You can pass a Javascript object and it will be converted to JSON automatically.

done

function

no

A callback that will be called if the request succeed and will send one parameter with the result of the call. The REST API returns a JSON string, but this method will convert it to a Javascript object automatically.

Please check the REST API docs to see the response.

error

function

no

A callback that will be called if the request fails. An object will be sent as parameter with the error code and error message.

Please check the REST API docs to see the response.

Samples

// creates a new record in an entity Contacts

var newRecord = {
    company: 'test company name',
    firstName: 'test first name',
    lastName: 'test last name',
    email: 'test email',
}
sys.ui.createRecord("contacts", newRecord, function (contact) {
     console.log('Contact created successfully: ' + JSON.stringify(contact));
}, function (errorInfo) {
    console.log('Error creating contact. Code: ' + errorInfo.code + ', message: ' + errorInfo.message);
})

updateRecord(entityName, recordId, data, done, error)

Uses the put method previously described to update a given record to a given entity and then informs back to the platform.

Parameters

Name Type Required Default Description

entityName

string

yes

The name of the entity where the new record will be created. This can be obtain from the context sent to the custom view after fully rendered.

recordId

string

yes

The id of the record that will be updated. This can be obtain from the context sent to the custom view after fully rendered.

data

object

no

The body of the request. You can pass a Javascript object and it will be converted to JSON automatically.

done

function

no

A callback that will be called if the request succeed and will send one parameter with the result of the call. The REST API returns a JSON string, but this method will convert it to a Javascript object automatically.

Please check the REST API docs to see the response.

error

function

no

A callback that will be called if the request fails. An object will be sent as parameter with the error code and error message.

Please check the REST API docs to see the response.

Samples

// updates a record of the entity Contacts

var newValues = {
    company: 'test company name',
    firstName: 'test first name',
    lastName: 'test last name',
    email: 'test email',
}
sys.ui.updateRecord("contacts", "5dbb1d5836e3bd27bd640ff3" ,newValues, function (contact) {
     console.log('Contact updated successfully: ' + JSON.stringify(contact));
}, function (errorInfo) {
    console.log('Error updating contact. Code: ' + errorInfo.code + ', message: ' + errorInfo.message);
})

goToView(viewIdOrName, params)

Allows to navigate to an app specific view.

Parameters

Name Type Required Default Description

viewIdOrName

string

yes

The view ID or name to navigate to.

params

object

no

Some views might accept additional parameters. For example, grid and workflow views accept a recordId parameter to go to the read only view of a record.

Samples

// goes to a grid view

sys.ui.goToView('companies');


// goes to the read only view of a record in a grid view

sys.ui.goToView('companies', {recordId: '5506fc43c2eee3b1a7026948'});

executeAction(entityNameOrId, actionNameOrId, recordIds, successCallback, errorCallback, canceledCallback)

Allows to execute a certain action from a custom view

Parameters

Name Type Required Default Description

entityNameOrId

string

yes

The name or ID of the entity.

actionNameOrId

string

yes

The name or ID of the action to execute.

recordIds

object[]

no

The ids of the registers on which the action will be executed. It can be an string with id or arrya of strings.

successCallback

function

yes

It runs after a successful execution of the action. Sends the result of the action as a parameter.

errorCallback

function

yes

It runs when the action fails.

canceledCallback

function

yes

It runs when the action is canceled.

Samples

// execute an action for employees

sys.ui.executeAction('employees', 'timeTrack', "xxxxx",
    function(result) {
       console.info("> success", result);
    },
    function(result) {
       console.info("> error", result);
    },
    function(result) {
       console.info("> canceled", result);
    });


// execute a global action

sys.ui.executeAction('sampleEntity', 'globalAction', null,
  function(result) {
     console.info("> success", result);
  },
  function(result) {
     console.info("> error", result);
  },
  function(result) {
     console.info("> canceled", result);
  });

Context API

Through these utilities you are able to access to the parameters sent by the service:

sys.ui.sendMessage({
    name: 'navigate',
    view: 'customViewId',
    parameters: {
        ...
    }
})

In the custom view code you can access to parameters by using the following utilities:

  • sys.context.PARAMS: parameters key-value object map available in the custom view context.
  • sys.context.getParam(paramName): this method is an utility to access to one specific parameter value.

Files

These are the files that compose the custom view. They are basically HTML, CSS and Javascript files.

However there is one special file that is created automatically: mainFile.html`. This is an HTML page and it is the main file that will be loaded when a user opens the custom view. It can not be removed or renamed and you are free to use any HTML tag, CSS or Javascript code you need in your view, or include other files as explained below.

This page will be displayed inside an iframe in the main content area of your application. This way there is no risk of conflicts with the rest of the app.

Besides the main file, you can also create more files to split the custom view in several pieces in order to keep things clean. They can be Javascript, CSS, or HTML files. Then it is possible to merge them in the main file of the custom view. For example let’s suppose you have the following files:

  • styles.css
  • utils.js
  • templates.html

You can merge them in the main file like this:

<html>
<head>
...
${styles.css}
${utils.js}
</head>
<body>
...
${templates.html}
</body>
</html>

CSS files will be inserted inside a <style>, while Javascript files will be wrapped with the <script> tag. This means you shouldn’t put those tags in the files. HTML fields are inserted exactly as they are in the file.

Permissions

Permissions allow to define which groups can access this view.

Permissions for a view can be handled right in the view definition, but it is just a different view of what you can configure in groups. It is oriented so you can easily configure permissions on the view for all existing groups.

For more information about permissions please refer to Groups.

Used as a CRUD Action

As a ReadOnly type view

You can select a custom view as a readOnly CRUD action view in a Grid View. If you select it, a context with some information will be passed as json through a message event. This event can be listened to by adding an event listener in the main file of the custom view. This way you are going to have the information set to be displayed in the custom view. Additionally, Refresh action button will also trigger a message event to inform the custom view about the refresh pressed. This way, the custom view could listen to this event and perform an action. This refresh event will also be trigger after executing other custom actions.

Sample of a listener in the custom view

// Logs the context and the event type

    window.addEventListener('message', function (event) {
       if(event.data.eventType){
         var eventType = event.data.eventType;
         sys.logs.info("EVENT: " + JSON.stringify(eventType));
       }else if(event.data.context){
         var context = event.data.context;
         sys.logs.info("CONTEXT: " + JSON.stringify(context));
       }
    });

As a Create type view

You can select a custom view as a create CRUD action view in a Grid View. if you select a Custom View, a context with some information will be passed as json through a message event. This event can be listened to by adding an event listener in the main file of the custom view. This way you are going to have the information set to be displayed in the custom view. Additionally Create action button will also trigger a message event to inform the custom view about the create button pressed. This way, the custom view could listen to this event and perform an action. This add event will also be trigger after executing other custom actions.

Sample of a listener set in a custom view in order to obtain some context information

    window.addEventListener('message', function (event) {
    //We wait for a message from the platform to let us know the Create Button has been pressed
        if (event.data.eventType) {
          if (event.data.eventType === 'add') {
    //This is a method we should implement to save the new data and then comunicate it back to the platform
             self.createRecord();
          }
    // Logs the context. This happened once the custom view is fully rendered
       }else if(event.data.context){
         var context = event.data.context;
         var entity = event.data.context.entity;
         sys.logs.info("CONTEXT: " + JSON.stringify(context));
       }
    });

Once you listen to the add event. We should implement some functionality. Custom views have an util method to create new records and then inform back to the platform. There is more information about it in the Custom View section.

Sample of an implementation of a createRecord() method

     self.createRecord = function () {
        console.log('creating new record from REST API');
     //Custom view method to create a record and inform back to the platform
        sys.ui.createRecord(entity.name, newRecord, function (recordCreated) {
            console.log("ON SUCCESS RECORD: " + JSON.stringify(recordCreated));
        }, function (error) {
            console.log("ON ERROR :" + JSON.stringify(error));
        })
    };

As an Edit type view

You can select a custom view as a create CRUD action view in a Grid View. If you select a Custom View, a context with some information will be passed as json through a message event. This event can be listened to by adding an event listener in the main file of the custom view. This way you are going to have the information set to be displayed in the custom view. Additionally Save action button will also trigger a message event to inform the custom view about the save button pressed. This way, the custom view could listen to this event and perform an action. This edit event will also be trigger after executing other custom actions.

Sample of a listener set in a custom view in order to obtain some context information

    window.addEventListener('message', function (event) {
    //We wait for a message from the platform to let us know the Save Button has been pressed
        if (event.data.eventType) {
          if (event.data.eventType === 'edit') {
    //This is a method we should implement to save the new data and then comunicate it back to the platform
             self.updateRecord();
          }
    // Logs the context. This happened once the custom view is fully rendered
       }else if(event.data.context){
         var context = event.data.context;
         var entity = event.data.context.entity;
         var contextRecord = event.data.context.record;
         sys.logs.info("CONTEXT: " + JSON.stringify(context));
       }
    });

Once you listen to the edit event. We should implement some functionality. Custom views have an util method to update records and then inform back to the platform. There is more information about it in the Custom View section.

Sample of an implementation of a updateRecord() method

     self.createRecord = function () {
        console.log('creating new record from REST API');
     //Custom view method to create a record and inform back to the platform
        sys.ui.createRecord(entity.name, newRecord, function (recordCreated) {
            console.log("ON SUCCESS RECORD: " + JSON.stringify(recordCreated));
        }, function (error) {
            console.log("ON ERROR :" + JSON.stringify(error));
        })
    };
Back to top