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"
            }
        ]
    }
};