Package¶

Die Objekte und Funktionen im Bereich Packages erlauben es Funktionen über Webcomponents bereitzustellen.

Hinweis

HTML Imports allow HTML to be imported from one document to another. This feature was part of the early experimental version of Web Components not implemented in other browsers. As such it is now deprecated with removal expected in Chrome 73, around April 2019. Sites depending on HTML imports already require a polyfill on non-Chromium browsers. When HTML imports is removed, sites that have the polyfill should continue to work on Chrome.

Mit der Version 2.0.0 (Stand 1.1.2019) baut das Framework nichtmehr auf HTMLImports auf, sondern importiert die Scripte und Templates als Javascript direkt.

Dabei bilden die Objekte Modul und Komponente als Paar eine eingebundene Funktionalität ab. Das Modul beschreibt die eingebundene Javascript-Datei und die zugehörigen DOM-Templates und die Komponente verwaltet die inneren Angelegenheiten der eingebundenen Daten und Funktionen.

Funktionsreferenz¶

Alvine.Package.executeOnModulesAvailable(moduleNames, callback, args)

Beschreibung

Mit Hilfe dieser Methode kann Code, der auf das Vorhandensein eines Modules angewiesen ist, nach dem Laden ausgeführt werden.
Alvine.Package.executeOnModulesAvailable('MyModule', function() { /** mache etwas */ }, args);
Die definierte Funktion wird ausgeführt, wenn das Modul MyModul erfolgreich geladen wurde.

Parameter-Liste

moduleNames (String)

Name des Moduls, auf das gewartet werden soll

callback (Function)

Diese Methode wird, nachdem ein Modul erfolgreich geladen wurde, aufgerufen.

args (Array)

Argumente die der Callback-Funktion übergeben werden sollen.

Rückgabewert

Kein Rückgabewert

Alvine.Package.importTemplate(id, template)

Beschreibung

Mit Hilfe dieser Methode kann ein Template-Zeichenkette als Template-Tag in das Dokument eingebunden werden.

Parameter-Liste

id (String)

ID des Moduls

template (String)

Zeichenkette des Templates

Rückgabewert

HTML-Element des Modul-Templates

Base¶

Das Basisobjekt ist der Prototyp für die in dem Paket definierten Objekte, bildet aber keine eigene Funktion ab.

Factory¶

Das Objekt Alvine.Package.Factory erlaubt es über die Methode Factory.createComponent(name, properties, callback) eine neue Komponente zu erstellen. Jede Komponente muss über ein Modul eingebunden worden sein.

Objektreferenz¶

createComponent(name, properties, callback)

Beschreibung

Die Factory-Methode erstellt für ein angegebenes Modul eine Komponente. Als Referenz verwendet Sie den Namen des Moduls (muss mit identischem Namen in der Registry vorhanden sein). Die neue Komponente wird dann in der Registry im Feld Components unter dem angegebenen Namen name registriert.

Parameter-Liste

name (String)

Name des zugehörigen Moduls und der neuen Komponente

properties (Object)

Die Eigenschaften werden direkt an das Komponenten-Objekt angehängt.

callback (Function)

Diese Funktion wird vor dem Eintragen der Komponente in die Registry aufgerufen. Über diese Methode können somit noch Änderungen durchgeführt werden. this ist im Callback die Komponente.

Rückgabewert

Neues Komponenten-Objekt

Module¶

Das Modulesystem sorgt für die Einbindung eines Javascript-Dokuments mit Templates in die Seite. Die Funktionen werden in einer Komponentenklasse gekapselt.

Eine beispielhafte Datei ist im folgenden zu sehen. Die als Modul test-modul importierte Datei erstellt erst eine Komponente um im Anschluss ein View zu erstellen. Das View wird in der Komponente registriert um auf die Templates zugreifen zu können.


Alvine.Package.importTemplate('test-module', `
<template id="templateA1">
    <div>
        <h2 data-replace="dataset:headline">dummy</h2>
    </div>
</template>`);

!(function() {
    var component, view;
    component = Alvine.Package.Factory.createComponent('test-module');
    view = component.createView('Alvine.Package.Test.MyModule.MyView', '#template');
})();

Im Hauptdokument wird das Modul mit der Anweisung new Alvine.Package.Module('test-module') eingebunden. Hier wird auch das Dataset definiert und das View an den Zeilort (ID mycontainer) gerendert.

Über einen Eventhandler, der auf die Events loadmodule.DONE und loadmodule.FAIL hört, kann auf das Ergebnis des Imports gewartet werden und entsprechend reagiert werden.

<div id="mycontainer"></div>
<script>
jQuery(window).on('loadmodule.DONE', function(event, eventModule) {
    var dataset;
    /** Nur das definierte Modul prüfen */
    if(eventModule===module) {

        dataset = new Alvine.DOM.Dataset({"headline": "MyHTML"});
        Alvine.Registry.set('myelementimporttest', dataset);

        Alvine.Registry.get('Components')
            .get('test-module')
            .getView('Alvine.Package.Test.MyModule.Element')
            .appendTo('#mycontainer', dataset);

        done();
    }
});

module = new Alvine.Package.Module('test-module'); 
<script>

Alle Module werden in der Registry unter dem Schlüssel Module registriert.

modules = Alvine.Registry.get('Modules');
// -> Alvine.Types.Map

Automatischer Import¶

Einzubindende Module können auch direkt in HTML definiert werden. Hierzu muss einem Element das Attribute data-auto-import und data-component gegeben werden. Über die Daten-Attribute können dann die Module definiert werden. Pro HTML-Element kann ein Modul definiert werden. Die einzelnen Attribute werden in den entsprechenden Parametern dem Modul-Konstruktor übergeben.

Attribut	Beschreibung
data-component	Name der Komponente
data-container	Name des Datencontainers in der Komponente
data-url	URL der HTML-Datei der Komponente

div data-auto-import
    data-component="MyComponent" 
    data-url="asset/mycomponent.html" 
    data-attributes="data-url dataset:resources | index:console | index:host | trim"></div>

Diese führt zu folgendem Link-Element

<link rel="import" href="asset/mycomponent">

Wichtig

Das betreffende DOM-Element mit der Definition des Moduls wird aus dem DOM entfernt.

Objektreferenz¶

Module(name, containerSelector, url, async)

Beschreibung

Der Konstruktor erstellt ein neues Modul-Objekt und registriert dieses Objekt in der Registry unter dem Namen des Moduls. Über den Namen kann auf das Objekt zugegriffen werden Alvine.Registry.get('Modules').get(name)

Parameter-Liste

name (String)

Beschreibung

containerSelector (String)

Beschreibung

url (String)

URL die für den Import des Moduls verwendet werden soll. Wird keine URL undefined übergeben, so wird die URL aus dem Namen erstellt. Dazu wird der Name in Kleinbuchstaben umgewandelt und alle Punkte werden zu Schrägstrichen. So wird aus Alvine.Console.Host die URL alvine/console/host.html Gleichzeitig wird die Basis-URL des Moduls auf /alvine/console/ gesetz.

async (Boolean)

Synchroner oder Asynchroner Import.

Rückgabewert

Gibt neues Objekt zurück

Module.getBaseURL()

Beschreibung

Mit dieser Methode lässt sich die Basis-URL des Moduls abfragen. Dies ist besonders für das Nachladen von Ressourcen und Bildern sinnvoll.

Rückgabewert

Gibt einen String mit der URL zurück.

Module.getDocumentSynchronous()

Beschreibung

Diese Methode gibt das entsprechende DOM-Dokument-Objekt des Moduls zurück. Ist noch kein Modul eingebunden, oder der Browser unterstützt die Funktion nicht, so wir eine Alvine.Exeption geworfen. Alternativ kann Module.getDocument() verwendet werden.

Rückgabewert

DOM-Dokument des Moduls

Module.getDocument()

Beschreibung

Diese Methode gibt ein Promise zurück, dass sobald das Modul verfügbar ist mit dem DOM-Dokument-Objekt des Moduls erfüllt wird.

Rückgabewert

Promise

Module.getImportedContent(selector, referenceFlag)

Beschreibung

Diese Methode sucht im DOM-Dokument des Moduls nach einer über den Selctor angegebene DOM-Node. Es wird die jQuery funktion find() verwendet.

Parameter-Liste

selector (String)

Der jQuery-Selektor für die entsprechende Suche. Wird kein Selektor übergeben, so wird der Selektor * verwendet.

referenceFlag (Boolean)

Ohne dieses Flag wird eine geklonte Kopie der Nodes zurückgegeben. Wird dieser Parameter auf true gesetzt, so wird eine Referenz auf das Original Element zurück geliefert.

Rückgabewert

Promise

Component¶

Eine Komponente bündelt die Funktionen, die über ein Modul eingebunden wurde.

Hinweis

Das Komponenten-Objekt muss in der importierten HTML-Datei erstellt werden.

Jede Komponente kann mit der Methode Component.getDefaults() eigene Defaultwerte definieren.

Component.getDefaults = function() {
  return {
    'myvalue': 1
  };
}

Über die Factory-Methode Alvine.Package.Factory.createComponent können Komponenten erstellt werden. Diese Methode bündelt alle Schritte zur Erstellung einer Komponente. Die Methode verbindet das Komponentenobjekt mit dem Modul und setzt den entsprechenden Dokumentenkontext. Die Komponenten werden über diese Funktion ausserdem in der Registry unter dem Schlüssel Components registriert.

components = Alvine.Registry.get('Components'); 
// -> Alvine.Types.Map

Mit Hilfe der Methode Component.getContainerSelector() kann der Selector des Containers ermittelt werden. Diese Methode liefert - falls gesetzt - den im Modul definierten Wert zurück.

Mit der Methode Component.getModul() lässt sich das dazugehörige Modul ermitteln.

Um von einer Komponente verwendete Daten aufräumen zu können besitzt die Komponente die Methode Component.cleanUp(). Diese muss überschrieben werden und von der Anwendung aufgerufen werden.

Objektreferenz¶

Component(parameter)

Beschreibung

Dieser Funktion erstellt ein neues Komponenten-Objekt innerhalb eines Moduls. Der Aufruf ist nur innerhalb eines Moduls und hier auch nur einmalig sinnvoll. Im Kontext des Objektes Component.context wird das aktuell - zur Ausführungszeit der Funktion - gültige DOM-Dokument referenziert.

Rückgabewert

Gibt eine neue Komponente zurück

Component.getView(name)

Beschreibung

Gibt einen zugeordneten View mit dem Namen name zurück. Wichtig: Die Methode gibt nicht das eigentliche Property des Objektes zurück, sondern sucht über den Namen der Komponente die Instanz in der Registry und gibt den dort definierten View zurück!

Parameter-Liste

name (String)

Name des gesuchten Views.

Rückgabewert

Gibt einen zugeordneten View mit dem Namen name zurück.

Component.getViews()

Beschreibung

Gibt alle in der Komponente definierten Views als Alvine.Tyes.Map zurück. Wichtig: Die Methode gibt nicht das eigentliche Property des Objektes zurück, sondern sucht über den Namen der Komponente die Instanz in der Registry und gibt den dort definierten View zurück!

Rückgabewert

Gibt alle in der Komponente definierten Views als Alvine.Tyes.Map zurück.

Component.getDocument()

Beschreibung

Liefert das DOM-Dokument-Objekt der Komponente zurück.

Rückgabewert

Gibt das DOM-Dokumenten-Objekt der Komponente zurück.

Component.getDefaults()

Beschreibung

Diese Mathode gibt ein Objekt mit den Defaults der Kompoenten zurück. Diese Defaults werden bei der Anlage des Objekts als Eigenschaften gesetzt.

Rückgabewert

Gibt Objekt mit Default-Werten zurück. {name:'value'}

Component.cleanUp()

Beschreibung

Diese Methode wird nach dem Verlassen einer visuellen Komponente aufgerufen und erlaubt es Aufräumfunktionen zu definieren. hierzu muss diese Methode von dem konkreten Objekt überschrieben werden.

Rückgabewert

Gibt eine Referenz auf die Komponente zurück

Component.getModule()

Beschreibung

Diese Hilfsfunktion gibt das zur Komponente zugehörige Modul zurück.

Rückgabewert

Gibt das Modul, falls vorhanden, oder undefined zurück

Component.getContainerSelector()

Beschreibung

Diese Methode schlägt im zugehörigen Modul nach und holt den definierten Selektor.

Rückgabewert

Gibt undefined oder eine Zeichenkette mit dem definierten Selektor zurück.

Component.createView(name, templateSelector, properties, initCallback, activateCallback)

Beschreibung

Diese Methode erstellt für die Komponente einen View.

Parameter-Liste

name (String)

Name des Views

templateSelector (String)

Beschreibung

properties (Object)

Beschreibung

initCallback (Function)

Diese Funktion wird vor dem Einfügen der Inhalte in das DOM aufgerufen.

activateCallback (Function)

Diese Funktion wird nach dem Einfügen der Inhalte in das DOM aufgerufen.

Rückgabewert

Gibt ein neues Objekt vom Typ Alvine.Package.View zurück.

View¶

Ein View bündelt in einer Komponente ein Dataset und ein Template um eine Ausgabe zu erzeugen. Ein View kann über den Konstruktor erstellt werden.

view = new Alvine.Package.View();

Um den View nicht manuell einrichten zu müssen, sollte die Factory-Methode Alvine.Package.Component.createView() verwendet werden. Diese Methode erwartet als Parameter den Namen des Views name und einen Selektor templateSelector. Optional können Eigenschaften über properties übergeben werden. Die initCallback Funktion wird beim initialisieren aufgerufen. Der activateCallback

Alvine.Package.Component.createView(name, templateSelector, properties, initCallback, activateCallback);

Im folgenden Beispiel wird eine Komponenten-Objekt erstellt und ein View-Objekt erzeugt. Das View wird im Anschluß mittels View.appendTo() in das DOM eingehängt.

component = Alvine.Package.Factory.createComponent('Alvine.Package.Test.MyModule');
view = component.createView('Alvine.Package.Test.MyModule.MainView', '#template');

var dataset = new Alvine.DOM.Dataset({"headline": "MyHTML"});
Alvine.Registry.set('myelementimporttest', dataset);
view.appendTo(component.getContainerSelector(), dataset);

Einem View können über die Methode View.addContent() Inhalte hinzugefügt werden. Diese Inhalte werden in der Render-Phase dem View hinzugefügt.

Alle Inhalte können mit View.clear() wieder gelöscht werden.

Da sich Inhalte im View ändern können, ist es sinnvoll Inhalte Eventhandler nicht an die einzelnen Objekte zu binden, sondern zentral im View zu registrieren. Hierzu ist die Methode View.on() da.

view.on('shown.bs.tab', '.tab', function (e) {
  // ...
});

Als zweiter Parameter kann entweder ein Selector oder ein Objekt vom Type Alvine.UI.Control übergeben werden. Wird ein Control übergeben, ist daraf zu achten welcher Event verwendet wird.

Über die Methode View.appendConten() können dem View Inhalte hinzugefügt werden. Die Inhalte werden beim Aufruf von View.appendTo() ebefalls ins DOM eingefügt.

Wichtiger Hinweis

Die Node, die die Inhate aufnehmen soll, muss das Attribute data-container besitzen.

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

Objektreferenz¶

View(templateSelector)

Beschreibung

Erstellt einen neues View-Objekt einer Komponente

Parameter-Liste

templateSelector (String)

Selektor

Rückgabewert

Gibt ein neues Objekt vom Typ Alvine.Package.View zurück.

View.initView()

Beschreibung

Diese Methode kann von Komponenten überschrieben und für eigene Initialisierungen herangezogen werden.

Rückgabewert

Gibt eine Referenz auf den View zurück.

View.appendContent(content)

Beschreibung

Fügt dem View einen Inhalt hinzu.

Parameter-Liste

Der Inhalt wird beim rendern mittels jQuery.append() bzw. Alvine.UI.Control.appendTo() in den Container des Views eingehangen.

Rückgabewert

Gibt eine Referenz auf den View zurück.

View.appendTo(containerSelector, dataset, replaceFlag)

Beschreibung

Diese Methode ist ein Wrapper für die Methode View.render() mit vertauscher Parameterliste.

Parameter-Liste

containerSelector (String)

Kommagetrennte Liste mit den Selektoren die jeweils einen Container definieren. Die einzelnen Container müssen das Attribute data-container besitzen.

dataset (Alvine.Types.Dataset)

Dataset, mit den Daten für das entsprechende Template.

replaceFlag (Boolean)

Ist das Flag true, so wird vor dem Hinzufügen die Methode jQuery.empty() auf den Container aufgerufen.

Rückgabewert

Gibt eine Referenz auf den View zurück.

View.clear()

Beschreibung

Leert alle Inhalte aus dem View

Rückgabewert

Gibt eine Referenz auf den View zurück.

View.render(dataset, containerSelector, replaceFlag)

Beschreibung

Diese Methode holt über die Eigenschaft View.templateSelector das Template des Views und erstellt mit dem übergebenen Dataset ein HTML-Fragment. Verfügt das Template des Views über einen Container (zum Beispiel ein DIV) mit dem Attribute data-container, so werden alle mittels View.appendContent() hinzugefügten Inhalte in den Container eingehangen.
<template id="template">
  <div data-container></div>
</template>

Parameter-Liste

dataset (Alvine.Types.Dataset)

Dataset, mit den Daten für das entsprechende Template.

containerSelector (String)

Kommagetrennte Liste mit den Selektoren die jeweils einen Container definieren. Die einzelnen Container müssen das Attribute data-container besitzen.

replaceFlag (Boolean)

Ist das Flag true, so wird vor dem Hinzufügen die Methode jQuery.empty() auf den Container aufgerufen.

Rückgabewert

Beschreibung

View.getTemplate()

Beschreibung

Diese Methode holt ein im Kontext des Scripts liegendes Template und gibt dieses zurück.

Rückgabewert

Gibt ein Objekt vom Typ Alvine.DOM.Template zurück

View.on(event, selector, callback)

Beschreibung

Diese Methode hängt den Eventhandler callback an das DOM-Element des Views mit der CSS-Klasse data-container.

Parameter-Liste

event (String)

Name des Events

selector (String | Alvine.UI.Control)

Selektor des zu beobachtenden DOM-Elements oder ein von Alvine.UI.Control abgeleitetes UI-Control. Wird ein UI-Control verwendet, so wird die ID des Controls als jQuery-Selektor verwendet.

callback (Function)

Funktion, die beim eintreffen des Events aufgerufen wird.

Rückgabewert

Gibt eine Referenz auf den View zurück

View.off(event, selector, callback)

Beschreibung

Diese Methode lösst den Eventhandler callback vom DOM-Element des Views mit der CSS-Klasse data-container.

Parameter-Liste

event (String)

Name des Events

selector (String | Alvine.UI.Control)

Selektor des zu DOM-Elements oder ein von Alvine.UI.Control abgeleitetes UI-Control. Wird ein UI-Control verwendet, so wird die ID des Controls als jQuery-Selektor verwendet.

callback (Function | Boolean)

Funktion, die beim Aufruf von on angegeben wurde oder false.

Rückgabewert

Gibt eine Referenz auf den View zurück

Plugin¶

Das Plugin ist die kleine Schwester der Komponente. Die Komponente wird über einen HTML-Import eingebunden, wohingegen ein Plugin als einfaches Javascript-Datei eingebunden wird. Für die Integration eines Plugins kann die Methode Alvine.Package.importScripts(url) verwendet werden.

Ein eigenes Plugin selber kann folgendermaßen umgesetzt werden.


function MyPlugin(options) {
    this.init('MyPlugin', options);
}
MyPlugin.prototype = new Alvine.Package.Plugin();
MyPlugin.prototype.constructor = MyPlugin;

plugin = new MyPlugin({myoption:true});

Objektreferenz¶

Plugin(options)

Beschreibung

Das Plugin-Objekt ist von Alvine.Types.Map abgeleitet und implementiert zentrale Funktionen für ein Plugin.

Parameter-Liste

options (Object)

Optionen des Plugins als Objekt

Rückgabewert

Gibt neues Objekt zurück

Sequenzdiagramm¶

Sequenzdiagramm

Extension¶

Eine Erweiterung erweitert die Tagstruktur. Diese Funktionalität ist auf Grund der aktuell fehlenden Browserunterstützung noch nicht implementiert.