JavaScript-Bibliothek common/templates

Diese Bibliothek bietet Funktionen, um Platzhalter in einen String mit Objekt-Metadaten oder Variablen zu füllen. Im Fall von Zahlen und Datumswerten legen Sie die Formatierung fest.

Verwendung

let templates = require('common/templates');

Funktionen

fill

templates.fill(template, variables, object, clearEmpty)

{ <variable>: <Variablenwert>}

Beispiel 1

let objects = require('common/objects');
let user = objects.find('user:roi');
templates.fill('${num:de|0} ${name} ${name:1,2} (${owner.fullName})', { num: 12345678.9 }, user);

Das Ergebnis dieses Aufrufs könnte folgendermaßen aussehen:

12345678 Testobject Te (Max Mustermann)

• Wert der Variable num im deutschen Format, ohne Tausendertrennzeichen oder Nachkommastellen
• Name von object
• die ersten beiden Zeichen des Namens von object
• Vor- und Nachname des Besitzers von object

Beispiel 2

Bei Variablen muss immer folgendes Format angegeben werden:

{<variable>: <variablenwert>}

let vorname = 'Marta'
let nachname = 'Müller'

let username = templates.fill('${vorname}.${nachname}',{vorname: vorname, nachname: nachname});
let usermail = templates.fill('${vorname}.${nachname}@agorumcore.com', {vorname: vorname, nachname: nachname});

Strings formatieren

Handelt es sich bei dem Attribut um eine Zeichenkette, können auch nur Teile davon verwendet werden.

Durch die Verwendung der Syntax ${<Attribut>:x,y} wird der Teil vom x-ten bis zum y-ten Zeichen ausgeschnitten, etwa extrahiert ${<Attribut>:2,5} die Zeichen 2 bis 5 (jeweils einschließlich).

• Sind die verwendeten Zahlen negativ, beginnt die Zählung vom Ende des Attributs, eine Mischung ist ebenfalls möglich, etwa ${<Attribut>:2,-2}, um das erste und letzte Zeichen zu entfernen.
• Fehlt die zweite Positionsangabe, werden die ersten x Zeichen (bei positivem x) oder die letzten x Zeichen (bei negativem x) selektiert.

Dieses kann in einer JavaScript-Konsole mit folgendem Skript getestet werden:

/* global Packages, sc */

let templates = require('common/templates');

// Ausgabe ohne Tausendertrennung, Dezimaltrennung in Deutsch
//              Formatierung    Belegen des Strings, der formatiert ausgegeben wird
templates.fill('${str:2}',     { str: 'Hier steht ein Text' });

// Ergebnis: Hi

Beispiele

Ausgabe der ersten beiden Zeichen

templates.fill('${str:2}', { str: 'Hier steht ein Text' });

Ergebnis

'Hi'

Ausgabe von Zeichen 2 bis Zeichen 4 jeweils einschließlich (gezählt wird ab 1)

//                                   1234567890123456789
templates.fill('${str:2,4}', { str: 'Hier steht ein Text' });

Ergebnis

'ier'

Ausgabe von Zeichen 2 bis Zeichen -2 (also von hinten gezählt) jeweils einschließlich (gezählt wird ab 1)

//  von hinten gezählt:              9876543210987654321
//                                    1234567890123456789
templates.fill('${str:2,-2}', { str: 'Hier steht ein Text' });

Ergebnis

'ier steht ein Tex'

Ausgabe von Zeichen -6 (also von hinten gezählt) (gezählt wird ab 1)

//  von hinten gezählt:            9876543210987654321
templates.fill('${str:-6}', { str: 'Hier steht ein Text' });

Ergebnis

'n Text'

Modifikatoren verwenden

Sie können folgende Modifikatoren für die Template-Formatierung verwenden:

• f (Filesystem-Safe): Ersetzt alle für Windows-Dateisysteme ungültigen Sonderzeichen durch _ (Unterstrich). Dies betrifft etwa < > : " | ? * / und weitere Windows-inkompatible Zeichen.
• l (Lower-Case): Konvertiert alle Zeichen in Kleinbuchstaben.

Strings mit :f formatieren

Wenn ein String formatiert wird, der als Name eines Objekts gesetzt wird, können Sie mit der Formatierung :f dafür sorgen, dass alle Sonderzeichen, die im Windows-Filesystem nicht erlaubt sind, als _ im String ersetzt werden.

Das f muss immer nach dem Doppelpunkt (:) stehen und vor der Zahl.

Beispiel

/* global Packages, sc */

let templates = require('common/templates');

templates.fill('${name:f2}', { name: 'a/' });

// Ergebnis: a_

templates.fill('${name:f}', { name: 'a/b/c' });

// Ergebnis: a_b_c

Strings mit :l (lower-case) formatieren

Der Lower-Case-Modifikator 'l' (kleines L) wird in Template-Platzhaltern verwendet, um Text in Kleinbuchstaben zu konvertieren. Er kann allein oder in Kombination mit anderen Formatierungsoptionen eingesetzt werden.

Syntax-Varianten

${variable:l}      // Nur Lower-Case
${variable:f}      // Filesystem-Safe (Windows-kompatible Zeichen)
${variable:lf}     // Lower-Case + Filesystem-Safe
${variable:fl}     // Filesystem-Safe + Lower-Case
${variable:lf1,2}  // Lower-Case + Filesystem-Safe mit Substring-Parametern
${variable:fl1,2}  // Filesystem-Safe + Lower-Case mit Substring-Parametern

Beispiel-Ausgaben

Gegeben ist der Eingabewert: test: 'TestTest Test*'

Zahlen formatieren

Allgemeine Schreibweise

${<Name Metadatum>[:Locale[|Formatangabe]]}

Schreibweisen

0     Number     Represent digit
#     Number     Digit, zero shows as absent
.     Number     Decimal separator or monetary decimal separator (Nachkommastellen)
-     Number     Minus sign
,     Number     Grouping separator (Tausendertrennung)
E     Number     Separates mantissa and exponent in scientific notation.
;     Subpattern boundary     Separates positive and negative subpatterns
%     Prefix or suffix     Multiply by 100 and show as percentage
}     Ende der Metadatum-Beschreibung oder eines einzeiligen JavaScriptes
}}    Ende eines mehrzeiligen JavaScriptes

Beispiel

Sie können die Schreibweise in einer JavaScript-Konsole mit folgendem Beispiel testen:

/* global Packages, sc */

let templates = require('common/templates');

// Ausgabe ohne Tausendertrennung, Dezimaltrennung in Deutsch
// Test für die Formatierung einer Zahl

//              Metadatum ausgeben    Zahl definieren für die Testausgabe
templates.fill('${num:de|####.##}', { num: 12345678.987654 });

// Ergebnis: 12345678.99

Beispiel in der fill-Methode

Ausgabe
Deutsche Nachkommatrennung, ohne Tausendertrennung, 2 Nachkommastellen:

templates.fill('${num:de|####.##}', { num: 12345678.987654 });

Ergebnis

12345678.99

Ausgabe mit Tausendertrennung, Dezimaltrennung in Deutsch

templates.fill('${num:de|#,###.##}', { num: 12345678.987654 });

Ergebnis

12.345.678,99

Beispiel in der fill-Methode mit Ländercode (Deutsch) und locale (Schweiz)

templates.fill('${num:de-CH|#,###.##}', { num: 12345678.987654 });

Ergebnis

12'345'678.99

Beispiel Ausgabe in % (Zahl wird mit 100 multipliziert)

templates.fill('${num:de|#%}', { num: 0.11 });

Ergebnis

11%

Beispiel mit 2 Formatangaben, einmal für positive Zahl, und für negative Zahl (num ist negativ)

templates.fill('${num:de|#,###.##;#,###.##-}', { num: -12345678.987654 });

Ergebnis

 12.345.678,99- 

Beispiel mit 2 Formatangaben, einmal für positive Zahl, und für negative Zahl (num ist positiv)

templates.fill('${num:de|#,###.##;#,###.##-}', { num: 12345678.987654 });

Ergebnis

12.345.678,99 

Beispiel Ausgabe als Ganzzahl (Nachkomma wird gerundet)

templates.fill('${num:de|####}', { num: 12345678.987654 });

Ergebnis

12345679 

Beispiel Ausgabe als Ganzzahl mit führenden Nullen

templates.fill('${z:de|000}', {z:3});

Ergebnis

003

Datumswerte formatieren

Um ein Metadatum mit dem Datentyp Datum zu formatieren, wird folgender Syntax aufgerufen:

${Rechnungsdatum:[Länderkennung|]formatstring[|Geschäftsjahr]}

Für den Formatstring können Sie Folgendes verwenden:

Beispiel: AD

Beispiel: 07

Beispiel: 2007

Beispiel: 7

Beispiel: 07

Beispiel: Sep

Beispiel: September

Beispiel: 26

Beispiel: 9

Beispiel: 0

Beispiel: 13

Beispiel: 22

Beispiel: 257

Beispiel: Mi

Beispiel: Mittwoch

Beispiel: 304

Beispiel: 3

Beispiel: 12

Beispiel: 3

Beispiel: AM

Beispiel: 24

 Beispiel: 0

Beispiel: GMT+02:00

Beispiel: +0200

Beispiel: templates.fill('${date:yyyy\'/\'MM\'/\'dd}');

Ergebnis (wenn heute der 18.02.2021 ist):
2021/02/18

Beispiel:'

Beispiel: 2016-11-27T16:54:36.164Z

Für das Geschäftsjahr können Sie Folgendes verwenden:

Testen können Sie dies in der JavaScript-Konsole mit folgendem Skript:

/* global Packages, sc */

let templates = require('common/templates');

// Formatierung des Datums: Datum für den Test belegen
templates.fill('${datum:yyyy-MM-dd HH:mm:ss}', { datum: new Date(2017, 1, 28, 12, 14, 39) });
// Ergebnis: 2017-02-28 12:14:39
​​​​​

templates.fill('${date:yyyy-MM-dd HH:mm:ss}', { date: new Date(2017, 1, 28, 12, 14, 39) });

Aufbau von new Date()

new Date() hat folgenden Aufbau:

new Date(year, monthIndex [, day [, hour [, minutes [, seconds [, milliseconds]]]]]);

Als monthIndex geben Sie einen Wert zwischen 0 und 11 an, wobei 0 = Januar und 11 = Dezember ist.

Folgendes Beispiel verdeutlicht die Funktionsweise:

/* global sc */ 

let templates = require('common/templates');

let datum = new Date(2021, 1, 1);
//Ausgabe: 2021-01-31T23:00:00.000Z

// Formatierung des Datums: Datum für den Test belegen
templates.fill('${datum:EEEE}', { datum: datum });

• let datum = new Date(2021, 1, 1); ergibt den 2021-01-31T23:00:00.000Z.
• Das JavaScript-Datum wird immer in GMT+0 ausgegeben.
• In Deutschland gilt GMT+1, daher tritt der Februar in Deutschland exakt eine Stunde früher ein als in Greenwich, London (wo der 0-Meridian verläuft). agorum core kann jedoch mit Zeitzonen umgehen und berechnet daher das Datum automatisch um. Als Tag wird daher Monday ausgegeben.

Die aktuelle Kalenderwoche ausgeben

Möchten Sie die aktuelle Kalenderwoche ausgeben, arbeiten Sie mit local-Angaben:

/* global Packages, sc */

let templates = require('common/templates');

// Formatierung des Datums: Datum für den Test belegen
templates.fill('${datum:de|w}', { datum: new Date(2021, 1, 1) });

Als Ausgabe wird die Kalenderwoche 5 zurückgegeben.

Das Datumsformat nach ISO-8601 angeben

Beispiel für das Datumsformat nach ISO-8601, etwa für die Verwendung als Übergabeparameter im FileWorkflow oder in Suchanfragen:

let templates = require('common/templates');

let d = new Date('2016-11-27T16:54:36.164Z');

// Formatierung des Datums          
let ds = templates.fill('${datum}', {
  datum: d
});

d + ' - ' + ds;

Ergebnis (Beispiel Zeitzone Deutschland Winterzeit)

Sun Nov 27 2016 17:54:36 GMT+0100 (CET) - 2016-11-27T16:54:36.164Z

Beispiel einer Formatierung für ein Geschäftsjahr

templates.fill('${datum:de|yyyy|M+11}', { datum: new Date(2017, 1, 28, 12, 14, 39) });

Gleiches funktioniert auch, wenn Sie statt M (für month) ein H (für hour) verwenden:

templates.fill('${datum:de|yyyy|H+11}', { datum: new Date(2017, 1, 28, 12, 14, 39) });

In diesem Fall werden 11 Stunden zum Datum hinzugezählt.

Ergebnis

2018

Beispiel für die Länderkennung „de“ und ausgeschriebenem Monat und Tag

templates.fill('${datum:de|EEEE dd MMMM yyyy}', { datum: new Date(2017, 1, 28, 12, 14, 39) });

Ergebnis

Dienstag 28 Februar 2017

Besonderheit bei Sekunden

Möchten Sie lediglich die Sekunden eines Zeitstempels verwenden, müssen Sie zwingend zusätzlich eine Länderkennung angeben, etwa:

${datum:de|ss}

Der Grund hierfür ist, dass ss selbst eine Länderkennung ist und als solche interpretiert wird, wenn sie allein steht.

Beispiel templates.fill mit createPath zum Erstellen einer Ordnerstruktur nach einem Datum

Wenn Sie eine Ordnerstruktur nach einem Datum anlegen wollen, kombinieren Sie die Funktion createPath(..) mit templates.fill.

Beispiel mit dem aktuellen Datum

..
.
// Sie benötigen einen Ordner, an den sie die neue Struktur anlegen wollen
let folder = objects.find('FolderID');  
// Unter diesen Ordner wollen Sie jetzt eine Struktur anlegen im Format yyyy/MM/dd
// Wenn heute der 23.08.2021 ist, dann sieht die Struktur wie folgt aus:
// <Folder>/2021/08/23
let dd = folder.createPath(templates.fill('${myDate:yyyy}/${myDate:MM}/${myDate:dd}', {myDate: new Date()});
// als Rückgabewert wird der letzte Ordner der neu angelegten Struktur zurück gegeben in diesem falle der Ordner mit dem Namen "23"
..
.

Inline-JavaScript

In der fill-Methode können Sie auch ein JavaScript ausführen lassen. Mit dem JavaScript führen Sie Berechnungen aus und das Ergebnis kann zurückgegeben werden.

Berechnet wird von links nach rechts. Dies bedeutet, eine JS-Variable aus einem JS-Skript kann in einem nächsten JS-Skript, das rechts davon steht, weiter verwendet werden.

Testen kann man dieses mit folgendem Skript in der JavaScript-Konsole:

/* global Packages, sc */

let templates = require('common/templates');

//           num formatiert ausgeben     num im JS verwenden           ab hier die Metadaten für den Test definieren
templates.fill('${num:de|000000.0000} - ${js: i = global.num + 123.88;i;}', { num: 234.998 });
// Ergebnis: '000234,9980 - 358.878'

Besonderheiten des JavaScripts

• Der Aufruf ${js: .... } läuft in einer eigenen Sandbox. Dort ist nicht alles zugelassen.
• Der Aufruf ${{js: .... }} läuft in einer eigenen Sandbox. Dort ist nicht alles zugelassen.

Der Unterschied zwischen ${js:.. und ${{js:.. ist folgender:

• ${js: ...} bedeutet, dass der JavaScript-Code in einer Zeile stehen muss. Es darf kein \n darin vorkommen.
• ${{js: ...}} bedeutet, dass der JavaScript-Code über mehrere Zeilen verteilt werden kann. Dieses bedingt eine bessere Lesbarkeit von größeren Programmteilen, hat aber den Nachteil, dass es etwas langsamer ausgeführt wird.

Verwenden Sie bei kleinen Programmstücken, die nur einzeilig sind, Folgendes:

${js: ... }

Bei größeren Programmstücken, die über mehrere Zeilen besser lesbar sind:

 ${{js:....}}

Beispiel

Berechnet wird von links nach rechts. Dies bedeutet, eine JS-Variable aus einem JS-Skript kann in einem nächsten JS-Skript, das rechts davon steht, weiter verwendet werden.

templates.fill('${num:de|000000.0000} - ${{js: i = global.num + 123.88; i;}}  - ${js: i - 10;}', 
{ num: 234.998 });

Ergebnis

'000234,9980 - 358.878 - 348.878'

Aufruf von extern definierten JavaScript-Skripten

Im Standard werden die Skripte unter /agorum/roi/Scripting/Libraries/default automatisch geladen. Darin sind die beiden DocForm-Scripte transform und validate enthalten. Aus historischen Gründen ist auch noch das Skript AC enthalten, um die Abwärtskompatibilität zu erhalten. Für diese Skripte muss kein require durchgeführt werden.

Beispiel

templates.fill('${js: transform(test).remove(/[^0-9]+/g).value() }', {
  test: 'XY-00-12345'
});

Ergebnis

'0012345'

Find

In der fill-Funktion kann auch ein find ausgeführt. Mit dem find und einer ID/UUID kann ein Objekt in agorum core gesucht werden, das als Grundlage zur Ersetzung der Variablen dient.

• Die ID/UUID kann entweder fest im Template hinterlegt oder ebenfalls durch das Template ersetzt werden lassen.
• Mit der Angabe des Metadatums wird der Wert des Metadatums zur Laufzeit zum Austauschen des Metadatums verwendet.

Minimales Beispiel

templates.fill('${find(uuid).~metadatum}', {
  uuid: '1234-1234-1234-1234' //Ersetzen Sie die UUID mit der UUID eines realen Objekts Ihrer agorum core-Installation
});

Erweitertes Beispiel 1: Neuen Dateinamen durch gesetztes Metadatum erzeugen

Das folgende Beispiel lädt die Metadaten eines gewünschten Dokuments und verwendet anschließend ein gesetztes Metadatum, um einen neuen Dateinamen zu erzeugen. Zum Erzeugen des neuen Namen wird die oben beschriebene fill-Funktion (templates.fill) verwendet:

/* global sc, data */

let objects = require('common/objects');
let metadata = require('common/metadata');
let templates = require('common/templates');

let file = objects.find('/agorum/roi/customers/TestDaten/test.pdf');

// lade die Metadaten des Objektes die mit dem (custom) Präfix acmf_ beginnen

let md = metadata().load(file, /^acmf_/).data();

// wenn es ein Metadatum acmf_displayName gibt, dann benenne die Datei um, hierzu wird templates.fill() genutzt

if (md.acmf_displayName) {

  let newname = templates.fill('${acmf_displayName:f}', md) + '.' + file.nameExtension;
  file.name = newname;
}

Erweitertes Beispiel 2: Umwandeln von Metadaten über common/beans (veraltete Funktion)

Das folgende Beispiel liest von einem Objekt Metadaten, wandelt diese in Strings um und schreibt diese wieder zurück. Die Wandlung ist so aufgebaut, dass beim Zurückschreiben wieder der richtige Datentyp erstellt wird:

let objects = require('common/objects');
let beans   = require('common/beans');
let templates = require('common/templates');

let test = objects.find('1307827');

let data = beans.get(test, '~');
let ret = [];

ret.push( templates.fill('acmf_testLong        : ${acmf_testLong}', {} , test));
ret.push( templates.fill('acmf_testDouble      : ${acmf_testDouble:en|########.##########}', {} , test));
ret.push( templates.fill('acmf_testZeichenkette: ${acmf_testZeichenkette}', {} , test));
ret.push( templates.fill('acmf_testInteger     : ${acmf_testInteger}', {} , test));
ret.push( templates.fill('acmf_testDate        : ${acmf_testDate:yyyy-MM-dd\'T\'HH:mm:ss.SSSXXX}', {} , test));
ret.push( templates.fill('acmf_testFloat       : ${acmf_testFloat:en|########.############}', {} , test));
ret.push( templates.fill('acmf_testBoolean     : ${acmf_testBoolean:}', {} , test));
ret.push(new Date(templates.fill('${acmf_testDate:yyyy-MM-dd\'T\'HH:mm:ss.SSSXXX}', {} , test)));

beans.set(test, {
  '~acmf_testLong:long'          : templates.fill('${acmf_testLong}', {} , test),
  '~acmf_testDouble:double'      : templates.fill('${acmf_testDouble:en|########.##########}', {} , test),
  '~acmf_testZeichenkette:string': templates.fill('${acmf_testZeichenkette}', {} , test),
  '~acmf_testInteger:long'       : templates.fill('${acmf_testInteger}', {} , test),
  '~acmf_testDate:date'          : templates.fill('${acmf_testDate:yyyy-MM-dd\'T\'HH:mm:ss.SSSXXX}', {} , test),
  '~acmf_testFloat:double'       : templates.fill('${acmf_testFloat:en|########.############}', {} , test),
  '~acmf_testBoolean:boolean'    : templates.fill('${acmf_testBoolean:}', {} , test)
});

JSON.stringify(data, null, 4)  + '\n' + ret.join('\n');

JavaScript-Ausdrücke

Im Standardfall liefert templates.fill() einen String als Ergebnis zurück, selbst wenn in einem Platzhalter ein Skript aufgerufen wird, das einen anderen Datentyp zurückliefert. Manchmal kann es nützlich sein, beliebige Datentypen als Ergebnis zuzulassen, etwa wenn komplexere Werte wie Arrays oder Objekte entstehen sollen.

Um diese Funktion zu verwenden, muss der template-String ein bestimmtes Format aufweisen:

let result = templates.fill('#{<code>}', ...);

• Der String muss mit #{ beginnen und mit } enden.
• Dazwischen wird ein JavaScript-Ausdruck erwartet, dessen Ergebnis als Ergebnis des templates.fill()-Aufrufs zurückgegeben wird.

Beispiel

Rückgabe eines Arrays von agorum-Objekten:

let objects = require('common/objects');
let templates = require('common/templates');

let items = templates.fill('#{folder.items()}', {
  folder: objects.find('/')
});

items.map(item => item.name);

/*
[
  "Home",
  "Administration",
  "agorum"
]
*/