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.

Internationalisierung i18n

In der Host-Komponente wird in Abhängigkeit der Sprache des Dokuments <html lang="de"> die Lokale-Datei mit den sprachabhängigen Zeichenketten geladen. Auf die Zeichenketten kann mittels der Methode Host.getLocale() zugegriffen werden. Die Methode Host.getLocaleMessage(key, default, map) liefert sprachabhängie Zeichenketten aus der Resourcen-Datei.

// 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.

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() ausgelsen 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.

Ä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 Resourcen reserviert. Sei es ein Eintrag in der Registry oder ein global registrierter Eventhandler. Um beim Verlassen eines Kontextes diese Resourcen 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    
};

Referenzen

Kommentare