The official Enplug JavaScript SDK for the dashboard/control interface of apps built for Enplug displays.
- CDN:
<script src="http://cdn.enplug.net/libs/dashboard-sdk/3.0.0/sdk.min.js"></script>
- Bower:
bower install enplug-dashboard-sdk --save-dev
- NPM:
bower install enplug-dashboard-sdk --save-dev
When you build an app for Enplug displays, you also need to provide a web page that allows users to customize your app for their displays. This web page is loaded as an iFrame in the Enplug dashboard (dashboard.enplug.com). In order for your web page to communicate with and control the dashboard, you should use this SDK.
All SDK methods are asynchronous RPC calls. If you're loading data, the data will be provided via the onSuccess
callback that every method provides. There is also an onError
callback for you to handle errors.
The SDK is split into two APIs:
enplug.account
: Used for loading and modifying a user's account settings and app config.
enplug.dashboard
: Provides convenient access to UI components:
- Loading indicator (with loading, success and error states)
- Confirm box with custom text
- Confirm unsaved changes box
- Change the page header title and buttons
Jump to the API Documentation to read more.
Set enplug.debug = true;
for the SDK to log most actions to debug. You'll see messages like:
[Enplug SDK] Calling method: [MethodCall object]
The JavaScript SDK comes with a built-in AngularJS plugin. If you load the SDK in a project that has already loaded Angular, the plugin will automatically be initialized. The Angular plugin provides two services for working with the Enplug SDK, and returns promises instead of requiring the use of callbacks.
To use the plugin, first include the enplug.sdk
module in your Angular app's dependencies:
angular.module('myApp', ['enplug.sdk']);
Then, the $enplugAccount
and $enplugDashboard
are available in your app. All method calls will return promises you can chain to, and still accept callbacks if you prefer.
angular.module('myApp').controller('MyController', function ($enplugAccount, $enplugDashboard) {
'use strict';
$enplugAccount.getAssets().then(function (assets) {
$scope.assets = assets;
});
$enplugDashboard.openConfirm({ title: 'A title', text: 'A longer description' }).then(function () {
// user confirmed
}, function () {
// user cancelled
});
});
All methods available on enplug.account
are also available on $enplugAccount
, and all methods available on enplug.dashboard
are available on $enplugDashboard
.
All methods take a success and an error callback as the final two parameters. For methods which load data, the success callback will be passed the data as the first and only parameter. The error callback is given the reason (string
) an SDK method failed.
All methods return the API call ID, which can be used to find the API call in the pending calls stack during troubleshooting:
enplug.account.transport.pendingCalls[callId]; // stores the API call and its details
Example:
enplug.account.getAccount(function (data) {
var accountId = data.accountId;
}, function (reason) {
console.error('There was an error:', reason);
});
Loads all information for the current user.
Callback receives:
{
id: 'string', // Current display group ID
type: 'string', // User account type
appInstanceId: 'string', // ID of current app when turned on
accountId: 'string' // Current user's account ID
}
Loads information for the currently selected display group.
Callback receives:
{
language: 'string', // e.g. English, Russian, French
orientation: 'string', // Landscape or Portrait
timezone: 'string',
}
Loads an array of assets for the current app instance.
Callback receives:
[{
Created: 'string', // WCF date
Id: 'string', // Asset ID
Name: 'string', // Asset Name
Value: {} // Value object provided when created
}]
Creates an asset under the current app instance.
Updates an asset under the current app instance.
- id: string ID of the asset to be updated.
- value: object to update the asset's value to
Removes an asset under the current app instance.
Creates one or more assets under the current app instance.
assets: array
[{
AppInstanceId: 'string', // optional, defaults to current app instance
AssetName: 'string', // required
AssetValue: {} // required
}]
Updates one or more assets under the current app instance.
assets: array
[{
AppInstanceId: 'string', // optional, defaults to current app instance
AssetId: 'string', // required
AssetValue: {} // required
}]
Removes one or more assets.
assets: array
[{
AppInstanceId: 'string', // required
AssetId: 'string' // required
}]
or, to remove multiple assets for the current app instance, provide an array of asset ID strings:
['id1', 'id2', 'id3']
Loads an array of app instances including assets that are available for the current app on a chain account.
All enplug.dashboard
methods also accept success and error callbacks which acknowledge when a certain UI control has been triggered, but they aren't usually needed so they're left out of the documentation except in cases where they're used.
Sets the last part of the title bar breadcrumb. Set an empty title '' to clear the title.
Sets the primary action buttons for a page in the titlebar. Accepts either a single button object, or an array of buttons. Each button must have a button.action callback. button:
{
text: 'button text',
class: 'class-name',
action: function () {}, // callback when clicked
disabled: true, // boolean true/false
}
Controls the loading state for the entire page. Every application starts off in loading state, and must set pageLoading(false) to notify the dashboard that it has successfully loaded.
Use enplug.dashboard.isLoading()
to synchronously check current loading state.
Synchronously returns the current loading state.
Note: The loading state is updated asynchronously when this sender receives an acknowledgement of successful SDK call from the dashboard after using .pageLoading(bool);
Puts the page into error state.
Puts the page into 404 state.
Turns on the progress indicator, typically used during asynchronous actions.
Note that the progress indicator will continue until a call is made to the errorIndicator or successIndicator APIs.
Shows the success indicator. Should only be used after a call has been made to .loadingIndicator().
Shows the error indicator. Should only be used after a call has been made to .loadingIndicator().
Opens a confirm window with Yes/No buttons and configurable messages. If the user clicks the Confirm button, the success callback is called. Otherwise the error callback is called.
Available options:
{
title: 'string', // required
text: 'string', // required
confirmText: 'string', // optional, defaults to "Confirm"
cancelText: 'string', // optional, defaults to "Cancel"
confirmClass: 'string', // optional, defaults to primary button. Other option: 'btn-danger'
}
Opens a confirm window asking the user to confirm their unsaved changes. If the user clicks the confirm button, the success callback is called. Otherwise the error callback is called.
Opens an upload interface for the user to select a file to upload. The options parameter is currently unused. The success callback receives the newly uploaded and encoded file wrapped in an array:
[{
url: 'string', // publicly accessible URL for the encoded file
filename: 'string', // filename of the uploaded file
mimetype: 'string', // mimetype of the uploaded file
size: 1000 // the size of the uploaded file in bytes, if available
}]
Please send any issues to support@enplug.com.
Clone the repository, then install the dependencies:
npm install
bower install
grunt build
To compile files as they're changed, run:
grunt watch
After installing the dependencies, run:
grunt test
This SDK is distributed under the MIT License, see LICENSE for more information.