Zum Inhalt

Host

Die Host-Komponente ist ein Singleton und besitzt nur eine Instanz. Der Host bildet die Grundlage der Anwendung. Der Host ist für das laden der Konfiguration, die Initialisierung der Navigation und die Bereitstellung grundlegender Funktionen verantwortlich. Die Instanz des Hosts ist über die Alvine.Registry erreichbar: Alvine.Package.Console.Host

Konfiguration

Die Konfiguration wird über die Methode Host.loadConfig(url) geladen. Wird keine url übergeben, so wird der Standardwert config.json verwendet. Die Werte der Konfiguration wird in der Registry im Schlüssel console.settings gespeichert.

Notify

Um den Benutzer direkt über ein Ergebnis einer Aktion zu informieren, bietet der Host mit der notify-Schnittstelle die Möglichkeit direkt Kundenmeldungen abzugeben. Über die Methoden Host.notifyDanger(), Host.notifySuccess(), Host.notifyWarning() und Host.notifyInfo() können unterschiedliche Meldungen angeziegt werden.

message = "Aktion konnte nicht ausgeführt werden";
icon = "fa fa-cogs";
title = "Mein Titel";
url = "http://example.com";
location = "_blank";

// Bis auf die Message sind alle Parameter optional Alvine.Package.Console.Host.notifyWarning(message, icon, title, url, location);

Die Meldung und der Titel können auch lokalisierte Texte enthalten.

Alvine.Package.Console.Host.notifyWarning('i18n:thiswarning');

Um Navigationshandler zu registrieren, muss die Methode Alvine.Package.Console.Host.register() aufgerufen werden und ein Objekt vom Type Alvine.NavigationHandler übergeben werden.

handler = new Alvine.Package.Console.NavigationHandler('shortcut', function() {
  // ... code
})

Kontext

Ein Kontext wird durch den Hash-Wert in einer URL definiert. Der Kontext in dem sich der Benutzer in der folgenden URL befindet ist dashboard. Der Kontext wird durch Argumente genauer spezifiziert. Die Argumente sind durch eine Kombination von Wertepaaren (key=value), die durch ein Semikolon getrennt sind, definiert.

http://www.example.com/page#dashboard;panel=1

Location

Das Location-Objekt bildet einen Kontext mit seinen Argumenten ab. Ein neues Location-Objekt kann über die Funktion Location(context, contextArguments) erstellt werden. Die Argumente können entweder als Map oder als Objekt-Array übergeben werden.

location = new Alvine.Package.Console.Location('mypage', {a=1, b=1})

Werden keine Argumente angeben, so wird ein Location-Objekt mit der aktuelle Location des Browser-Windows erstellt.

location = new Alvine.Package.Console.Location()

Über die Methode Location.toString() kann aus dem Location Objekt eine Zeichenkette erstellt werden. Die Methode Location.getContext() liefert den Kontext zurück. Die Argumente können über die Methode Location.getArguments() ausgelesen werden. Ein einzelnes Argument kann mit Hilfe Location.getArgument(key, defaultValue) ausgelesen und mit Hilfe von Location.setArgument(key, value) verändert werden.

Über die Methode Location.activate() wird der Kontext an den Browser übergeben und aktiviert.

Objektreferenz

Alvine.Package.Console.Location(context, contextArguments)

Beschreibung

Neues Objekt erstellen. Wird kein Kontext und keine Argumente übergeben, so wird die aktuelle Location des Browsers verwendet.

Parameter-Liste

context (String)

Eindeutige Bezeichnung des Kontext (erscheint in der URL hinter dem Hash #)

contextArguments (Alvine.Types.Map | Object)

Argumente die im Kontext verwendet werden sollen. Diese werden per Seikolon vom Kontext getrennt.

Rückgabewert

Neues Location-Objekt

Location.toString()

Beschreibung

Gibt den Kontext und die Argumente als Zeichenkette zurück.

Rückgabewert

String mit dem Kontext und den Argumenten

Location.activate()

Beschreibung

Aktiviert den Kontext des Objekts im Browserwindows.

Rückgabewert

Referenz auf Location

Location.getArguments()

Beschreibung

Argumente des Objektes holen

Rückgabewert

Gibt die Alvine.Types.Map mit den Argumenten zurück

Location.getContext()

Beschreibung

Kontext des Objekts auslesen

Rückgabewert

Gibt Kontext als String zurück

Location.setArgument(key, value)

Beschreibung

Argumente des Objekts einzeln setzen

Parameter-Liste

key (String)

Schlüssel des Arguments

value (String)

Wert des Arguments

Rückgabewert

Referenz auf Location

Location.removeArgument(key)

Beschreibung

Entfernt ein Argument

Parameter-Liste

key (String)

Schlüssel des Arguments

Rückgabewert

Referenz auf Location

Location.getArgument(key, defaultValue)

Beschreibung

Wert eines Arguments auslesen

Parameter-Liste

key (String)

Schlüssel des Arguments

defaultValue (String)

Standardwert, wenn der Schlüssel nicht gesetzt ist.

Rückgabewert

Wert des Arguments oder defaultValue

Änderung des Kontextes

Die Konsolenanwendung läft in verschiedenen Kontexten, die über den ersten Wert im Hash in der URL definiert werden. Beim Ändern des Kontextes wird der Event contextchange.HOST.DONE gesendet. Als Parameter enthält der Event eine Referenz auf den Host, den Wert des Kontextes und die Argumente.

#myhash;a=4;b=5

myhash ist der Kontext und a und b sind die Kontext-Argumente.

Will man den Kontext über das Skript ändern, so stehen mehrer Wege offen. Man kann entweder direkt über die window.location einen neuen Wert setzen oder man erstellt ein Location-Objekt und aktiviert dieses. Über den Host kann man die Methode Alvine.Package.Console.Host.changeLocation(location) verwenden.

map = new Alvine.Types.Map();
map.set('key','value');
Alvine.Package.Console.Host.changeLocation(new Alvine.Package.Console.Location('newValue', map));

Die Methode Alvine.Package.Console.Host.changeLocation(location) bietet den Vortail, das kein Location-Objekt erstellt werden muß, die Arguente können auch in Kurzform angegeben werden.

Alvine.Package.Console.Host.changeLocation('newValue', {a=1,b=1});

Will man nicht den gesamten Kontext ändern, sondern nur einzelne Werte so kann die Methode Host.setLocationArgument(key, value) verwendet werden. Über die Methode Host.removeLocationArgument(key) können Argumente entfernt werden.

Kontextänderungen

Um Änderungen des Kontextes und Änderungen der Variablen mitzubekommen, kann man im Host einen Handler registrieren. Dies erfolgt über die Methode Host.registerContextHandler(location, callback). Die Abmeldung vom Host erfolgt über die Methode Host.unregisterContextHandler(location)

function callback(location) {
// this === host
}

location = new Alvine.Package.Console.Location('demo');
Alvine.Package.Console.Host.registerContextHandler(location, callback);

Alvine.Package.Console.Host.unregisterContextHandler(location);

Für Registrierungen mit dem aktuellen Kontext gibt es die Kurzformen Host.registerCurrentContextHandler(callback) und Host.unregisterCurrentContextHandler().

Möchte man die Änderung über jeden Kontext erhalten, so kann man als Location einen Stern Host.registerCurrentContextHandler('*') übergeben.

Änderung der Location

Soll über die Kontextänderung jede Änderung der Location beobachtet werden, so kann man sich in die Eventverarbeitung zu dem Event locationchange.HOST hängen. Als Argument erhält man die aktuelle Location. 

jQuery(globalContext).bind('locationchange.HOST.MYHANDLER', function (event, location) {
    // ...
});

Kontext auslesen

Über die Methode Host.getLocation() kann die aktuelle Location ausgelesen werden. 

location = Alvine.Package.Console.Host.getLocation();

// Aktueller Kontext
location.getContext();

// Argumente
location.getArguments()
// -> Map mit Argumenten

Views

Jeder Kontext sollte über einen View verfügen, der mittels Component.createView() erstellt wird. 

<template id="template">
    <div data-container></div>
</template>

Der Methode Component.createView() können zwei Callbacks übergeben werden. Der erste Callback

/** Initialisierung der Felder, Inhalte und Controls */

var view;

function initUI(configuration) {
    panel = ...

    /** View leeren */
    view.clear();

    /** Inhalt hinzufügen */
    view.appendContent(panel);
}

/** Aktivierung der Felder, Inhalte und Controls */
function activateUI(configuration) {
}

component = Alvine.Package.Factory.createComponent(namespace + '.Demo');
view = component.createView(namespace + '.Demo.Panel', '#template',
            {'required': ['Alvine.Package.UI.Dialog.Bootstrap']}, initUI, activateUI);

Beim Erstellen und Hinzufügen des Views zum DOM wird zuerst initView aufgerufen. Zu diesem Zeitpunkt enthält das DOM noch keine Elemente aus dem View. In der InitView-Funktion können zum Beispiel Controls über View::appendContent() zum View hinzugefügt werden. Werdem dem Template über View.appendContent() Inhalte hinzugefügt, so werden diese in der Node mit dem Attribute data-container ins DOM eingefügt.

Der erste Parameter der Callback-Methoden definiert die Werte aus der Konfiguration. Wird ein optionales zweites Argument angegebn, so wird diesem Wert ein Callback übergeben. Dieser Callback muss im Funktionsbody explizit aufgerufen werden. Erst mit aufruf von done() wird der View eingehängt und activateUI() aufgerufen.

function initUI(configuration, done) {
    // muss explizit aufgerufen werden
    done();
}

Kontext verlassen

Im Rahmen eines Modules werden unterschiedliche Ressourcen reserviert. Sei es ein Eintrag in der Registry oder ein global registrierter Eventhandler. Um beim Verlassen eines Kontextes diese Ressourcen freizugeben, muss das Modul die Methode Component.cleanUp() implementieren. Diese Methode wird beim Ändern des Kontextes aufgerufen.

component = Alvine.Package.Factory.createComponent(namespace + '.' + componentName);
component.cleanUp = function () {
                // Aufräumen    
};

Modul laden

Ein Modul kann zur Laufzeit geladen werden. Dazu stellt der Host die Methode Host.loadModule(module, url) bereit.

Alvine.Package.Console.Host.loadModule('MyPackage', 'http://example.com/packages/mypackage.html');

Hinweis

Falls das Modul eine Konfiguration benötigt, muss diese vorher in der zentralen Konfiguration eingetragen werden.

ServiceWorker

Der Host kann beim Start einen Serviceworker initialisieren. Dazu muss in der Konfiguration unter dem Schlüssel serviceworker.url eine URL und ein optionaler Scope serviceworker.scope angegeben werden. Der Serviceworker wird dann registriert und die Registration ist über der ServiceWorkerWrapper erreichbar. Der gültige Wrapper kann mit der Methode Host.getServiceWorkerWrapper() geholt werden.

Cache

Um den Cache zu leeren muss die Methode ServiceWorkerWrapper.clearCache(key) aufgerufen werden. Die Methode ServiceWorkerWrapper.clearCaches(whitlist) löscht hingegen alle Caches. 

sw = Alvine.Package.Console.Host.getServiceWorkerWrapper();
sw.clearCache('mycache')
   .then(function(value){
      console.log('Gelöscht: ',value);
   }).catch(function(error){
      console.log("Fehler: "+error);
   });

Objektreferenz

ServiceWorkerWrapper(registration)

Beschreibung

Der ServiceWorkerWrapper kapselt den ServiceWorker des Hosts.

Parameter-Liste

registration (Types)

Registration des ServiceWorkers

Rückgabewert

Gibt ein ServiceWorkerWrapper Objekt zurück

ServiceWorkerWrapper.getRegistration()

Beschreibung

Gibt die Registration zurück

Rückgabewert

Gibt die Registration zurück

ServiceWorkerWrapper.sendMessage(message)

Beschreibung

Diese Methode sendet eine Nachricht an den Serviceworker

Parameter-Liste

message (String | Object)

Die zu sendende Nachricht

Rückgabewert

Gibt ein Promise zurück

ServiceWorkerWrapper.clearCaches(whitelist)

Beschreibung

Diese Methode holt alle verfügbaren Caches und löscht diese. Über den Parameter

Parameter-Liste

whitelist (Array)

Ein Array, mit Namen die nicht gelöscht werden sollen.

Rückgabewert

Ein Promise mit einem Array als Promise-Wert. Das Array enthält soviele Einträge, wie Caches gelöscht wurden. Bei Erfolg steht ein true, bei Misserfolg ein false im Eintrag des Array.

ServiceWorkerWrapper.clearCache(key)

Beschreibung

Diese Methode prüft, ob es einen Cache mit dem Namen gibt und löscht diesen.

Parameter-Liste

key (String)

Name des Chaches

Rückgabewert

Promise

Internationalisierung i18n

In der Host-Komponente wird in Abhängigkeit der Sprache des Konsolen-Dokuments <html lang="de"> die Lokale-Datei mit den sprachabhängigen Zeichenketten geladen. Auf die Zeichenketten kann mittels der Methode Host.getLocaleMessage(key, default, map) zugegriffen werden. Das Laden der Locale kann über die Methode Host.loadLocale(url) oder Host.loadLocales([url]) erfolgen.

// Map mit Ersetzungen
map = new Alvine.Types.Map();
map.set('count',4);

// Lokalisierte Zeichenkette
mystring = Alvine.Package.Console.Host.getLocaleMessage('mykey','defaultvalue', map);

Über den dritten Parameter in Host.getLocaleMessage(key, default, map) kann eine Map mit Ersetzungen übergeben werden. In dem Beispiel ist in der Zeichenkette der Platzhalter %count% definiert. Dieser wird in dem Beispiel mit dem Wert aus der Map, hier 4, ersetzt.

Objektreferenz

Host.getLocation()

Beschreibung

Schlägt die aktuelle Location des Browsers nach und erstellt ein Location Objekt

Rückgabewert

Gibt 'Location'-Objekt zurück

Host.registerHandler(handler)

Beschreibung

Registriert einen Alvine.Package.Console.NavigationHandler im Host.

Parameter-Liste

handler (Alvine.Package.Console.NavigationHandler)

Zu registrierender Handler

Rückgabewert

Referenz auf den Host

Host.getLocaleMessage(key, defaultValue, map)

Beschreibung

Die Methode schlägt in der Registry Alvine.Registry.get('Locale') den Schlüssel key nach und gibt die gefundene Zeichenkette oder den Standardwert defaultValue zurück. Über die map können vorhandene Ersetzungen in der Zeichenkette durchgeführt werden.

Parameter-Liste

key (String)

Schlüssel

defaultValue (String)

Standardwert, wenn der key nicht vorhanden ist

map (Alvine.Types.Map)

Map mit Ersetzungen

Rückgabewert

Gibt String mit lokalisierte Zeichenkette oder Standardwert defaultValue zurück.

Host.notifyDanger(message, icon, title, url, target)

Beschreibung

Die Methode gibt eine Nachricht message mit Farbgebung für Probleme in der Konsole aus. Für die Darstellung kommt das Bootstrap Notify-Plugin zum Einsatz.

Parameter-Liste

message (String)

Auszugebender Text

icon (String)

CSS-Klasse, die ein Icon definiert. Wird kein Icon angegeben, so wird fa fa-times-circle verwendet.

title (String)

Titel des Nachrichtenfensters

url (String)

Wird eine URL angegeben, so wird das Meldefenster zu einer klickbaren Fläche mit der angegebenen URL als Ziel.

target (String)

Browsertarget (Mögliche Werte: _blank | _self | _parent | _top)

Rückgabewert

Gibt Referenz auf Host zurück

Host.notifyDanger(message, icon, title, url, target)

Beschreibung

Die Methode gibt eine Nachricht message mit Farbgebung für einen Erfolg in der Konsole aus. Für die Darstellung kommt das Bootstrap Notify-Plugin zum Einsatz.

Parameter-Liste

message (String)

Auszugebender Text

icon (String)

CSS-Klasse, die ein Icon definiert. Wird kein Icon angegeben, so wird fa fa-times-circle verwendet.

title (String)

Titel des Nachrichtenfensters

url (String)

Wird eine URL angegeben, so wird das Meldefenster zu einer klickbaren Fläche mit der angegebenen URL als Ziel.

target (String)

Browsertarget (Mögliche Werte: _blank | _self | _parent | _top)

Rückgabewert

Gibt Referenz auf Host zurück

Host.notifyWarning(message, icon, title, url, target)

Beschreibung

Die Methode gibt eine Nachricht message mit Farbgebung für eine Warnung in der Konsole aus. Für die Darstellung kommt das Bootstrap Notify-Plugin zum Einsatz.

Parameter-Liste

message (String)

Auszugebender Text

icon (String)

CSS-Klasse, die ein Icon definiert. Wird kein Icon angegeben, so wird fa fa-warning verwendet.

title (String)

Titel des Nachrichtenfensters

url (String)

Wird eine URL angegeben, so wird das Meldefenster zu einer klickbaren Fläche mit der angegebenen URL als Ziel.

target (String)

Browsertarget (Mögliche Werte: _blank | _self | _parent | _top)

Rückgabewert

Gibt Referenz auf Host zurück

Host.notifyInfo(message, icon, title, url, target)

Beschreibung

Die Methode gibt eine Nachricht message mit Farbgebung für eine Information in der Konsole aus. Für die Darstellung kommt das Bootstrap Notify-Plugin zum Einsatz.

Parameter-Liste

message (String)

Auszugebender Text

icon (String)

CSS-Klasse, die ein Icon definiert.

title (String)

Titel des Nachrichtenfensters

url (String)

Wird eine URL angegeben, so wird das Meldefenster zu einer klickbaren Fläche mit der angegebenen URL als Ziel.

target (String)

Browsertarget (Mögliche Werte: _blank | _self | _parent | _top)

Rückgabewert

Gibt Referenz auf Host zurück

Host.disableEasterEgg()

Beschreibung

Die Methode schaltet die Alvine-Ausgabe in der Browser-Konsole aus und speichert die Einstellung im localStorage.

Rückgabewert

Gibt die Zeichenkette OK zurück

Host.loadModule(module, url)

Beschreibung

Diese Methode lädt ein Modul mit einem Namen und der angegebenen URL

Parameter-Liste

module (String)

Name des Moduls mit Namespace

url (String)

URL, unter der das Modul zu finden ist.

Rückgabewert

Gibt ein Objekt vom Typ Alvine.Package.Module zurück.

Host.getCurrentComponentName()

Beschreibung

Gibt den Namen der aktuellen Komponente zurück. Zum Beispiel Alvine.Platform.Item

Rückgabewert

Gibt einen String mit dem Namen der Komponente zurück.

Host.registerContextHandler(location, callback)

Beschreibung

Registriert einen Kontext-Handler

Parameter-Liste

location (String | Location)

Zu registrierende Location

callback (Function)

Handler

Rückgabewert

Gibt Referenz auf den Host zurück.

Host.unregisterContextHandler(location)

Beschreibung

Entfernt eine Registrierung für einen Kontext

Rückgabewert

Gibt Referenz auf den Host zurück.

Host.resetCurrentNavigationHandler()

Beschreibung

Setzt den Aktuellen Navigations-Handel zurück.

Rückgabewert

Gibt Referenz auf den Host zurück.

Host.changeLocation(location, contextArguments)

Beschreibung

Diese Methode wechselt den Kontext zu dem Wert der Location

Parameter-Liste

location (String | Location)

Neue Location

Rückgabewert

Gibt Referenz auf den Host zurück.

Host.setLocationArgument(key, value)

Beschreibung

Mit dieser Methode kann man in der aktuellen Location des Browsers ein Kontext-Argument setzen.

Parameter-Liste

key (String)

Schlüssel des Arguments

value (String)

Wert des Arguments

Rückgabewert

Gibt Referenz auf den Host zurück.

Host.removeLocationArgument(key)

Beschreibung

Mit dieser Methode kann man in der aktuellen Location des Browsers ein Kontext-Argument entfernt werden.

Parameter-Liste

key (String)

Schlüssel des Arguments

Rückgabewert

Gibt Referenz auf den Host zurück.

Host.loadConfig(url)

Beschreibung

Diese Methode lädt die Konfiguration des Hosts.

Parameter-Liste

url (String)

URL der Konfiguration

Rückgabewert

Gibt Referenz auf den Host zurück.

Host.loadLocales(urls)

Beschreibung

Lädt Sprachdateien mit Schlüssel-/Wertpaaren im Format JSON. Über das Promise kann das weitere Vorgehen definiert werden. Hierzu muss eine then und catch-Methode implementiert werden.

Achtung: Es muss nur die Basisurl in dem die Dateien liegen angegeben werden. Die Funktion entscheidet selbstständig welche Datei geladen wird.

Wird die Datei nicht innerhalb von 10 Sekunden erfolgreich geladen, so wird das Promise auf fehlerhaft gesetzt. Das heißt allerdings nicht, dass die Datei nicht noch geaden wird.

Parameter-Liste

urls (Array)

Ein Array mit mehreren Basis-URLs die geladen werden sollen.

Rückgabewert

Gibt ein Promise zurück, das sobald alle Resourcen geladen wurde einen Erfolg vermeldet.

Host.loadLocale(url)

Beschreibung

Lädt Sprachdateien mit Schlüssel-/Wertpaaren im Format JSON. Über das Promise kann das weitere Vorgehen definiert werden. Hierzu muss eine then und catch-Methode implementiert werden.

Achtung: Es muss nur die Basisurl in dem die Dateien liegen angegeben werden. Die Funktion entscheidet selbstständig welche Datei geladen wird.

Wird die Datei nicht innerhalb von 10 Sekunden erfolgreich geladen, so wird das Promise auf fehlerhaft gesetzt. Das heißt allerdings nicht, dass die Datei nicht noch geaden wird.

Parameter-Liste

url (String)

Eine Basis-URL an der die Sprachdatei liegt.

Rückgabewert

Gibt ein Promise zurück, das sobald alle Resource geladen wurden einen Erfolg vermeldet.

Host.isLocaleQueueEmpty(timeout)

Beschreibung

Diese Methode gibt ein Promise zurück und hierüber das weitere Vorgehen definiert werden. Hierzu muss eine then und catch-Methode implementiert werden.

Ist die Queue nicht innerhalb von timeout Millisekunden erfolgreich geleert worden, so wird das Promise auf fehlerhaft gesetzt. Das heißt allerdings nicht, dass die Dateien aus der Queue nicht noch geladen werden.

Parameter-Liste

timeout (Integer)

Timeout

Rückgabewert

Gibt ein Promise zurück, das sobald alle Ressourcen geladen wurde einen Erfolg vermeldet.

Host.getServiceWorkerWrapper()

Beschreibung

Mit der Methode kann der ServiceWorkerWrapper geholt werden.

Rückgabewert

Gibt den im Host registrierten ServiceWorkerWrapper zurück.

Ablaufdiagramm

uml diagram

Referenzen

Kommentare