OpenPlatform / 03. Client-side library
Updated: 14. October 2019
Author: Peter Širka

03. Client-side library

Professional Support Chat with contributors

OpenPlatform offers a small client-side library called openplatform.js. The application can obtain user/meta-data from OpenPlatform and it supports another features for OpenPlatform manipulation.


Topics


Initialization

The code below describes OpenPlatform initialization in your web application. OPENPLATFORM and OP are global variables defined in window scope.

<script src="https://cdn.totaljs.com/openplatform.min.js"></script>
<script>

    OP.init(function(err, response, redirectTimeout) {

        if (err) {
            document.body.innerHTML = '401: Unauthorized';
            return;
        }

       // response === meta-data
        OP.notify('Hello world!');
    });

</script>

Methods

  • OP.init(callback(err, response, redirectTimeout)) - initializes OpenPlatform
  • OP.loading(visible, [sleep]) - toggles preloading (animation)
  • OP.meta(callback(err, response)) - reads meta data again
  • OP.play(url) - plays a sound, url can be beep, success, alert, fail, confirm, done, drum, badges, notifications, message or phone
  • OP.stop(url) - stops the playing sound
  • OP.maximize() - maximizes this application in OpenPlatform
  • OP.minimize() - minimizes this application in OpenPlatform
  • OP.restart() - restarts this application
  • OP.open(appid, [data]) - opens another application
  • OP.close() - closes/kills this running application
  • OP.notify([type], body, [custom_data]) - sends a push notification
  • OP.confirm(msg, buttons_arr, callback(button_index)) shows a confirm message
  • OP.confirm2(msg, buttons_str, callback) shows a confirm message, the callback is executed when the user clicks on the first button
  • OP.message(msg, [type], [button_label]) - shows a message box, types: success (default) and warning
  • OP.success(message, [button_label]) is a alias for OP.snackbar()
  • OP.warning(message, [button_label]) is a alias for OP.snackbar()
  • OP.snackbar(msg, [type], [button_label]) - shows a snackbar, types: success (default), warning and waiting.
  • OP.focus() - focuses the current app
  • OP.badge([everytime]) - shows a badge in the app icon
  • OP.log(msg) - appends a log on the server-side
  • OP.mail(email, subject, html_body, [type(html|plain)]) - sends an email
  • OP.share(app/appid/app_name, type, body, [silent]) shares data in another app
  • OP.progress(percentage) - shows a progress bar if the percentage > 0 and < 100
  • OP.help(array_wiki) Opens a WIKI, array in the form: [{ name: 'Topic', body: 'Markdown' }] or MARKDOWN_BODY
  • OP.changelog(array_wiki) Opens a WIKI with changelog, array in the form: [{ name: 'Topic', body: 'Markdown' }] or MARKDOWN_BODY
  • OP.appearance() - creates CSS automatically on client-side, read more here
  • OP.config(obj) - can write configurationwrite
  • OP.config(callback(obj, err)) - can read configuration read
  • OP.shake([if_is_not_focused]) - performs a shake of windows
  • OP.success2(message, [show]) - appends a message onto console
  • OP.warning2(message, [show]) - appends a message onto console
  • OP.error2(message, [show]) - appends a message onto console
  • OP.info2(message, [show]) - appends a message onto console
  • OP.options(function(items_arr), function(selected)) - +v4 can append new j-Menu items to window options
  • OP.titlesuccess(message) - shows a success message in a title bar for 1 second
  • OP.titlewarning(message) - shows a warning message in a title bar for 1 second
  • OP.done(message, [callback]) - Can process a callback with success or warning message + callback (optional) is executed when the response doesn't contain any error
  • OP.link(path, data) - generates a public link to OpenPlatform app, it returns {String}
// OPENPLATFORM.notify([type], body, [url]);
// "type" {Number} 0 - info, 1 - success, 2 - error
// "body" {String}
// "url" {String} can be relative

// Examples:
OP.notify(0, 'Info');
OP.notify(1, 'Success', '/orders/101210/');
OP.notify(2, 'Error/Warning', '/reports/');

OP.confirm('Are you sure you want to remove selected order?', ['Yes', 'Cancel'], function(index) {
   // index === Button index, 0 = yes, 1 = cancel
   console.log(index); 
});

OP.confirm2('Are you sure you want to remove selected order?', ['Yes', 'Cancel'], function() {
    // YES BUTTON HAS BEEN PRESSED
});

// v4+ Method OP.done() automatically handles AJAX responses.
AJAX('....', OP.done('The item has been saved successfully', function() {
    // DONE, successfully
    // Errors are handled automatically and the callback isn't executed if the method processes error
}));

Sharing data between apps

OP.share() shares data between apps via client-side messaging.

OP.share('calendar', 'refresh', 'YOUR_DATA');             // app "calendar" will be open
OP.share('calendar', 'refresh', 'YOUR_DATA', 'silent');   // app "calendar" will be open minimized
OP.share('calendar', 'refresh', 'YOUR_DATA', 'open');     // app "calendar" must be open

Extending of window options

Window Options is supported in +v4.

OP.options(function(items) {
    items.push({ name: 'Home', icon: 'home' });
    items.push({ name: 'Settings', icon: 'cogs' });
}, function(selected) {
    console.log('DONE', selected);
});

Print

Printing is supported in +v4.

OP.on('print', function() {
    console.log('User wants to print the content of the window');
    window.print();
});

Events

OP.on('maximize', function() {
    // App is maximized
});

OP.on('minimize', function() {
    // App is minimized
});

OP.on('close', function() {
    // App is closed
});

// Is executed when the user will click on the notification
OP.on('notify', function(data) {

    // A raw data from the notification
    // {String/Number/Object}
    data;
     
});

// +v4
OP.on('custom', function(data) {

    // Triggered when OpenPlatform sends a custom data
    // It's targeted for special operations or customized OpenPlatform

    // @data {Object}
    
    // Sending from main OpenPlatform application:
    // OpenPlatform sends this custom data to all open iframes
    // EMIT('custom', { something });
});

// Is executed when the user will click on a question mark icon in title bar
// +v4
OP.on('help', function() {
    var wiki = [];
    wiki.push({ name: 'Welcome', body: 'YOUR MARKDOWN '});
    wiki.push({ name: 'Settings', body: 'YOUR MARKDOWN '});
    wiki.push({ name: 'FAQ', body: 'YOUR MARKDOWN '});
    OP.help(wiki);
});

// Is executed when the user has another version as the current version
// +v4
OP.on('changelog', function(userversion) {
    var body = '# New features\nThis version contains a lot of new features like ...';
    OP.changelog(body);
});

// Is executed when the app shares some data to this app
OP.on('share', function(data) {
    // Some app wants to share some data

    // {String} sender/app ID
    data.app;
    
    // Type of message
    // {String/Number}
    data.type;
    
    // Message body/data
    // {Object}
    data.body;
    
    // {Date}
    data.datecreated;    

    // You can send a data back via this method:
    data.share(type, body);
   
});

// Is executed when the user will change appearance
OP.on('appearance', function(data) {

    data.colorscheme; // {String} Contains HEX color
    data.background;  // {String} Contains a link to background image of OP
    data.darkmode;    // {Boolean} true/false 
 
});

// Is executed when the user will click on the public link
// +v4
OP.on('link', function(path, data) {
    // @path {String}
    // @data {Object}
});

// Is executed when the OpenPlatform performs SENDCOMMAND(type, data) method
// +v4
OP.on('command', function(type, data) {
    // Sends a command back to OpenPlatform
    // OP.command(type, body)
    OP.command('answer', { processed: true });
});

Appearance

Method OP.appearance() creates styles (CSS) automatically on client-side.

Supported global CSS classes:

  • oplight in <body element determines light mode
  • opdark in <body element determines dark mode
  • opbg contains a theme color for background
  • opfg contains a theme color for color (foreground color)
  • opborder contains a theme color for border-color
  • opbody in <body element contains a background color (#FFFFFF - light mode, #202020 - dark mode)

Supported global JS variables:

OPCOLOR;
// {String}
// contains a theme color (hex)

OPDARKMODE;
// {Boolean}
// contains "true" if the user uses dark mode

OpenPlatform client-side library supports great mechanism for sharing data between apps. It's very easy, just follow the example below:

APP 1:

<a href="openplatform://APP_NAME_OR_APP_ID?key1=value&key2=value&key3=value">SHOW APP</a>

APP 2:

OP.on('share', function(data) {

    if (data.type === 'link') {
        // LINK
        var body = data.body;
        console.log(body);
        // body.key1
        // body.key2
        // body.key3
        
        // Do you want to send something back to the sender?
        // OPTIONAL
        data.share('YOUR_TYPE_CAN_BE_link', { custom: 'data_object' });
    }
    
});