Skip to content

MindSphere OS Bar – Getting Started

Version Update

A new version (v4) of the MindSphere OS Bar with new features is available since 15.11.2018.
Be aware that the prefix for HTML selectors, such as classes or IDs, has been changed from _msb to _mdsp!

MindSphere OS Bar Integration

The MindSphere OS Bar is integrated by adding a JavaScript snippet and an HTML fragment to your website / web app. The HTML fragment ensures that the layout of MindSphere OS Bar and app can be set up automatically. If your app is served through e.g. an index.html file, you have to integrate the MindSphere OS Bar there.

Add the following snippet in your JavaScript code:

1
2
3
4
5
6
...
_mdsp.init({
    title: "MindSphere OS Bar Demo",
    appId: "_mdspcontent"
});
...

The app markup has to be wrapped into a div element with ID _mdspcontent. If required, this ID can be customized. The MindSphere OS Bar JavaScript file has to be referenced and initialized:

1
2
3
4
5
<div id="_mdspcontent">
  <!-- Main app markup goes here -->
</div>

<script src="https://static.eu1.mindsphere.io/osbar/v4/js/main.min.js"></script>

Attention

  • The MindSphere OS Bar does not set a valid viewport for your HTML/app.
    If no viewport is defined, neither the MindSphere OS Bar nor your app will be responsive.
  • The MindSphere OS Bar does not provide a promise polyfill by default.
    If your framework does not provide a polyfill, configure the MindSphere OS Bar to include polyfill to make sure the app works properly in IE11.
  • The height of the MindSphere OS Bar might change on smaller screens due to responsive behaviour.
    Use the CSS positioning attributes static, relative, or absolute to make sure that the height of the MindSphere OS Bar won't affect your app.
    Avoid the usage of position:fixed in your app since this might lead to unexpected results.

Info

MindSphere currently enforces certain Content-Security-Headers (CSP), which prevents the execution of inlined JavaScript.

Configuration Options

The MindSphere OS Bar is configurable and provides options to show your tenant-specific legal information.

Parameter Description Default
title Specifies the title of the app. If not specified, and no displayName parameter is defined, no title is displayed. none
appId If provided, the script looks for an element with this parameter as ID attribute. This allows for the HTML markup to look different to the default markup described above. If no appropriate container element can be found, the MindSphere OS Bar is not populated.
Note: The MindSphere OS Bar is populated on the same level, but above the element with the matching ID attribute.
Important: If you customize your appId, you have to set/add the _mdspcontent class on the container element so that the required styles can be set automatically.
"_mdspcontent"
initialize If this parameter is set as true, the script does not wait for a DomContentLoaded event to start the initialization. It immediately searches the app containing element and creates the MindSphere OS Bar markup above. The DOM must already have been loaded and initialized. true
appInfoPath Specifies a custom path to the app-info.json, if it is not located in the root directory of the app. If the file is not found, the drop-down menu for app information only shows the operator-specific links, if available. Otherwise, it is not available. "/app-info.json"
polyfills An object can be specified which is used to toggle the loading of different polyfills. refer to Polyfills

App Information

The following app information can be displayed in the MindSphere OS Bar and is configured in the app-info.json file:

Parameter Description
displayName Specifies the name of the app to be displayed in the MindSphere OS Bar. This name is overridden, if the title parameter is set in the _mdsp.init(...) call.
appVersion Specifies the version of the app according to semantic versioning, which is displayed at the top of the app information.
appCopyright Specifies the app creator's name (i.e., company name) and the year of publication.
links Specifies links to be displayed at the bottom of the app information. Available link types are WWW, MAIL, PHONE.

Links

Links can be provided in multiple languages using language codes according to ISO 639-1. The default language is usually English. If a browser is set to a language for which links are defined, the respective links are displayed in the MindSphere OS Bar. Otherwise, the default language is used.
Apps should at least provide links to their documentation and the third party software they use. By convention, those links should be called "Third-Party Software" and "Documentation" (in German: "Third-Party Software" and "Dokumentation").

This is an example of the app-info.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "displayName": "Sample App",
  "appVersion": "0.0.0",
  "appCopyright": "© Siemens 2018",
  "links": {
    "default": [
      {
        "type": "WWW",
        "name": "DEV Information",
        "value": "http://sie.ag/abc"
      }
    ],
    "de": [
      {
        "type": "WWW",
        "name": "Entwicklungs-Information",
        "value": "http://sie.ag/abc"
      }
    ]
  }
}

The appInfoPath configuration parameter has to be added to the JavaScript snippet as follows:

1
2
3
4
5
6
7
...
_mdsp.init({
    title: "MindSphere OS Bar Demo",
    appId: "_mdspcontent",
    appInfoPath: "/assets/json/myfile.json"
});
...

Polyfills

The MindSphere OS Bar implements multiple polyfills. The polyfills configuration parameter defines, if a polyfill shall be enabled or disabled, because it conflicts with the used framework. The following polyfills are currently available for the MindSphere OS Bar:

Name Requirement Default
es5adapter Required for newest versions of Chrome and Firefox since they deprecated an older draft of the custom-elements API. true
promise Required for IE11 if no other polyfill for the promise API is available. false
webcomponents Required for browsers which do not provide the custom-elements API. true
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
...
_mdsp.init({
    ...
    polyfills: {
        es5adapter: true,
        promise: false,
        webcomponents: true
    },
    ...
});
...

Disabling polyfills

If a polyfill is disabled, a substitute must be loaded before initializing the MindSphere OS Bar to ensure its proper functionality.

Dynamic Insertion

The following code block shows an example for dynamic insertion of the MindSphere OS Bar:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
...
(function(d, script) {
    script = d.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.onload = function(){
        _mdsp.init({
            title: "MindSphere OS Bar Demo width dynamic initialization",
            initialize: true
        });
    };
    script.src = 'https://static.eu1.mindsphere.io/osbar/v4/js/main.min.js';
    d.getElementsByTagName('head')[0].appendChild(script);
}(document));
...

Initialize after loading script

Make sure the initialization is only called after the script finished loading. Otherwise, the initialization function will still be unknown and the console will throw an error.

Tip

If the population / generation of the MindSphere OS Bar fails, it might be for one of the following reasons:

  • The CDN-hosted script and assets are unavailable.
  • The appId parameter is supplied, but no matching element is present in the DOM tree.
  • No appId parameter is supplied and no element with default attribute is present in DOM tree.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.