Dokumentation: xw-browse-API

Das Hilfsplugin "xwctrl" dient zur Initialisierung der xw-browse, sowie – wenn es ohne Parameter verwendet wird – zum Zugriff auf das xw-browse-API.

Initialisierung der xw-browse am Platzhalter (hier: <div id="idbrowse"/>):
$("#idbrowse").xwctrl( { ctrlType: "browse", ... } );

Parameter (Properties des Initialisierungs-Objects):

• ctrlType (Type: String)
  Hier muss für die xw-browse stets der String "browse" übergeben werden.
• rows (Type: jQuery)
  Darzustellende Browse-Zeilen als XML-Elemente, gekapselt in einem jQuery-Object; jedes XML-Element repräsentiert eine Zeile. Die Rohdaten für die Zellen einer Zeile können als Attribute des XML-Zeilenelements und/oder als dessen direkte Kindelemente enthalten sein. Der volle Funktionsumfang des API ist jedoch nur nutzbar, wenn die Werte in Kindelementen enthalten sind. Die Zuordnung der Zellen zu den Spalten erfolgt durch die XML-Meta-Beschreibung (siehe Property "meta"). Spezialfälle (z.B. mehrere Attribute/Kindelemente in einer Zelle oder Darstellung spezieller Werte durch Grafiken) können über eine eigene Formatierungsfunktion realisiert werden (siehe Property "formatter"), ebenso Formatierungen, die nicht durch die Verwendung der Standarddatentypen in der XML-Meta-Beschreibung abgedeckt werden.
• meta (Type: jQuery)
  Metainformationen über die Zeilen (Property "rows") als XML, gekapselt in einem jQuery-Object; mit "meta" wird beschrieben, wie die Werte in "rows" durch die xw-browse zu behandeln sind. Ein Beispiel findet sich im Element "xw-meta" in der Tab "XML" zu Demo 1.

  Das in "meta" gekapselte Element (dessen Elementname keine Rolle spielt) kann die Metainformationen in den folgenden direkten Kindelementen definieren (in Klammern wird jeweils die Kardinalität angegeben):

  col-Elemente (1-n)

  Beispiel:

  <col dt="int" grp="false" h="ID" s="pk"/>
  <col dt="date" h="Beginn" s="startdate"/>

  Die col-Elemente beschreiben die Spalten der Browse, sowie deren Reihenfolge. Folgende Attribute werden ausgewertet:

  • dt (Type: string, Default: string)
    Angabe des Datentyps der Spaltenwerte; wird als formatter "xw.format" verwendet, werden die Standarddatentypen ausgewertet.
  • grp (Type: bool, Default: true)
    Angabe für Spalten mit numerischen Werten, ob die Ziffern der Werte gemäß der aktuellen Lokalisierung gruppiert werden sollen (z.B. Tausenderpunkte wie in "1.000.000" bei deutschem Locale).
  • scale (Type: int, Default: 2)
    Angabe für Spalten mit Fließkommawerten: Anzahl der Nachkommastellen.
  • h (Type: string)
    Spaltenüberschrift; wird die Notation ":resourcenGruppe:resource" verwendet, wird als Überschrift eine in Javascript hinterlegte Resource verwendet (siehe "Internationalisierung").
  • s (Type: string)
    Ein einfacher Selektor, um den Spaltenwert innerhalb der XML-Zeile zu selektieren. Möglich sind nur die Angabe des Namens des direkten Kindelements der Zeile, das den Zellenwert als Textknoten beinhaltet oder – wenn der gewünschte Wert ein Attribut des XML-Zeilenelements ist – die Angabe des Attributnamens mit vorangestellten "@"-Präfix (z.B. "@attname"). Andere Selektoren sind nicht zulässig. Sofern kein zusätzliches Attribut "class" im col-Element angegeben wird, wird der in "s" angegebene string außerdem auch als CSS-class-name für die Spalte verwendet, um z.B. über CSS die Spaltenbreite festzulegen.
  • class (Type: string, Default: {Wert aus Attribut "s"})
    Soll nicht "s" als CSS-class-name für die Spalte (für jede in der Spalte enthaltene Zelle und die Spaltenüberschrift) verwendet werden, kann hier ein abweichender CSS-class-name angegeben werden.

  sort-Elemente (0-2)

  Beispiel:

  <sort ascending="false" s="startdate"/> 

  Die (optionalen) sort-Elemente geben an, wie die XML-Zeilenelemente sortiert sind, damit die Sortierpfeile nach der Initialisierung korrekt gesetzt werden können. Bis zu zwei sort-Elemente sind erlaubt, um eine max. zweistufige Sortierung auszudrücken. Wird der xw-browse bei der Initialisierung "initialSort: true" mitgegeben, wird die Browse initial gemäß der sort-Elemente sortiert. Ansonsten wird aus Optimierungsgründen davon ausgegangen, dass die Zeilen bereits korrekt sortiert vorliegen (weil sie z.B. serverseitig bereits mittels SQL "order by" sortiert wurden).
  Folgende Attribute werden ausgewertet:

  • s (Type: string)
    Angabe des Selektors zum Zugriff auf einen Spaltenwert (siehe col-Elemente). Der im entsprechenden col-Element (das mit demselben Selektor) angegebene Datentyp wird für die Sortierung berücksichtigt.
  • ascending (Type: bool, Default: true)
    Sortierung aufsteigend?
  • cs (Type: bool, Default: false)
    Groß-/Kleinschreibung beachten ("case sensitive")?

  key-Elemente (1-n)

  Beispiel:

  <key s="pk"/>

  key-Elemente beschreiben einen (ggf. mehrsegmentigen) Schlüssel, über den eine Zeile eindeutig identifiziert werden kann. Das Feature wird verwendet, um das Ergebnis der API-Funktion selKeys() zu liefern (also die Schlüssel der durch den Benutzer selektierten Zeilen). Alternativ können die selektierten Zeilen auch über die API-Funktion selElements() abgerufen werden, die komplette XML-Zeilen liefert. Keys sind insbesondere wichtig, wenn die "entity-Events" für "Business Entities" verwendet werden sollen (siehe hierzu auch Property "datatype" und "Business Entities" unten).

  Das Attribut "s" im key-Element ist – anders als bei den sort-Elementen – ein einfacher Selektor, der wie der Selektor für col-Elemente arbeitet. Die keys dürfen – müssen aber nicht – als Spalten über die col-Elemente definiert sein, d.h. sie müssen nicht zwangsweise in der xw-browse sichtbar sein.

  Die xw-browse verwendet den Selektor "s" auch als Namen für den key. Der Name muss als javascript-Property-Name verwendbar sein. Ist der Selektor dazu ungeeignet oder wird ein abweichender Name gewünscht, kann der Name über ein Attribut "name" gesondert angegeben werden.

• datatype (Type: string)
  

  Optional: Setzen eines Entity-Datentyps. Hierdurch reagiert die xw-browse auf Events "entities-deleted" und "entity-updated", löscht oder aktualisiert also enthaltene rows, wenn das entsprechende Event eintrifft.

  Der übergebene Name des Datentyps muss als CSS-class-name verwendbar sein, da er (mit dem Präfix "xw-datatype-") dem CSS-class-Attribut der xw-browse (dem HTML-Platzhalter-DIV) hinzugefügt wird.

  Siehe hierzu auch "Business Entities" unten.

• selectFirstRow (Type: bool, Default: true)
  Soll die erste Zeile der xw-browse nach der Initialisierung selektiert sein?
• initialSort (Type: bool, Default: false)
  Soll die xw-browse bei der Initialisierung sortiert werden, wenn die Metabeschreibung sort-Elemente enthält? Standardmäßig wird nicht sortiert, weil in vielen Fällen die Sortierung bereits serverseitig beim Erzeugen der Zeilen über SQL erfolgt.
• singleSelection (Type: bool, Default: false)
  Soll die xw-browse auf die Selektion einzelner Zeilen beschränkt sein? Mit "false" wird die Selektion mehrerer Zeilen erlaubt.
• browseResizable (Type: bool, Default: true)
  Soll die xw-browse mit der Maus in der Größe verändert werden können? Wenn "true", kann mit Ziehen an rechter und unterer Kante, sowie an der rechten unteren Ecke die Größe geändert werden. Setzt jQuery UI-Plugin "Resizable" voraus.
• colsResizable (Type: bool, Default: true)
  Sollen die Spalten in der Breite durch Ziehen mit der Maus veränderbar sein? Setzt jQuery UI-Plugin "Resizable" voraus.
• colsSortable (Type: bool, Default: true)
  Sollen die Spalten per Drag and Drop der Spaltenüberschrift verschoben werden können ? Setzt jQuery UI-Plugin "Sortable" voraus.
• extraSpaceVertScroll (Type: bool, Default: true)
  Die Breite der xw-browse wird automatisch berechnet. Soll hierbei Zusatzplatz für eine mögliche vertikale Scrollbar geschaffen werden?
• maxRowsPerPage (Type: int, Default: 15)
  Die Höhe der xw-browse wird bei der Initialisierung und beim Hinzufügen von Zeilen berechnet. maxRowsPerPage gibt an, ab welcher Zeilenanzahl die xw-browse nicht mehr wächst sondern stattdessen eine vertikale Scrollbar eingefügt wird.
• brwsMinWidth (Type: int, Default: 40)
  Mindestbreite der xw-browse in Pixel, bis zu der höchstens verkleinert werden kann.
• brwsMinHeight (Type: int, Default: 47)
  Mindesthöhe der xw-browse in Pixel, bis zu der höchstens verkleinert werden kann.
• attribNameSel (Type: string, Default: "xwuisel")
  Das Merken der Zeilenselektionen wird intern in einem Attribut direkt in den XML-Zeilen vermerkt. Für den unwahrscheinlichen Fall, dass der Name des Attributs mit einem gleichnamigen Datenattribut der Zeilen kollidiert, kann der Attributname hier geändert werden.
• tabIndex (Type: int, Default: 0)
  Setzt das HTML-Attribut "tabindex" für die xw-browse. Der tabindex regelt die Reihenfolge der Fokussierung, wenn mit der Tabulatortaste zum nächsten HTML-Element gewechselt wird.
• connectButtons (Type: bool, Default: false)
  Soll die xw-browse bei der Initialisierung mit den Buttons verbunden werden, die im Rahmen einer HTML-Button-Browse (siehe Demo 2 "Button-Browse") definiert wurden? Wenn true, werden die Buttons vorbereitet, auf die Events "xwSelChanged" und "xwDoStdButton" (siehe "Events") der Browse zu reagieren, d.h. beim Wechsel der Selektion wird der Enabled-Status der Buttons neu berechnet/gesetzt und ein Doppelklick auf eine Browsezeile simuliert einen anschließenden Klick auf den ersten der Buttons (sofern dieser aktiv ist). Wenn true, wird "xwSelChanged" bereits bei der Initialisierung der Browse getriggert, um den Enabled-Status der Buttons zu diesem Zeitpunkt korrekt zu setzen. Als Buttons werden bereits initialisierte jQuery UI-Buttons vorausgesetzt. Sollen andere Buttons verwendet werden, kann das Object xw.buttonState durch ein geeignetes Object ersetzt werden.
• formatter (Type: function)
  Return: string|null
  Funktion zur Formatierung der Zellenwerte; um mit den Standarddatentypen arbeiten zu können, muss formatter auf die Funktion "xw.format" gesetzt werden (siehe Bibliothek xw.js) oder eine eigene Funktion mit entsprechender Funktionalität.
  Wird kein Formatter gesetzt, werden die Rohdaten der XML-Zeilen in der xw-browse dargestellt.

Die Properties ctrlType, rows und meta sind Pflichtangaben. Die Angabe eines formatters ist optional; für den Umgang mit Standarddatentypen muss der formatter "xw.format" verwendet werden (siehe Demo) oder als Grundlage eines eigenen formatters dienen.

In der meta-Beschreibung kann pro Spalte ein Datentyp (Attribut "dt" in col-Elementen) angegeben werden. Dies dient – im Zusammenspiel mit der Lokalisierung – einer korrekten Formatierung der Rohdaten, sowie der richtigen Sortierung. Die "Standarddatentypen" sind hier dokumentiert und werden durch den formatter xw.format und die interne Sortierung interpretiert.

Die xw-browse kann global lokalisiert werden, indem ein locale-Object wie folgt gesetzt wird:

xw.locale = { 
  name: "de", 
  currency: "\u20AC", 
  decimalSep: ",",
  decimalGroup: ".",
  dateOrder: [2, 1, 0],
  dateSep: ".",
  bool: ["nein", "ja"]
};

Standard ist das englische Locale mit Währung EURO; Die Währung spielt allerdings für die xw-browse keine Rolle.

xw.locale = { 
  name: "en",
  currency: "\u20AC",
  decimalSep: ".",
  decimalGroup: ",",
  dateOrder: [1, 2, 0],
  dateSep: "/",
  bool: ["no", "yes"]
};

Für die xw-browse steuert das aktive Locale, wie die Standarddatentypen formatiert werden.

Für mehrsprachige Sites gibt es einen Mechanismus, Resourcen (Texte) in der gerade aktiven Sprache mit Javascript zu hinterlegen; die Texte werden hierbei in Resourcengruppen organisiert:

xw.i18n.brwsHeader = { 
  number: "nummer",
  course: "Kurs",
  fee: "Gebühr €"
};

Die xw-browse kann Resourcen für Spaltenüberschriften verwenden, indem in den Metainformationen zu den Spalten die Notation ":resourcenGruppe:resource" verwendet wird:

<col dt="int" grp="false" h=":brwsHeader:number" s="pk"/>
<col h=":brwsHeader:course" s="name"/>
<col dt="money" h=":brwsHeader:fee" s="fee"/> 

Um Problemen mit Sonderzeichen aus dem Weg zu gehen, sollten die Resourcengruppen in <script>-Tags direkt in der HTML-Seite mit derem "charset" hinterlegt werden. Am unproblematischsten ist erfahrungsgemäß der flächendeckende Einsatz des charset "utf8".

Um die Anwendung des Mechanismus' zu verhindern (weil die Überschrift tatsächlich mit einem Doppelpunkt beginnen soll), ist der erste Doppelpunkt zu verdoppeln ("::brwsHeader:number" wird also nicht durch eine Resource ersetzt, sondern setzt den Text ":brwsHeader:number" als Überschrift).

Resourcengruppen können natürlich auch in eigenem Code verwendet werden; der Zugriff auf eine Resource erfolgt über den Aufruf:

var myText = xw.i18n.resolve(":brwsHeader:number");

Wird der Funktion "resolve" ein String übergeben, der nicht der Notation entspricht, wird der übergebene String zurückgegeben.

Das API ist ein "plain object", dessen Properties Funktionen sind, die im Folgenden beschrieben werden. Der Zugriff auf das API (hier für den Browse-Platzhalter <div id="idbrowse"/>) erfolgt nach der Initialisierung mit
var browseApi = $("#idbrowse").xwctrl();

Am API sind dann die folgenden Funktionen aufrufbar:

• cloneRows (Type: function)
  Return: jQuery
  Erzeugt eine Kopie aller enthaltenen XML-Zeilen und gibt diese, gekapselt in einem jQuery-Object, zurück. Evtl. in den XML-Zeilen enthaltene Selektionsattribute werden in der Kopie entfernt.
• colMeta (Type: function)
  Return: object-array
  Liefert die Metainformation der Spalten in einem Array von "plain objects"; die Objekte enthalten neben den bei der Initialisierung mitgegebenen Spalteninformationen (siehe col-Elemente) zusätzlich die aktuelle Spaltenbreite in Pixel im Property "width".
• deleteRows (Type: function)
  

  Löscht die Zeilen, die den keys im übergebenen key-array entsprechen.

  Die Spaltenwerte der XML-Zeilen müssen in Kindelementen der Zeilen enthalten sein, nicht in Attributen.

  Parameter:

  • key (Type: object-array)
    Array von "plain objects" mit key-value-Paaren, nach denen gesucht werden soll, z.B. [{ pk: "7" }, { pk: "12" }]; die Werte müssen als "string" enthalten sein.
• deleteSelected (Type: function)
  Löscht die in der Browse selektierten Zeilen.
• findRow (Type: function)
  Return: jQuery|null
  

  Sucht die (erste) zum übergebenen key passende XML-Zeile und gibt diese, gekapselt in einem jQuery-Object, zurück. Wird keine passende Zeile gefunden, wird null zurückgegeben.

  Die Spaltenwerte der XML-Zeilen müssen in Kindelementen der Zeilen enthalten sein, nicht in Attributen.

  Parameter:

  • key (Type: object)
    "plain object" mit key-value-Paaren, nach denen gesucht werden soll, z.B. { pk: "7"}; die Werte müssen als "string" enthalten sein.
• insertRows (Type: function)
  

  Fügt (mehrere) neue Zeilen, ggf. einsortiert, hinzu. Ein Beispiel finden Sie im Demo.

  Parameter:

  • r (Type: jQuery)
    Die neuen XML-Zeilen, gekapselt in einem jQuery-Object.
  • selFilter (Type: {jQuery-filter-parameter})
    

    Optional: gibt an, welche Zeilen der Browse nach dem Einfügen selektiert werden sollen. selFilter wird an die jQuery-Funktion "filter" übergeben, um die zu selektierenden Zeilen zu finden (rows().filter(selFilter)).

    Um einen einfachen Filter für die Suche nach XML-Zeilen mit einem bestimmten Spaltenwert zu bilden, hilft die Funktion xw.filter(), z.B. xw.filter("pk", "7") liefert den Filter zum Suchen nach Zeilen, die in Spalte "pk" den Wert "7" enthalten.

• jqItem (Type: function)
  Return: jQuery
  Liefert das jQuery-Object, das die xw-browse kapselt (im Beispiel ist das $("#idbrowse")).
• optimalWidth (Type: function)
  Berechnet die Browse-Metrik bzgl. optimaler Breite von Browse und horizontalen Scrollbereich neu. Wird hauptsächlich intern verwendet, einziger derzeit bekannter externer Anwendungsfall ist:
  Die xw-browse bzw. der sie enthaltende Bereich kann versteckt sein und wird sichtbar gemacht (z.B. in einem Tab-Panel). Solche Panels sollten bei Aktivierung also die Funktion für alle enthaltnen xw-browses aufrufen:
  panel.find(".xw-browse").each(function () { $(this).xwctrl().optimalWidth() });
  Grund ist, dass beim Zoomen des Browserfensters (z.B. mit Tasten Ctrl-"+"/"-") die Breite der Scrollbars ungleichmäßig verändert werden, was zu einer nicht optimalen Darstellung führen kann.
• redraw (Type: function)
  Zeichnet die Browsezeilen neu (um z.B. Änderungen in den rows zu reflektieren).
• replaceRows (Type: function)
  

  Ersetzt die XML-Zeilen der Browse durch die übergebenen XML-Zeilen. Anschließend wird die Browse ggf. sortiert.

  Parameter:

  • r (Type: jQuery)
    Die neuen XML-Zeilen, gekapselt in einem jQuery-Object.
• rows (Type: function)
  Return: jQuery
  Liefert alle XML-Zeilen (keine Kopie), gekapselt in einem jQuery-Object.
• selAll (Type: function)
  Selektiert alle Zeilen der Browse, sofern Mehrfachselektion zugelassen wurde.
• selElements (Type: function)
  Return: jQuery
  Liefert die selektierten XML-Zeilen (keine Kopie), gekapselt in einem jQuery-Object.
• selKeys (Type: function)
  Return: object-array
  Liefert die keys der selektierten Zeilen als Array von "plain objects". Um diese Funktion nutzen zu können, müssen in den Metainformationen die key-Elemente definiert worden sein. Der dort angegebene Name (bzw. Selektor) wird jeweils als Property-Name in den plain objects verwendet, z.B. wird [{pk: "3"}, {pk:"7"}] zurückgegeben, wenn ein einzelner key namens "pk" definiert wurde und die Zeilen mit pk=="3" und pk=="7" selektiert sind. Die Properties sind stets vom Javascript-Type "string".
• setInnerWidth (Type: function)
  

  Setzt die innere Breite (die Breite des Scrollbereichs) der Browse.

  Parameter:

  • brWidth (Type: int)
    Breite in Pixel
• setLocalStyle (Type: function)
  

  Setzt eine lokale CSS-Eigenschaft, die nur für diese Browse gilt (ein HTML-style-Element wird innerhalb des Browse-HTML eingefügt; dem Selector wird die Browse-ID vorangestellt; hat der Browse-Platzhalter keine ID, wird eine eindeutige ID erzeugt).

  Parameter:
  • selector (Type: CSS-Selector)
    Ein CSS-Selector, dem (gedanklich) die Browse-ID vorangestellt wird.
  • sdef (Type: string)
    Style-Definition(en)

  Beispiel: Wurde für diese xw-browse in den Metainformationen für eine Spalte die CSS-Klasse "startdate" definiert, bewirkt ein Aufruf von

  browseApi.setLocalStyle(".startdate", "width: 60px");

  das Einfügen der CSS-Eigenschaft "#idbrowse .startdate {width: 60px}" in das style-Element innerhalb der Browse (hiermit wird die Spaltenbreite gesetzt). Ein erneutes Setzen eines styles überschreibt einen evtl. bereits vorhandenen style mit demselben Selektor.

• setSelRowsVal (Type: function)
  

  Setzt in allen selektierten Zeilen den übergebenen Wert in der angegebenen Spalte. Die Spaltenwerte der XML-Zeilen müssen in Kindelementen der Zeilen enthalten sein, nicht in Attributen.

  Parameter:

  • el (Type: string)
    Name des XML-Zeilen-Kindelements, in denen jeweils der Spaltenwert ersetzt werden soll. Existiert dieses Kindelement noch nicht, wird es erstellt.
  • val (Type: string)
    Der zu setzende neue Spaltenwert.
  • opt (Type: object)
    Optional: "plain object", dessen Properties ein abweichendes Verhalten steuern können:
    • toggleBoolIfSingle (Type: bool, Default: false)
      Nur für Spalten vom Typ "bool": wird { toggleBoolIfSingle: true } übergeben und ist genau eine Zeile selektiert, wird der Parameter "val" nicht ausgewertet. Stattdessen wird der aktuelle Wert gelesen und invertiert (wenn der aktuelle Spaltenwert "true" ist, wird er auf "false" gesetzt, sonst auf "true").
    • splitLines (Type: bool, Default: false)
      Nur für Spalten vom Typ "string" mit potenziell mehrzeiligen Inhalt. Wird { splitLines: true } übergeben, werden ggf. in "val" enthaltene Newlinezeichen ("\n") ausgewertet und der Wert in mehreren "line"-Kindelementen als Spaltenwert eingestellt. Vgl. hierzu xw.select() mit Option "allLines=true".
• sort (Type: function)
  Sortiert die Browse gemäß der aktuellen Sortiereinstellung.
• unselAll (Type: function)
  Deselektiert alle Zeilen der Browse.

Die folgenden Events werden von der xw-browse getriggert:

• xwSelChanged
  Die Selektion wurde geändert. Das Event wird auch nach der Initialisierung getriggert, wenn die xw-browse mit "connectButtons:true" initialisiert wurde.
• xwDoStdButton
  Eine Zeile wurde doppelt geklickt (wodurch sie auch selektiert wurde) oder es wurde die Return-Taste gedrückt und mindestens eine Zeile ist selektiert. Wenn die xw-browse mit "connectButtons:true" initialisiert wurde, wird das Event von der xw-browse selbst ausgewertet, indem für den ersten Button der Browse "click" getriggert wird (sofern der Button "enabled" ist).
• xwMenu
  

  Auf einer selektierten Zeile wurde das Contextmenu ausgelöst (rechte Maustaste). Für nicht selektierte Zeilen wird kein Event getriggert, das Contextmenu des Browsers wird in diesem Fall regulär angezeigt.

  Im Event-Handler mit den Parametern (e, browse, li) kann auf die (in einem jQuery-Object gekapselte) XML-Zeile mit

  var row = li.data("xd");

  zugegriffen werden.

Mit "Business Entities" sind Datensätze (rows) gemeint, die mit einem bestimmten Datentyp (z.B. "kunde") gekennzeichnet sind und über eindeutige Schlüssel (keys) verfügen.

Der xw-browse kann bei der Initialisierung im Property "datatype" der Name eines Entity-Datentyps mitgegeben werden; hierdurch wird festgelegt, dass die enthaltenen rows diesem bestimmten Datentyp entsprechen. Bei eintreffenden Events über gelöschte oder aktualisierte Datensätze reagiert die xw-browse automatisch durch Löschen von Zeilen bzw. Aktualisieren einer Zeile. Zum Identifizieren betroffener rows ist es erforderlich, in den Metainformationen zur xw-browse eindeutige keys zu definieren (siehe Initialisierung, Property "meta").

Hier finden Sie weitere Informationen zu Business Entities.