Util

Unter dem Namespace Util finden sich verschiedene Hilfsfunktionen.

getDomPath

Die Methode Alvine.Util.getDomPath() gibt einen Pfad auf ein Dom-Element zurück, der für jQuery als Selektor benutzt werden kann. Als Parameter kann entweder ein Selektor, ein Dom-element oder ein jQuery-Objekt übergeben werden.

<div>
   <p>Hallo World!</p>
</div>

// Dom Element referenzieren
element = jQuery('div > p').get(0);

// Dom-Path
path = Alvine.Util.getDomPath(element);
// -> body > div:nth-child(1) > p:nth-child(1)

// Referenzieren
ref = jQuery(path);
// (ref === element) === true

Logger

Mit Hilfe des Loggers können schnell und einfach Funktionen analysiert und Fehler ermittelt werden. Eine Logmeldung wird mit Hilfe einer der folgendne Funktionen geschrieben:

Alvine.Util.Logger.logFatal('my fatal');
Alvine.Util.Logger.logError('my error');
Alvine.Util.Logger.logWarn('my warn');
Alvine.Util.Logger.logInfo('my info');
Alvine.Util.Logger.logDebug('my debug');
Alvine.Util.Logger.LogTrace('my trace');

Als Best-Practise Ansatz sollte man als erstes Argument immer das Modul oder die Funktion übergeben. Damit ist es dann sehr leicht die Meldungen über die Konsole zu filtern.

Alvine.Util.Logger.logDebug('alvine.types.string', 'my message');

Nach dem Aufruf einer dieser Funktionen wird zuerst keine Meldung ausgegeben. Erst wenn man den Trashold entsprechend setzt werden Meldungen ausgegebn. Der Trashold kann über eine der folgenden Funktionen gesetzt werden:

Alvine.Util.Logger.setAll();
Alvine.Util.Logger.setFatal();
Alvine.Util.Logger.setError();
Alvine.Util.Logger.setWarn();
Alvine.Util.Logger.setInfo();
Alvine.Util.Logger.setDebug();
Alvine.Util.Logger.setTrace();
Alvine.Util.Logger.setOff();

Die einzelnen Level schließen immer die darunterliegenden Level ein. So wird mit einem Trashold auf WARN auch alle Errors und Fatals angeteigt. KeineMeldungen erhält man demnach mit dem Trashold Off. Die Reihenfolge der Auswertung ist folgendermassen

ALL > TRACE > DEBUG > INFO > WARN > ERROR > FATAL > OFF

Der Loglevel kann auch über die URL des Browsers gesetzt werden. Hierzu muss der Parameter loglevel im Hash-Teil der URL gesetzt sein. http://example.com/#loglevel=ALL. Der Wert wird als Zeichenkette übergeben.

Außerdem kann der Loglevel per Cookie gesetzt werden. Dazu muss ein Cookie mit dem Namen loglevel geschrieben werden.

Wird ein Loglevel über die URL oder per Javascript gesetzt, so wird dieser immer auch als Cookie mit dem Namen loglevel gespeichert. Damit bleibt der Loglever auch für zukünftige Aufrufe aktiv.

Standardmässig werden die Logmeldungen immer über das Consolenobjekt ausgegeben. Diese wird bereits beim Laden des Frameworks mit Hilfe der addConsoleHandler() aktiviert.

 Alvine.Util.Logger.addConsoleHandler();

Alternativ kann man die Logmeldungen auch an eine URL per POST senden. Dazu muss ein Ajax-Handler definiert werden.

Alvine.Util.Logger.addAjaxHandler('http://example.com/logging');

eigene Loghandler lassen sich ebenfalls einfach hinzufügen. Dazu muss nur das log-Event mit den gewünschten Namespaces beobachtet werden. Im folgenden Beispiel werden alle Logmeldungen abgefragt.

jQuery(window).on('log.TRACE.DEBUG.INFO.WARN.ERROR.FATAL', function () {
    // 
})

Möchte man nur FATAL-Fehler bekommen, so reicht es den Namespace auf log.FATAL zu setzen

jQuery(window).on('log.FATAL', function () {
    // 
})

UUID

Die UUID Funktion ermöglicht es eine UUID vom Typ 4 (Random) zu erstellen. Dazu muss einfach nur durch den Konstruktor ein neues UUID-Objekt erstellt werden.

// Neues UUID-Objekt
uuid = new Alvine.Util.UUID()
uuid.toString()
// -> "f49dc92c-1ac5-4f45-84bc-2645fce5a14a"

getEscapedIDSelector

Ids die eines der Sonderzeichen [ . [ ] , = enthalten, können im DOM nicht direkt selektiert werden. Die Sonderzeichen im Selektor müssen vorher mittels dieser Funktion escaped werden. Die Id erhält zudem gleich den ID-Seletor-Prefix #. Dieses Verhalten kann über den zweiten Parameter deaktivert werden.

Alvine.Util.getEscapedIDSelector('a[b]');
// -> #a\[b\]

// Ohne Hash
Alvine.Util.getEscapedIDSelector('a[b]', false);
// -> a\[b\]

Wird kein oder eine fehlerhafte ID übergeben, so wird eine Exception geworfen.

getEscapedIDSelectorOrRandom

Die Funktion getEscapedIDSelectorOrRandom ist ein Wrapper für die Funktion getEscapedIDSelector. Der Wrapper fängt die Exceptions ab, wenn keine ID übergeben wird und liefert dafür eine zufällige ID. Dies ist sinnvoll, wenn mann sich nicht sicher istm ob ein Objekt eine ID besitzt.

containsStringSetAValue

Die Methode Alvine.Util.containsStringSetAValue(string, searchValue, delimiter) prüft in einer Zeichenkette auf vorhandenseins eines Wertes. Dies ist typischerweise zur Prüfung auf Klassennamen anzuwenden.

Alvine.Util.containsStringSetAValue('btn btn-primary', 'btn-primary');   // true
Alvine.Util.containsStringSetAValue('btn btn-primary', 'btn-scondary'); // false

addValueToStringSet

Die Methode Alvine.Util.addValueToStringSet(string, valueToAdd, delimiter) fügt einen Wert in einer Zeichenkette hinzu. Dies ist typischerweise zur Bearbeitung von Klassennamen anzuwenden.

Alvine.Util.addValueToStringSet('btn btn-primary', 'text-right');   // -> btn btn-primary text-right
Alvine.Util.addValueToStringSet('abc def', 'geh def') // -> abc def geh

removeValueFromStringSet

Die Methode Alvine.Util.removeValueFromStringSet(string, valueToRemove, delimiter) fügt einen Wert in einer Zeichenkette hinzu. Dies ist typischerweise zur Bearbeitung von Klassennamen anzuwenden.

Alvine.Util.removeValueFromStringSet('btn text-right btn-primary', 'text-right');   // -> btn btn-primary
Alvine.Util.removeValueFromStringSet('abc def ghi jkl', 'ghi abc') // -> def jkl

transformValues

Die Funktion Alvine.Util.transformValues() stellt verschiedene Hilfsfunktionen über einen Aufruf bereit. Somit kann ein Wert zentral über eine Funktion bearbeitet und umgewandelt werden. Nachfolgend sind einige Beispiele aufgeführt:

Alvine.Util.transformValues('DaS iST mEin texT.', 'strtolower');
// -> das ist mein text.

Alvine.Util.transformValues('das ist mein text.', 'ucfirst');
// -> Das ist mein text.

Alvine.Util.transformValues('das ist mein text.', 'base64');
// -> ZGFzIGlzdCBtZWluIHRleHQu

Alvine.Util.transformValues('das ist <b>mein</b> text.', 'plaintext');
// -> das ist mein text.

Alvine.Util.transformValues('das ist mein text.', 'prefix:Ja,');
// -> Ja,das ist mein text.

Alvine.Util.transformValues('das ist mein text', 'suffix:!');
// -> Ja,das ist mein text!

Alvine.Util.transformValues('das ist mein text.', 'substring:4:3');
// -> ist

Alvine.Util.transformValues('das ist mein text.', 'static:my static value');
// -> my static value

Über den if-Befehl können auch Abfragen definiert werden, die das erste Argument überprüft. In folgenden Fällen ist das Ergebnis der Prüfung false: undefined, "off", "" (leere Zeichenkette), false und "false" In folgenden Fällen ist das Ergebnis der Prüfung true: Ungleich undefined, "on", true und "true"

Alvine.Util.transformValues(true, 'if:ja:nein');
// -> ja

Alvine.Util.transformValues(false, 'if:ja:nein');
// -> nein

// Mit dem Schlüsselwort value kann der Wert 
// aus dem ersten Argument übernommen werden.
Alvine.Util.transformValues('my value', 'if:value:is empty');
// -> my value

// Will man das Schlüsselwort value verwenden muss 
// es mit einem \\ versehen werden.
Alvine.Util.transformValues('my value', 'if:\\value:is empty');
// -> value

Alvine.Util.transformValues('my value', 'if:value:is empty');
// -> is empty

Info

Diese Funktion kommt beim Form-Objekt und Template-Objekt zum Einsatz.

Der Funktionsaufruf bietet die Möglichkeit über einen Callback eigene Funktionen zu implementieren. In diesem Beispiel gibt die Funktion beim Aufruf mit dem Befehl mycommand den Wert myvalue zurück.

Alvine.Util.transformValues('Hans Mustermann', 'mycommand', function (command, args) {
        if (command === 'mycommand') {
            return 'myvalue';
        }
    });

// -> myvalue

Folgende Befehle sind verfügbar:

Anweisung Alias Argumente Beschreibung Beispiel
base64 Base64
call Aufruf einer Callbackfunktion. Die Funktion kann an drei Stellen definiert sein: entweder global, im Kontext context.Operation oder im übergeben Objekt call:myfunction,param1:param2:...
count Anzahl der Einträge in einer Map oder Collection
empty Leere Zeichenkette
htmlspecialchars HTML-Sonderzeichen nach Entities
i18n Lokalisierung; der Wert wird als Schlüssel in der Registry unter Alvine.Registry.get('Locale') gesucht
if ? true:false Ist der ternary Operator, der erste Parameter ist der True, der zweite der False-Teil. Um den aktuellen Wert in der Queue zu verwenden, kann man das Schlüsselwort value setzen. Will man hingegen die statische Zeichenkette "value" haben, so muss man einen  davorstellen und value schreiben. dataset:myIndex
index ruft .get() oder .getIndex() einer Map oder Collection auf index:myIndex
intval Integer
length Länge der Zeichenkette
logger Der Wert wird in der Console ausgegeben; es erfolgt keine Bearbeitung. Als Parameter kann der Loglevel (trace) übergeben werden. Wird kein Loglevel übergeben, so wird console.log verwendet.
nop Keine Operation; Wert wird einfach weitergegeben
plaintext Alle HTML-Tags werden entfernt
prefix Nachsilbe
property wird ein Javascript-Objekt übergeben, so wird die Eigenschaft - oder falls nicht vorhanden, der defaultValue - zurückgegeben. property:myProperty
rawurlencode URL-Codierung
registry Liest einen Wert aus der Registry aus registry:myvalue
static content Der Wert Arguments wird verwendet und an den Wert. Sonderzeichen \ <space> und : können durch ein vorangesteltes \ gequotet werden static:helloworld
strtolower Der Eingangswert wird in Kleinbuchstaben umgewandelt
strtoupper Der Eingangswert wird in Großbuchstaben umgewandelt
substring start:length Teilzeichenkette von start length-Zeichen substring:10:5
suffix Vorsilbe
tointeger Typumwandlung in einen Integerwert; wenn nicht möglich ist der Wert undefined
tostring Typumwanlung in eine Zeichenkette
trim Leerzeichen am Anfang und Ende entfernen
ucfirst Erstes Zeichen groß
ucwords Jeder Wortanfang groß
undefined Der undefined Wert
uniqid Eindeutige temporäre ID

Funktionsreferenz

Alvine.Util.transformValues(value, command, callback)

Beschreibung

Diese Funktion wandelt den übergebenen Wert value mittels definiertem Befehl um. Über den optionalen Callback können eigene Befehle definiert werden.


Parameter-Liste

value (Mixed)

Zu bearbeitender Wert

command (String)

Befehl mit optionalen Argumenten, die durch einen Doppelpunkt getrennt sind: command:arg1:arg2:arg3:... Die Befehle können der Tabelle entnommen werden.

callback (Function)

Callbackfunktion zur Implementierung eigener Befehle. Die Callback-Methode muß einen Wert zurück geben. function (command, args) { return returnValue };


Rückgabewert

Gibt das Ergebnis des Befehls zurück.

getInstanceFromDataset

Die Funktion getInstanceFromDataset liefert von einem Dataset eine Instance zurück. Wichtig ist das das Objekt das mit name Definiert wurde auch die Mehtode getInstanceFromDataset implementiert hat.

var json = {
    "name": "Alvine.UI.Control",
    "dataset": {
        "options": {}
    }
};
var instance = Alvine.Util.getInstanceFromDataset(window, new Alvine.DOM.Dataset(Json))

Mit dem Schlüssel call wird eine Globale Mehtode aufgerufen die eine Instance zurück liefern muss. In diesem Beispiel liefert die Methode Alvine.myFunction das Objekt Alvine.Types.Map zurück

Alvine.myFunction = function(){
    return new Alvine.Types.Map();
}
var json = {
    "call": "Alvine.myFunction",
}
var instance = Alvine.Util.getInstanceFromDataset(window, new Alvine.DOM.Dataset(Json))

Ein komplettes Beispiel

var json = {
    "name": "Alvine.Package.UI.Dialog.Form",
    "dataset": {
        "options": {},
        "controls": [
            {
                "name":"Alvine.Package.UI.Dialog.Input",
                "dataset": {
                }
            },
            {   
                "call": "Alvine.getMyControl"
            }
        ]
    }
};