This object contains some MorphIT services that are useful for the development of WebWidgets .

• contextMenu
• location
• localization
• morphitLocalStorage
• overlay
• webwidgetCommunication
• webwidgetLoader
• widgetOverlay
• widgetModel

services.contextMenu

This service provides methods for the WebWidget to control its grid menu (a menu button is displayed in the top right corner of the widget).

• setGridMenuItem(widgetId, item, noAdd)
• removeGridMenuItem(widgetId, item)

services.contextMenu.setGridMenuItem(widgetId, item, noAdd)

Adds a new menu item to the grid menu of the widget, or updates an existing item with the same item id.

The widgetId gets a WebWidget from the widget returned by webwidgetLoader.loadWidget().

The item is an object with the following structure:

Item

If an existing menu item is updated, only the properties specified in the item parameter are updated. For example, one can simply deactivate an already existing menu item with the following call.

morphitApi.services.contextMenu.setGridMenuItem(this.widget.id, {id:itemId, disabled:true});

If noAdd = true is set, then only existing menu items are updated, but no new ones are created if no menu item with the corresponding ID exists.

services.contextMenu.removeGridMenuItem(widgetId, item)

Removes a previously inserted menu item. The only property that must be defined in item is the id.

services.location

This service provides a few methods to work with the URL of the MorphIT application and resolve relative paths for resources.

• clientSearch()
• proxySearch()
• search()
• getPort()
• resolvePathStrict(relativePath, startPath?)
• getRelativePath(resource, startPath?)
• getAbsolutePath(resource, startPath?)

services.location.clientSearch() -> {name:value}

This method parses the query string (everything after the "?") of the URL (from the current address bar in the browser) and returns the passed query parameters as an object.

services.location.proxySearch() -> {name:value}

If the MorphIT application is running behind a reverse proxy that translates a URL like "https://site.com/morphit/customer/acme" into "https://site2.com/?customer=acme", then this method returns only the query parameters that are added by the reverse proxy and are not visible in the browser's address bar (the MorphIT server plays this information back to the client).

The query parameters are returned as an object just like from location.clientSearch().

services.location.search() -> {name:value}

This method returns all query parameters (location.clientSearch() + location.proxySearch()) as an object that the MorphIT server saw during the query and returned to the client.

services.location.getPort() -> number

This method returns the port number from the address line of the browser. If no port is explicitly specified, the port number is determined from the protocol used (http/https).

services.location.resolvePathStrict(relativePath, startPath?) -> string

Resolves a path relative to a start path (default = path to index.html of MorphIT) and throws an error if during path navigation an attempt is made to navigate out of the root path ("/") via "..".

If an absolute path is passed (starting with "/"), then the path is resolved relative to the root path and the startPath parameter is ignored.

services.location.getRelativePath(resource, startPath?) -> string

Resolves the relative path passed in resource relative to the directory of startPath (default = path to index.html of MorphIT). There is no path resolution in the classical sense, the two strings are connected at the correct position and if the URL is requested via the browser, then the browser resolves the path navigation ("." and "..").

services.location.getAbsolutePath(resource, startPath?) -> string

Like location.getRelativePath(), except that an absolute URL is generated that also contains the server address itself.

services.localization

This service implements methods and objects to allow WebWidgets to respond to language/location changes.

• onLanguageChanged(callback)
• onLocaleChanged(callback)
• registerTranslation(widgetUrl, path?)

services.localization.onLanguageChanged(callback) -> deregisterFn

This method registers a callback function that is called each time the language changes with the new language. The passed callback function is called with a string parameter and the language corresponds to the DIN EN ISO 639-1 Alpha 2 standard. (Ex. "en", "de", "fr")

The callback function is called directly with the currently active language for the first time during registration.

The returned deregisterFn should be called to deregister the callback as soon as it is no longer needed. For WebWidgets, this should be done at the latest when they are closed (see Widget.onDestroy()).

services.localization.onLocaleChanged(callback) -> deregisterFn

This method registers a callback function that is called with the new locale information whenever the locale information changes. The locale information is an object and currently consists of the following data:

LocaleInfo

The callback function is called for the first time during registration directly with the currently active locale information.

The returned deregisterFn should be called to deregister the callback as soon as it is no longer needed. For WebWidgets, this should be done at the latest when they are closed (see Widget.onDestroy()).

services.localization.registerTranslation(widgetUrl, path?) -> Translator

This method allows a WebWidget to register its translation file(s) and returns an object that loads the translation files on demand and reads texts by id from the translation files.

Usually, the path to the WebWidget should be specified as widgetUrl (see Widget.url) and the relative path from the folder of the WebWidget to the translation file, or to the folder with the translation files, as path.

Alternatively, a path to the translation file/folder can be specified directly as widgetUrl and path can be omitted as a parameter in this case. In this case, widgetUrl is resolved relative to MorphIT's index.html.

<script>
morphitApi.services.webwidgetLoader.loadWidget('widget.js').then((widget) => {
    let translator = morphitApi.service.localization.registerTranslation(widget.url, 'translations/');
    translator.translate(['hello', 'world']).then((t) => {
        console.log(t['hello'] + ' ' + t['world']);
    });
})
</script>

If a .json translation file is specified, then MorphIT expects that for each language abbreviation (e.g. "de") in the JSON file there is an object with the order from Id to text.

If a folder is specified as the translation path, MorphIT expects that for each language abbreviation (e.g. "de") there is a corresponding .json file in the folder (e.g. "de.json") in which the object with the assignment of Id to text is defined.

Only one Translator object is created per translation path, so that several widgets can share the same Translator object. In this case, the translation files are only loaded once into the memory.

Translator

This object is responsible for the delayed loading of the translation files and the translation of the ids into the texts based on the loaded translation files.

• translate(ids, variables?)

Translator.translate(ids, variables?) -> Promise&lmt;string|{id:text}>

This method loads the translation file for the current language (if not already done) and then translates the passed ids (string or array of strings) using this translation file. An id can also be a path if the translation file is structured accordingly (e.g. "dialog.title.warning").

If a single id is passed, then the promise is fulfilled with a single string (the translated text). If an array of ids is passed, then the promise is fulfilled with an object, where the keys represent the individual ids and the values represent the translated texts.

Optionally, an arbitrarily structured object can be passed in variables. In the translation files, the fields of this passed object can be referenced in the translation texts via "{{path}}".

// Request and await translation for text literals
this.translator.translate(['dialog.info', 'language.changed'], {lang:{from:'en', to:'de'}}).then((t) => {
    // Display translated texts in a dialog
    morphitApi.services.overlay.showDialog(t['dialog.info'] + ': ' + t['language.change'], 'info');
});

The associated translation file could look like this:

{
    "dialog": {
        "info": "Information"
    },
    "language": {
        "changed": "Sprache wurde von {{lang.from}} auf {{lang.to}} geändert"
    }
}

services.morphitLocalStorage

This service provides access to the localStorage object used internally by MorphIT. The service stores keys with a URL prefix so that two MorphIT instances running on different paths on the same server do not overwrite each other's localStorage.

• put(key, value) - set value
• get(key) - read out value
• remove(key) - remove value
• clearAll() - remove all stored values
• getAll() - Returns all entries of the localStorage as an object.

services.overlay

This service provides access to the MorphIT loading & dialogue overlay. Dialogues can be opened in the look & feel of MorphIT.

In addition, this can be used to control the loading overlay (loading curl) for the MorphIT application. However, WebWidgets should preferably use services.widgetOverlay for the display of a loading overlay and status texts in order not to impair the use of the rest of the application.

• showDialog(message, level?, options?)
• showInputDialog(options)
• showFileDialog(text, multiSelect, webcam, fileTypePattern, onComplete)
• showThumbnailDialog(options, onComplete?)
• closeDialog()
• showWaitingElement(message?)
• closeWaitingElement()

services.overlay.showDialog(message, level?, options?)

Displays a regular dialogue (as in DialogBox). The displayed message can contain any special characters and line breaks "\n" are displayed as such.

level can take one of the following values: "info", "warning" (=default), "error", "exception", "question" and determines the text and the styling of the title line of the dialogue.

The options object has the following fields that can be set:

services.overlay.showInputDialog(options)

Displays a text input dialogue in which 1-n texts can be queried. The options parameter is an object with the following structure:

services.overlay.showFileDialog(text, multiSelect, webcam, fileTypePattern, onComplete)

Shows a file upload dialogue with text as description text, in which 1-n files can be dropped in. Alternatively, clicking on the upload button opens the native file explorer for file selection. The dialogue also shows a camera button with which the webcam can be opened in order to take a photo and select it.

If multiSelect = true, several files can be selected, otherwise only one file is allowed.

If webcam = true, the webcam is opened directly for taking a photo without the corresponding button having to be pressed first.

fileTypePattern can contain a string like "*.png" to restrict the file selection in the native file explorer to the corresponding file type. If this is not desired, simply pass false or undefined here.

onComplete(files) is the callback function that is called as soon as the dialogue is closed. If the dialogue was cancelled, then the function is called with undefined as a parameter, otherwise an array of files is called (even if multiSelect=false ). Files selected from the file system are passed as file objects, pictures taken with the webcam are objects with the following structure:

services.overlay.showThumbnailDialog(options, onComplete?)

Displays the overlay with a specified image. The image is displayed in its original size. The user can click anywhere on the overlay to close it again. This overlay is intended for the enlarged display of thumbnails.

options is an object that currently only defines the field imagePath. If a relative path is specified here, then the path is interpreted relative to MorphIT's index.html.

The optionally specified onComplete callbackis called as soon as the user has closed the overlay by clicking.

services.overlay.closeDialog()

Closes any open dialogues. The onConfirm/onComplete function indicated when opening the dialogue is not triggered.

services.overlay.showWaitingElement(message?)

This displays the overlay and the "waiting curl" with an optional status message.
WebWidgets should use WidgetOverlay.show() instead.

services.overlay.closeWaitingElement()

Closes a previously opened loading/status overlay.
WebWidgets should use WidgetOverlay.hide() instead.

services.webwidgetCommunication

This services encapsulates the communication of WebWidgets with ClassiX.

• registerWidget(id)

services.webwidgetCommunication.registerWidget(id)-> Channel

With this method, a WebWidget registers that it wants to communicate with the ClassiX counterpart of this WebWidget via a bidirectional communication channel. The id should correspond to the widget id of the WebWidget, which can be obtained, for example, via webwidgetLoader.loadWidget().

registerWidget() does not check the passed widget id for correctness. If an incorrect id is passed, then no messages can be sent and received via the returned channel object.

Note: Since the JavaScript of the WebWidgets can only be executed after the open WebWidget has arrived in the browser, any WebWidget communication between InstantView & JavaScript should always be initiated from the JavaScript side. Messages sent from InstantView to a JavaScript WebWidget before it has activated the channel(Channel.on()) will be lost.

Channel

A channel represents a bidirectional communication channel between ClassiX and the concrete WebWidget. If the channel is no longer needed, the channel should be closed and logged off using close().

• on(type, handler)
• send(type, data)
• close()

Channel.on(type, handler)

Registers a web widget handler that is called each time ClassiX and the widget send a web widget message via PushSocket with the type passed. Only one handler can be registered per type. If on() is called a second time with the same type, only the handler passed last applies.

Channel.send(type,data)

Sends a web widget message to the ClassiX web widget (InstantView page) and implements the reverse function to PushSocket.

Channel.close()

Closes the communication channel. Message handlers logged on to the channel are no longer called following close(). This method should always be called when the channel is no longer needed or the WebWidget has been closed.

services.webwidgetLoader

This service is used to develop pure JS/HTML WebWidgets without Angular and provides only one relevant method for this purpose:

• loadWidget(path)

services.webwidgetLoader.loadWidget(path?)-> Promise&lmt;Widget>

This method loads the .js file of an .html WebWidget. This .js file usually contains all the logic of the web widget and, unlike the .html part , is only loaded once.

Attention: This method may only be called within a script block in the .html part of the WebWidget, otherwise the method cannot assign the call to a widget and potentially resolves the path incorrectly.

If no path argument was passed, then no script file is loaded, but only the widget structure is returned (including Promise, which is immediately resolved). The call without path makes sense for small script WebWidgets that are inserted directly into a WebWidget via PutValue and do not need to reload any script files, but still need access to the information from the widget object.

The Promise returned by loadWidget contains a Widget object with the following properties:

Widget

Note: loadWidget also writes the above properties directly into the returned Promise object, so these properties can be read before the Promise is fulfilled.

Code example:

<script>
(function() {
    morphitApi.services.webwidgetLoader.loadWidget('widget.js').then((widget) => {
        // now the script is loaded....
    });
})();
</script>