Getting started

Integration¶

The 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 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 OS Bar there.

Add the following snippet in your JavaScript code:

...
_mdsp.init({
    title: "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 OS Bar JavaScript file has to be referenced and initialized:

<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 OS Bar does not set a valid viewport for your HTML/app.
If no viewport is defined, neither the OS Bar nor your app will be responsive.
The OS Bar is written in ECMAScript 2015 and therefore not running in older browsers like Internet Explorer.
The height of the 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 OS Bar won't affect your app.
Avoid the usage of position:fixed in your app since this might lead to unexpected results.

Info¶

Insights Hub and Industrial IoT currently enforces certain Content-Security-Headers (CSP), which prevents the execution of inlined JavaScript.

Configuration options¶

The 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 OS Bar is not populated. Note: The 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 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	`"/app-info.json"`

App information¶

The following app information can be displayed in the 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 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.
`documentation`	Specifies the link to the app documentation.
`links`	Specifies further links to be displayed in a sub-menu of the app information. Available link types are: - Website (WWW) - E-mail (MAIL) - Phone number (PHONE)

Documentation and info 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 OS Bar. Otherwise, the default language is used.
Apps can provide a dedicated link to their documentation. At least, apps should provide a link to the third party software they use.

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

{
  "displayName": "Sample App",
  "appVersion": "0.0.0",
  "appCopyright": "© Siemens 2024",
  "documentation": {
    "default": "https://sie.ag/documentation/en",
    "de": "https://sie.ag/documentation/de"
  },
  "links": {
    "default": [
      {
        "type": "WWW",
        "name": "Third-Party Software",
        "value": "http://sie.ag/abc"
      }
    ],
    "de": [
      {
        "type": "WWW",
        "name": "Drittanbieter Software",
        "value": "http://sie.ag/abc"
      }
    ]
  }
}

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

...
_mdsp.init({
    title: "OS Bar Demo",
    appId: "_mdspcontent",
    appInfoPath: "/assets/json/myfile.json"
});
...

Dynamic insertion¶

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

...
(function(d, script) {
    script = d.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.onload = function(){
        _mdsp.init({
            title: "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 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.

Known issues¶

ngx-bootstrap¶

When using the OS Bar with ngx-bootstrap, the bootstrap version cannot be detected automatically. This might cause it to render the components for the wrong version.

Set the bootstrap version manually to avoid this.

import { setTheme } from 'ngx-bootstrap/utils';

@Component({...})
export class AppComponent {
    constructor() {
        setTheme('bs3'); // or 'bs4'
        ...
    }
}