Zum Inhalt

JavaScript in Listen

Einführung

Mit Hilfe der Anwendung CortexUniplex auf Basis der CortexDB sind Sie in der Lage, beliebige Selektionen innerhalb Ihres Datenbestandes durchzuführen und in Form von Listen auszugeben. Die Listenfunktionen bieten Ihnen zudem die Möglichkeit, sog. Sublisten darzustellen, so dass auch rekursive Strukturen abgebildet werden können. Ergänzend dazu sind weitergehende Pivot-Auswertungen und damit verbundene, grafische Darstellungen möglich.

Als Ergänzung und für dynamische Berechnungen zur Laufzeit dienen berechnete Inhalte einer Liste. Das Ergebnis wird hierbei beim Anzeigen der Liste erzeugt und steht nur dort zur Verfügung. Es werden daher keinerlei Datensätze geändert und die berechneten Ergebnisse können somit auch nicht über eine Suche oder eine andere Selektionsart gefunden werden. Die weiterführenden Listen-Funktionen, wie die Pivot-Darstellung und die grafische Auswertung, sind dennoch mit diesen berechneten Feldern möglich. Dadurch können dynamische Berechnungen auf Basis von Listeninhalten durchgeführt und über verschiedene Methoden dargestellt werden.

Mit Hilfe des Import-Werkzeugs ImPlex ist es zudem möglich, dass (bestimmte) berechnete Inhalte in die Datenbank geschrieben werden. Vorhandene Informationen werden somit ergänzt oder geändert und können dann über die Standardmechanismen selektiert und ausgewertet werden.

Hinweis

Die JavaScript-Funktionalität zur Ermittlung von Listeninhalten wird serverseitig ausgeführt, so dass nur das Ergebnis zurückgegeben wird. Dafür wurde die Bibliothek "V8" von Google in der HTTP-Schnittstelle implementiert. Diese muss daher als Datei im Serververzeichnis (und ggf. im HTTP-Server-Verzeichnis) zur Verfügung stehen. Unter Windows ist die Datei "ctxv8.dll" und unter Linux-Systemen "ctxv8.so" notwendig.

Vorgehensweise

Die generelle Vorgehensweise für die erste und grundlegende Einrichtung einer berechneten Liste gliedert sich in drei Schritte:

  1. Listendefinition
  2. Konfiguration der berechneten Felder
  3. Speichern und bereitstellen der Liste

Beachten Sie, dass ein Anwender innerhalb der Liste nur die Spaltenüberschriften sieht und möglicherweise keinerlei Kenntnisse über die berechneten Inhalte besitzt. Daher sollten Sie zum Einen die Funktionen, die Sie zur Berechnung heranziehen, separat in einer Textdatei als Backup speichern. Zum Anderen sollten die Anwender mit Berechtigungen für die Listenbearbeitung darüber informiert werden, dass bei einer Listenänderung ggf. Funktionen für die Berechnung von Inhalten beeinflusst werden können.

Generell gilt, dass innerhalb der Listendarstellung nicht ersichtlich ist, bei welchem Feld es sich um Datensatzfelder oder um berechnete Felder handelt. Über die Formatierung der Spalten können Sie daher ein anderes Textformat für die Anzeige der Ergebnisse wählen (z.B. eine andere Farbe). Dadurch wird den Anwendern die Interpretation der Anzeige vereinfacht.

JavaScript editieren

Je Spalte einer Liste kann über die Spalten-Konfiguration ein JavaScript hinterlegt werden. Hierüber steht im Menü der Liste der Punkt "Scriptübersicht" zur Verfügung.

Version:4.0.60;Date:16.01.2019; Name:Liste.Script.Edit

In dieser Übersicht werden alle Felder der Haupt- und Subliste mit ihren jeweiligen Parametern untereinander aufgeführt. Da jedem Feld ein Javascript zugewiesen werden kann, ist die gleichzeitige Bearbeitung unterschiedlicher Scripte möglich.

Javascript in mehreren Feldern

Scripte sollten, wenn möglich, in separaten Feldern abgelegt werden, da ansonsten der Überblick schnell verloren geht.

In der Scriptübersicht kann der Script-Editor über den entsprechenden Bearbeitungsbutton aufgerufen werden (siehe Screenshot).

Version:4.0.60;Date:16.01.2019; Name:Liste.Script.Overview

Der Editor lässt alle Möglichkeiten von Javascript zu (außer Browser-Funktionen). Wurde ein Script bearbeitet, wird dieses über den Button mit dem Häkchen gespeichert oder die Änderungen werden verworfen.

Speichern von Scripten und Listen

Es ist zu beachten, dass der Scripteditor und auch die Scriptübersicht eigene Häkchen-Buttons besitzen, um die Änderungen zu speichern. Danach ist eine Speicherung der gesamten Liste trotzdem zwingend notwendig. Ansonsten gehen die Anpassungen verloren.


Funktionen für Listen

Datenformate

Zurückgegebene oder zu schreibende Werte müssen folgenden Konventionen entsprechen:

Feldtyp Javascript Datentyp Beispiel / Entsprechung
Zeichen String Freitext
positive Ganzzahl Number 521354
nummerisch mit Nachkommastellen Number 0.02462
Datum String YYYYMMDD
Zeitpunkt String YYYYMMDDHHII

Funktionen

GetListField

Mit GetListField wird der Wert des aktuellen Datensatzes in einer Spalte gelesen. Die Rückgabe erfolgt hierbei immer als Text.

g=GetListField("Gwert");

Parameter

Folgende Parameter können verwendet werden:

  • Spaltenname Name der Spalte aus der Liste oder Leerstring für die aktuelle Spalte. Sollten mehrere gleichnamige Spalten vorhanden sein wird nur die erste beachtet
  • Typenkonvertierung (optional) Konvertierung des Datentyps
    • C - Zeichenfolge
    • I - Ganzzahl
    • N - Nummerisch mit Nachkommastellen
    • J - JSON-Struktur

Rückgabe

Wert der Spalte entsprechend ihres Datentyps laut Listendefinition oder dem der optionalen Typenkonvertierung. Im Falle der JSON-Struktur wird immer ein Array aus Objekten zurückgegeben.

SetListField

Mit SetListField wird der Wert des aktuellen Datensatzes einer Spalte gesetzt.

SetListField("Gwert", 2535.43);

Ausblenden von Spalten

Das vollständige Ausblenden der Spalte erfolgt mit SetListField("Gwert", false);. Hierbei wird nicht das Feld geleert, sondern es wird vom Server nicht zurückgeliefert. Dieses ist ebenso über die UniplexAPI nicht ersichtlich.

Parameter

  • Spaltenname - Name der Spalte aus der Liste oder Leerstring für die aktuelle Spalte. Sollten mehrere gleichnamige Spalten vorhanden sein wird nur die erste beachtet
  • Wert - die zu setzenden Daten
  • Objektmodus - J wenn als Daten ein Objekt oder ein Array von Objekten verwendet werden`

ParseHistory

Mit ParseHistory können die in die Liste gelieferten Verlaufsinformationen in eine verarbeitbare Struktur gebracht werden.

ParseHistory(GetListField(""), "C", 1);

Parameter

  • Parameterfelddaten - Base64-kodierte Parameterfeld-Daten
  • Typenkonvertierung - Konvertierung des Ergebnisses
    • C - Zeichenfolge`
    • I - Ganzzahl`
    • N - Nummerisch mit Nachkommastellen`
  • Zeitpunktformat - (optional) 1 Zeit als String (YYYYMMDDHHII); 0 oder leer Zeit als Integer

Für die Typkonvertierung stehen folgende Kürzel zur Verfügung:

Rückgabe

Array mit Objekten über die Verlaufsinformationen

{
'm'  : 'Z',    // Mode (Z=Zeitscheibe, E=Event, X=aktueller Inhalt wenn es keine Zeitscheiben gibt)
'v'  : 'abc',  // Wert
'ts' :         // Zeit als String, oder 8 Leerzeichen wenn es keine Zeitscheiben gibt
'ti' :         // Zeit als Integer
}

Objektmodus für GetListField und SetListField

Wenn bei GetListField als zweiter Parameter ein J angegeben wird, so werden die Daten immer als Array mit Objekten zurückgegeben. Dies ist vor allem bei Wiederholfeldern und bei der bedingten Zellenformatierung interessant. Der Aufbau ist dabei wie folgt:

{
 'd' => 'Hein',   // Daten
 'w' => '98f4c34' // Wiederhol-Id nur bei Wiederholfeldern
},
//[...]

Dieses Array oder auch nur ein einzelnes Objekt davon kann durch SetListField gesetzt werden, wenn als dritter Parameter J angegeben wurde.

Zellenformatierung

Für Zellenformatierungen sind derzeit folgende Keys vorgesehen die in den Objekten gesetzt werden können. Bei Wiederholfeldern wird jedoch nur die Zellenformatierung des ersten Objektes zur Gestaltung der Zelle verwendet.

Key Bedeutung HTML-Entsprechung Referenz
stc Textfarbe color http://de.selfhtml.org/css/formate/wertzuweisung.htm#farben
sbc Hintergrundfarbe backgroundColor http://de.selfhtml.org/css/formate/wertzuweisung.htm#farben
sta Schriftausrichtung textAlign http://de.selfhtml.org/css/eigenschaften/ausrichtung.htm#text_align
sfw Schriftgewicht fontWeight http://de.selfhtml.org/css/eigenschaften/schrift.htm#font_weight
std Textdekoration textDecoration http://de.selfhtml.org/css/eigenschaften/schrift.htm#text_decoration
sfs Schriftstil fontStyle http://de.selfhtml.org/css/eigenschaften/schrift.htm#font_style

Beispiel färbt Hintergrund der Zelle grün oder rot:

var x = GetListField('Wert', 'J'); // lesen der Wertes als Array mit Objekten
if(x.length > 0) // ist ein Wert vorhanden ?
{
  if(x[0]['d'] < 30)
  {
    x[0]['sbc'] = 'red';
  }
  else if(x[0]['d'] > 70)
  {
    x[0]['sbc'] = '#00FF00';
  }
  SetListField('Wert', x, 'J'); // schreiben des Arrays (hier wäre auch das einzelne Objekt x[0] möglich gewesen, wenn es nicht um Wiederholfelder geht
}`

Bei der Erzeugung von Pdf-Dateien mit HxMakePdfFromJson werden noch folgende Parameter ausgewertet:

Key Bedeutung HTML-Entsprechung Referenz
sfm FilterMode nur fuer mehrzeilige HTML-Texte in Listen 0= kein Filter, 1 aus dem HTML wird alles ausser und entfernt
ssm Split Mode "p" Absatz; "l" Zeile um aus mehrzeilige HTML-Texte in Listen mehrere Zeilen zu generieren
slbc Zeilenhintergrund Hintergrund der gesamten Zeile inkl. Subzeilen. Kann in einem beliebigen Feld gesetzt werden, das ersten Auftreten beendet die weitere Suche
sslbc Sub-Zeilenhintergrund Hintergrund einer Subline. Kann in einem beliebigen Feld gesetzt werden, das ersten Auftreten beendet die weitere Suche

Beispiel:

var fi={};
fi.d=getlistfield("");
fi.sbc="#EFEFEF";
fi.slbc="#EFEFEF";
fi.sslbc="#EFEFEF";
fi.ssm="p";
fi.sfm=1;
setlistfield("", fi,"J");

// togglen der Zeilen mit einem leichten Grau um die Zeilenaufteilung
// zu sehen setvar("togglecolor","#f7f7f7");

Variablen für Werte

Für Werte die über einen Datensatz hinaus gespeichert werden sollen (z.B. für Summenbildung einer Subliste oder ähnlichem) können diese in dem Objekt ctx abgelegt werden.

ctx['temp'] = ctx['temp']++ || 0;`

setvar

Werte die außerhalb von Spalten an den Client zurückgegeben werden soll können über setvar abgelegt werden. Diese finden sich im v-Key des Rückgabe-Objekts wieder. Erlaubt sind nur primitive Variablen.

Es können auch Objekte abgelegt werden!

setvar("pos", 25);

Parameter

  • Name - Name unter dem der Wert gespeichert werden soll.
  • Wert - Wert der gespeichert werden soll

getvar

Werte die im v-Key an den Server geschickt wurden kann man mit getvar wieder auslesen. getvar("pos", 5);

Parameter

  • Name - Name unter dem der Wert gespeichert werden soll.
  • Default-Wert - //optional)// Wert der zurückgegeben wird, sollten keine Daten unter dem Namen gespeichert worden sein

Rückgabe

  • der abgelegte Wert oder der Default-Wert falls angegeben

Vordefinierte globale Variablen

Die folgenden Variablen können mit getvar abgerufen werden.

zgb_sGlobalRelDate globales relatives Verlaufsdatum, falls in der Liste gesetzt|

Die folgenden Variablen können mit setvar gesetzt werden.

  • zgb_aPreSelect Array, dass die Zeilennummern enthält, die vormarkiert werden sollen.

Ausführungszeitpunkt des Scripts

Für jedes Script kann eingestellt werden ob es vor oder nach dem Sortieren ausgeführt werden soll (zusätzlicher Button in der Listenübersicht neben dem Bearbeiten-Button zum Script). Für einen Positionszähler ist es zum Beispiel erforderlich das Script nach dem Sortieren auszuführen.

i=getvar("pos", 5);
setvar("pos", i+10);
SetListField("Pos", i);

Ergibt einen Positionszähler der mit 5 anfängt und in 10er Schritten weiter gezählt wird.

Ausschließen von Datensätzen

Mit setvar("exclude","1"); können Datensätze serverseitig ausgeblendet werden. Diese werden dann nicht zum Client übermittelt.


JavaScript-Einführung

Über ergänzende Literatur, sowie weitere Webseiten ist das Erlernen von JavaScript sehr einfach. Dennoch werden hier zur Hilfestellung einige Hinweise gegeben. Für einen schnellen Einstieg eignet sich auch die Online-Hilfe von Selfhtml.

Kommentare in JavaScript

Innerhalb eines Scriptes können Sie Kommentare erstellen, um Ihr Script lesbar und verständlich zu beschreiben

// zwei Schrägstriche kommentieren die komplette Zeile

/*
  Ein Schrägstrich und ein Stern leiten einen Kommentar über mehrere Zeilen ein.
  Um den Kommentar wieder aufzuheben,
  ist ein Stern und Schrägstrich notwendig.
*/

Zahlen in JavaScript

Wird mit Zahlen gearbeitet, so sind diese mit einem Punkt als Dezimaltrenner zu nutzen.

var pi = 3.1415;

Beachten Sie, dass bei Divisionen sog float-Werte (Fließkommazahlen) entstehen können und das Ergebnis des Dezimal-Bruchs sehr klein sein kann. Eine Prüfung, ob eine bestimmte Rechnung Null ergibt, ist daher ggf. erst dann sinnvoll möglich, wenn das Ergebnis zuvor gerundet wurde.

Variablen

Werte können in sog. "Variablen" zwischengespeichert werden, um sie für die weitergehende Verarbeitung zu nutzen. Gerade bei errechneten Ergebnissen können diese wiederverwendet werden, ohne die Berechnung erneut zu durchlaufen. Um eine Variable zu verwenden ist ein sinnvoller Name zu vergeben und diesem ein Wert zuzuweisen. Variablen werden zudem mit dem vorangestellten Begriff "var", "let" oder "const" deklariert (nähere Beschreibungen dazu entnehmen Sie bitte der gängigen JavaScript-Literatur).

Beispiel

    let iNumber = 42;  
    let iSqrRoot = Zahl * Zahl;

Vergleichsoperatoren

Um Werte miteinander vergleichen zu können, stehen nachfolgende Operatoren zur Verfügung.

a == b    a ist gleich b
a != b    a ist nicht gleich b
a >= b    a ist größer oder gleich b
a > b     a ist größer als b
a < b     a ist kleiner als b
a <= b    a ist kleiner oder gleich b

(a > 0) || (b < 0)    a ist größer als 0 ODER b kleiner als 0
(a > 0) && (b < 0)    a ist größer als 0 UND b kleiner als 0

Berechnungsoperatoren

Um Werte miteinander zu verrechnen, stehen die üblichen, mathematischen Verfahren zur Verfügung (die Regel "Punkt vor Strich" ist auch hier zu beachten).

a + b    a plus b (Addition)
a - b    a minus b (Subtraktion)
a * b    a mal b (Multiplikation)
a / b    a geteilt durch b (Division)
a % b    a modulo b (Restwert-Berechnung;
                    z.B. 2012 % 4 = 0 -> 2012 war ein Schaltjahr)

Hinweis

Wenn Sie mehrere Texte mit + "addieren", werden die Texte einfach hintereinander gehängt. Insbesondere wenn innerhalb der Anwendung CortexUniplex in Listen bestimmte Spalten gelesen werden, die als Text und nicht als Zahl formatiert wurden, erhalten Sie entsprechende Ergebnisse.

Beispiel

    let sLastName = 'Dent';  
    let sFirstname = 'Arthur';  
    let sName = sFirstname + sLastName; // => ArthurDent

bedingte Anweisungen

In Abhängigkeit von bestimmten Werten können Ergebnisse unterschiedlich bestimmt oder das Script anders ausgeführt werden. Hierfür eigenen sich die sog. "wenn-dann"-Bedingungen oder die Fallunterscheidungen mit "switch".

Beispiel 1

    let sUserStatus = 'poor';  
    if (iBalance > 1000) {  
        sUserStatus = 'wealthy;  
    }

Beispiel 2 - if-else-Bedingung

    let sUserStatus = 'poor';
    if (iBalance > 1000) {
        userStatus = "wealthy";  
    } else {  
        userStatus = "still poor";  
    }

Beispiel 3 - switch-Fallunterscheidung

    let iGrade = 3;
    switch (iGrade) {
        case "1":
            status = "A";
            break;
        case "2":
            status = "B";
            break;
        case "3":
            status = "C";
            break;
        case "4":
            status = "D";
            break;
        case "5":
            status = "E";
            break;
        case "6":
            status = "F";
            break;
        default:
            status = "unkown";
            break;
    }

Schleifen

Mit Hilfe von Schleifen können Anweisungen so lange wiederholt werden, bis eine bestimmte Bedingung zutrifft.

!!! note "Hinweis": Tritt eine Bedingung niemals ein, so spricht man von einer Endlos-Schleife. Dieses muss vermieden werden. Daher werden häufig ergänzende Abbruchbedingungen eingebaut, damit so etwas nicht auftritt (z.B. mit Hilfe von "if-else" und der Anweisung "break", die die Ausführung unterbricht).

Schleifen mit "while"

Die while-Schleife wiederholt so lange die eingeschlossenen Anweisungen, bis die zuvor bestimmte Abbruch-Bedingung eintritt. Wurde die Bedinung bereits zuvor erfüllt, wird die Schleife nicht durchlaufen.

Beispiel - while-Schleifen

status = "poor";
let myMoney = 0;
while(myMoney < 1000000) {
    myMoney += 1;  // add 1 to myMoney
}
status = "Your are millionaire";

Schleifen mit "do-while"

Als eine andere Form der while-Schleife gilt die "do-while"-Schleife. Diese Schleife wird mindestens einmal durchlaufen, weil erst am Ende die Bedingung geprüft wird.

Beispiel - do-Schleifen

status = "poor";
let myMoney = 0;
do {
    myMoney += 1;
} while (myMoney < 1000000);
status = "Your are millionaire";

Schleifen mit "for"

Mit for-Schleifen werden Zähler bis zu einem definierten Stand durchlaufen. Das nachfolgende Beispiel zählt eine Variable so lange um eins hoch, bis ein bestimmter Stand erreicht wurde:

Beispiel - for-Schleifen

for (var myMoney = 0; myMoney < 1000000; myMoney++) {
  status = "poor";
}
status = "Your are millionaire";