Requirements: Axeda 6.1.6+
The Axeda Applications User Interface can be extended to accommodate varying degrees of customization. This ability to customize the base product enables repurposing the Axeda Applications User Interface to serve a specific audience.
What this tutorial covers
This tutorial discusses three ways to extend the Axeda Applications User Interface, which can be achieved via the following features:
- Customizing the Look and Feel - Use your own custom stylesheet to replace the default page styles, even on a per-user basis
- Extended UI Modules - Insert your own Extended UI Module into the Service > Asset Dashboard
- Custom Tab - Create a custom tab that loads content from a custom M2M application
Customizing the Look and Feel of the Axeda Applications User Interface
You can add style changes into a user.css file which you then upload like any other custom application, via the Administration > Extensions tab as a zip archive. Make sure to adhere to the expected directory structure and follow the naming convention for the zip archive.
- Images - store image files in a directory called <userName>/images
- Styles - store user.css and any style sheet(s) that it imports in a directory called <userName>/styles
- Documentation - store documentation files in a directory called <userName>/doc.
The naming convention is to name the archive by the username of the user who should be able to see the changes, i.e. jsmith is the username so jsmith.zip is the archive name.
For step-by-step instructions for customizing the UI, Axeda customers may refer to http://<<yourdomain>>.axeda.com/help/en/stylesheets_for_user_branding.htm andhttp://<<yourdomain>>.axeda.com/help/en/upload_user_branding.htm .
Extended UI Modules
Extended UI Modules can be added to the Asset Dashboard to provide custom content alongside the default modules. The modules can contain the output of a custom object or a custom application, all within the context of the particular asset being viewed.
Create the Extended UI Content
Option 1: an Extended UI Type Custom Object
Navigate to Configuration > New > Custom Object
This Custom Object should output HTML with any Javascript and/or CSS styling embedded inline. Parameters may be defined here and made available to the script as "parameters.label".
Example:
def iframehtml = """<html>
<head>
<script type='text/javascript' src='https://www.google.com/jsapi'></script>
<script type='text/javascript'>
google.load('visualization', '1', {packages:['gauge']});
google.setOnLoadCallback(drawChart);
function drawChart() {
var data = new google.visualization.DataTable();
data.addColumn('string', 'Label');
data.addColumn('number', 'Value');
data.addRows([
['$parameters.label', $parameters.value]
]);
var options = {
redFrom: 90, redTo: 100,
yellowFrom:75, yellowTo: 90,
minorTicks: 5
};
var chart = new google.visualization.Gauge(document.getElementById('chart_div'));
chart.draw(data, options);
}
</script>
</head>
<body style="background: white;">
<div id='chart_div'></div>
</body>
</html>
"""
return ['Content-Type': 'text/html', 'Content': iframehtml.toString()]
Option 2: A Custom Application
Create a zip file that contains an index html file at the root of the directory, any stylesheets, scripts and images you prefer and upload the zip as a Custom Application (see the example zip file included at the end of this article).
Navigate to Administration > Extensions . Enter the information for the zip file and upload.
Create the Extended UI Object
Option 1: Using the Axeda Applications Console
Navigate to Configuration > New > Extended UI Module
Note that the parameters are entered in URI format myvalue=mykey&othervalue=otherkey
If Content Source is set to Custom Application rather than Custom Object, the Custom Applications will become available as the Extended UI Module content.
Option 2: Use Axeda Artisan
Check out Developing with Axeda Artisan in order to make use of this method. Add the Extended UI Module to the apc-metadata.xml and it will be created for you automatically on Maven upload. Note that Artisan does not support Model Preferences, so you will still have to add the module through the Axeda UI as described below.
<extendedUIModule>
<!-- you can create the module here, but you still have to use the Axeda Console to apply it to the model where the module should show up -->
<title>extendedUI_name</title>
<height>180</height>
<source>
<type>CUSTOM_APPLICATION</type>
<name>customapp_name</name>
</source>
</extendedUIModule>
Add the Extended UI Module to the Model Preferences
Navigate to Configuration > View > Model and click Preferences under UI Configuration next to the model that should display the Extended UI Module for its assets.
Click Asset Dashboard Layout
Select the Extended UI Module from the left and click the arrow to add it to the desired column. The asterisks indicate Extended UI Modules, as opposed to default modules.
Click Submit and navigate to an Asset Dashboard to see the module displayed.
Now you have an Extended UI Module with your custom content.
Custom Tabs
Upload a custom application as a custom tab.
And there you have it.
For Artisan developers, to enable a custom application as a custom tab, insert the following into the apc-metadata.xml:
<application>
<description>string</description>
<applicationId>string</applicationId>
<indexFile>string</indexFile>
<zipFile>relative path from apc-metadata.xml to the zip file containing the application files</zipFile>
<customTab>
<tabPrivilegeName>the privilege name required for the tab to be shown</tabPrivilegeName>
<afterTab>the name of the tab after which to place this tab</afterTab>
<showFooter>[true|false]</showFooter>
<tabNames>
<label>
<locale>the i18n locale (for example en_US or ja_JP)</locale>
<name>the name to be displayed for the locale</name>
</label>
</tabNames>
</customTab>
</application>
Authentication within Extended UI Components
When working with Custom Applications in custom tabs or modules, the user session ID is made available through a special variable that you can access from the landing page (such as index.html) only:
%%SESSIONID_TOKEN%%
This variable is substituted directly for the session id, which makes the authentication for viewing the Extended UI component appear seamless to the end user.
In order to make this ID available for AJAX calls, the index.html file should store the session ID as it is initializing. Additionally, index.html should instruct the browser not to cache the page, or the session ID may mistakenly be used to authenticate after it expires.
In index.html:
<html>
<head>
<title>My Custom App</title>
<META HTTP-EQUIV="CACHE-CONTROL" CONTENT="NO-CACHE">
<link media="screen" href="styles/axeda.css" rel="stylesheet" type="text/css"/>
<script src="scripts/jquery-1.9.0.min.js" type="text/javascript"></script>
<script type="text/javascript">
$(window).load(function () {
App.init(encodeURIComponent("%%SESSIONID_TOKEN%%"));
})
</script>
</head>
In App.js:
App.init = function (sessionID) {
// put initial processing here
storeSessionId( sessionID )
App.callScriptoWithStoredSessionID()
}
That's it! You can now customize the look and feel of the Axeda Applications Console, as well as add an Extended UI Module and a Custom Tab.
Further Reading
Common Questions
- I want to display my custom app on a custom tab. How should I manage authentication within my custom tab app?
Answer: Use Javascript to store the session ID injected as a variable into the index.html page, then use that to authenticate Scripto calls to the Axeda Platform.
- Are there example programs to get started?
Answer: There are several examples of Artisan projects to get started
- Axeda Sample Application: Populating A Web Page with Data Items
- An Axeda instance - https://<customerInstance>.axeda.com/artisan
