Extending the Axeda Platform UI - Custom Tabs and Modules

    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

    Ext UI Mod CO

    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.

    Custom App

    Create the Extended UI Object

    Option 1: Using the Axeda Applications Console

    Navigate to Configuration > New > Extended UI Module

    Extended UI Mobule Object

    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.

    Extended UI Module App

    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.

    Model Preferences Link

    Click Asset Dashboard Layout

    Dashboard Link

    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.

    Arrowing

    Click Submit and navigate to an Asset Dashboard to see the module displayed.

    Asset Dashboard

    Now you have an Extended UI Module with your custom content.

    Custom Tabs

    Upload a custom application as a custom tab.

    Custom Tab

    And there you have it.

    Tab

    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