Benutzerdefinierte JavaScript-Makrofunktionen
Zusätzlich zu den Makrofunktionen, die fest im Programm integriert sind (siehe Makrofunktionen, können bei Bedarf auch eigene Funktionen definiert werden. Die Definition von benutzerdefinierten Makrofunktionen erfolgt in der globalen Konfiguration. Die Funktionen sind in allen Szenarien verfügbar, die von der jeweiligen Programminstanz ausgeführt werden. Für benutzerdefinierte Funktionen kommt JavaScript-Code zum Einsatz, der mit Hilfe eines speziellen Interpreters innerhalb der .NET-Laufzeitumgebung ausgeführt wird.
Achtung
Die JavaScript-basierten Makrofunktionen sind nur eine Variante, um eigene Funktionen zu implementieren. Die andere Variante basiert auf einer externen .NET-Klassenbibliothek und benötigt eine separate .NET-Entwicklungsumgebung.
Eine separate .NET-Entwicklungsumgebung kann bei der Entwicklung und beim Debugging komplexerer Funktionen hilfreich sein. Eine solche Bibliothek eignet sich zum Aufbau einer Sammlung eigener Funktionen, die regelmäßig wiederverwendet werden sollen. Die JavaScript-Funktionen dienen hingegen zum spontanen Hinzufügen kleinerer Funktionserweiterungen.
Eigenschaft | Beschreibung |
|---|---|
CustomJsMacro.Macro[].Type | Art der Makrofunktion:
Der Einsatz benutzerdefinierter Funktionen ist beschränkt auf Feldmakros und Dokumentmakros, die im Kontext einer Dokumentverarbeitung ausgeführt werden. Ein Feldmakro liefert einen Ergebniswert zur Weiterverarbeitung zurück. Ein Dokumentmakro liefert hingegen keinen Ergebniswert zurück, sondern führt typischerweise direkte Änderungen an einem Dokument durch (siehe Funktionen). Ein Feldmakro kann dazu genutzt werden, einen Feldwert zu generieren, aber z. B. auch, um eine Bedingung ( Eine Funktion vom Typ |
CustomJsMacro.Macro[].Name(*) | Name der Makrofunktion Unter diesem Namen wird die Makrofunktion aufgerufen. Der Name der Makrofunktion muss eindeutig sein und darf nicht mit den Namen der integrierten Funktionen kollidieren. Um die benutzerdefinierten Funktionen von den integrierten Funktionen unterscheiden zu können, sollten die benutzerdefinierten Funktionen namentlich gekennzeichnet werden, z. B. mit einem Präfix |
CustomJsMacro.Macro[].Description | optionaler Beschreibungstext der Makrofunktion Der Beschreibungstext wird nur im Makro-Editor des Konfigurators angezeigt. |
CustomJsMacro.Macro[].Params | Parameterliste der Funktion, wenn diese über Aufrufparameter verfügen soll Die Parameterliste muss syntaktisch eine kommaseparierte Auflistung der Parameternamen sein, d.h. genau in der Form, wie die Liste im Kopf einer JavaScript-Funktion innerhalb der runden Klammern geschrieben werden würde. |
CustomJsMacro.Macro[].Code(*) | JavaScript-Code, der innerhalb des Funktionsrumpfes auszuführen ist Der Funktionskopf ist nicht mit anzugeben, da dieser vom Programm implizit aus den Eigenschaften Der Code einer Feldmakrofunktion endet in der Regel mit einem Eine Dokumentmakrofunktion kann wahlweise auch einen Textwert zurückliefern. Dieser Wert wird ausschließlich als zusätzliche Information im Log ausgegeben, z. B. als zusammenfassende Statusmeldung über das Ergebnis der Makroausführung. |
CustomJsMacro.AllowClr | Wahrheitswert, ob Klassen der .NET-CLR (Common Language Runtime) aus dem Namensraum "System" in der JavaScript-Umgebung verfügbar sein sollen Dies ist eine spezielle Funktion des eingesetzten JavaScript-Interpreters, durch die der JavaScript-Sprachumfang um Objekte und Methoden aus diesem .NET-Namensraum erweitert wird. Aus dem JavaScript-Code heraus kann so z. B. mit der .NET-Methode Standardwert: |
Benutzerdefinierte Makrofunktionen werden in einem Makroausdruck syntaktisch in gleicher Weise aufgerufen wie die integrierten Funktionen. Der Aufruf erfolgt über den Namen der Funktion und ggf. eine Liste von Aufrufparametern. Die beiden Funktionsarten (Feldmakro und Dokumentmakro) können in einem Ausdruck beliebig miteinander kombiniert werden. Aus dem eigenen JavaScript-Code heraus können jedoch keine integrierten Makrofunktionen ausgeführt werden. Hier können nur die vom JavaScript-Interpreter bereitgestellten Methoden verwendet werden, die bis auf einige Ausnahmen den Standard ECMAScript 2023 umfassen. Wenn die Eigenschaft AllowClr aktiviert ist, sind bestimmte .NET-Methoden verfügbar.
Die Aufrufparameter und Rückgabewerte werden automatisch in die äquivalenten .NET-Typen und JavaScript-Typen konvertiert. Das gilt auch für die Eigenschaften der nachfolgend beschriebenen Objekte. Diese Objekte müssen allerdings nicht explizit als Parameter übergeben werden, sondern sind innerhalb der JavaScript-Umgebung global zugreifbar. Das Objekt doc repräsentiert das Objekt, das sich aktuell in Bearbeitung befindet. Das Objekt vars bietet Zugriff auf alle Variablen, die in dem Ausführungskontext verfügbar sind. Das Objekt log stellt eine Methode zum Schreiben von Log-Informationen dar. Da bei JavaScript zwischen Groß- und Kleinschreibung unterschieden wird, muss bei dem Zugriff auf diese Objekte und deren Eigenschaften exakt auf die Groß-/Kleinschreibung geachtet werden.
Objekt / Eigenschaft / Methode | Beschreibung |
|---|---|
doc.id doc.uuid doc.name doc.extId doc.scenario doc.number doc.trackingId doc.trackingKey doc.customKey doc.batchId doc.batchName doc.batchExtId | interne Eigenschaften des Dokuments (analog zur Feldmakrofunktion |
doc.fields doc.fields.{Feldname} | Unterobjekt aller Kopfdatenfelder, die über ihren Feldnamen gemäß Feldkatalog angesprochen werden Die Werte dieser Eigenschaften stellen die entsprechenden Feldinhalte dar. Der Wert eines Feldes namens |
doc.tables doc.tables.{TabName} doc.tables.{TabName}.rows[] doc.tables.{TabName}.rows[].fields doc.tables.{TabName}.rows[].fields.{Feldname} | Unterobjekt aller Tabellenfelder An dieser Stelle werden keine hierarchisch verschachtelten Tabellen unterstützt, sondern nur Tabellen der obersten Ebene. Wenn ein tabellarisches Feld gemäß der Namenssyntax Die Zeilen einer Tabelle sind über ein Array |
doc.extKeys doc.extKeys.{Schlüsselname} doc.metaData doc.metaData.{Metadatumsname} | Unterobjekte der externen Schlüssel und Metadaten des Dokuments Der jeweilige Wert ist über den Namen des Schlüssels oder Metadatums abrufbar. Ein Metadatum |
doc.files[] doc.files[].id doc.files[].uuid doc.files[].name doc.files[].number doc.files[].type doc.files[].originalFile doc.files[].size doc.files[].fileType doc.files[].extKeys doc.files[].extKeys.{Schlüsselname} doc.files[].metaData doc.files[].metaData.{Metadatumsname} | Array der Dateianlagen des Dokuments Die internen Eigenschaften jeder Dateianlage können ausgelesen werden (analog zur Feldmakrofunktion |
vars vars.{Variablenname} | Unterobjekt aller verfügbaren Variablen Eine einzelne Variable ist über den Variablennamen auslesbar. Die Variable |
log( {Text} ) | Methode zum Schreiben eines eigenen Eintrags in das Protokoll von xSuite Interface, das im aktuellen Ausführungskontext aktiv ist Der Eintrag ist immer vom Typ "Debug". Ein solcher Eintrag kann z. B. dazu dienen, eigene Analyseinformationen zur Ausführung des JavaScript-Codes auszugeben. Der zu protokollierende Text muss vom Typ "String" sein (Beispiel: |
Ein Dokumentmakro kann direkte Änderungen an einem Dokument vornehmen und hat daher lesenden und teilweise auch schreibenden Zugriff auf die obigen Objekte und Eigenschaften. Änderungen an den folgenden Elementen werden aus der JavaScript-Ausführungsumgebung zurück in das Ursprungsdokument übernommen:
doc.fields.{Feldname}
doc.tables.{TabName}.rows[]
doc.tables.{TabName}.rows[].fields.{Feldname}
doc.extKeys
doc.metaData
doc.files[].extKeys
doc.files[].metaData
Versuche, andere Elemente im JavaScript-Code zu verändern, werden entweder ignoriert oder führen zu einem Ausführungsfehler. Die Inhalte vorhandener Kopf- und Positionsfeldern können geändert werden. Das Hinzufügen oder Löschen von Feldern ist jedoch nicht möglich. Ein Dokument und eine Tabellenzeile umfasst standardmäßig alle Felder, die im Feldkatalog definiert sind, ggf. mit leeren Initialwerten. Andere Felder, die nicht im Feldkatalog definiert sind, können nicht verwendet werden. Ein freies Hinzufügen neuer und unbekannter Felder wird daher nicht unterstützt.
Das Hinzufügen oder Löschen von ganzen Tabellenobjekten wird ebenfalls nicht unterstützt. Die Zeilenanzahl bestehender Tabellen kann jedoch verändert werden, d.h. Elemente aus dem Array rows können gelöscht werden oder neue Elemente hinzugefügt werden. Wenn alle Tabellenzeilen gelöscht werden, darf das vorhandene rows-Array nicht durch ein neues Array überschrieben werden. Für eine Tabelle namens Table1 ist doc.tables.Table1.rows = []; z. B. nicht zulässig. In diesem Fall müssen nur die Zeilen aus dem bestehenden Array entfernt werden:
doc.tables.Table1.rows.length = 0; doc.tables.Table1.rows.splice(0, doc.tables.Table1.rows.length);
Beim Hinzufügen neuer Tabellenzeilen müssen nicht zwingend alle Felder der Zeile im JavaScript-Code gesetzt werden. Für eine Tabelle mit den 3 Feldern Column1, Column2 und Column3 ist der folgende Ausdruck zulässig, da das fehlende Feld Column3 bei der Übernahme der Änderungen implizit ergänzt und mit dem Initialwert belegt wird.
doc.tables.Table1.rows.push({
fields: {
Column1: "Value1",
Column2: "Value2",
}
});Die internen Eigenschaften des Dokuments und der Dateianlagen sind an dieser Stelle grundsätzlich unveränderlich. Die externen Schlüssel und Metadaten des Dokuments und der Dateianlagen können hingegen frei gesetzt werden. Anders als bei den vordefinierten Feldern können dabei auch eigene neue Namen verwendet werden. Die Objekte extKeys und metaData dürfen nicht vollständig ersetzt werden, sondern nur verändert werden. doc.metaData = {}; wäre somit unzulässig. Um aus einem solchen Objekt eine Eigenschaft zu löschen, muss der Eigenschaftswert auf null oder auf undefined gesetzt werden, z. B. bei einem Metadatum Meta1 per doc.metaData.Meta1 = null;.