MS Excel-Tags für Dokumentgenerator

Ein "Tag" bezieht sich auf einen Ausdruck, den der Dokumentgenerator in einer Dokumentvorlage mit JSON-Daten ersetzen kann.

Daten

Die JSON-Daten können in Object Storage gespeichert oder in einer Anforderung inline angegeben werden.

Beispiel - In Object Storage gespeichert

  "data": {    
    "source": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/names.json"
  }

Beispiel - Inline in data.content angegeben

  "data": {
    "source": "INLINE",
    "content": [{"name":"John"},{"name":"Monica"}]
  }

Tags

Tags enthalten Pfade zu einem Wert in JSON-Daten. Beispiel für folgende Daten:

{
  "customer": {
    "first_name": "Jack",
    "last_name": "Smith"
  }
}

Sie können dies in Ihrer Vorlage verwenden:

Hello {customer.first_name} {customer.last_name}!

Um diesen Text zu generieren:

Hello Jack Smith!

Beachten Sie, dass bei JSON-Schlüsseln die Groß-/Kleinschreibung beachtet wird. first_name und First_Name sind unterschiedliche JSON-Schlüssel.

Tag-Begrenzungszeichen

Sie können die Standard-Tagbegrenzungszeichen { und } durch folgende Werte ersetzen:

  • {{ und }}
  • {{{ und }}}

Sie können die Tagbegrenzer in den benutzerdefinierten Eigenschaften der MS Excel-Vorlage sowohl mit document_generator_start_delimiter als auch mit document_generator_end_delimiter angeben, wie hier gezeigt:


Trennzeichen

Im vorherigen Beispiel können Sie dies in Ihrer Vorlage verwenden:

Hello {{{customer.first_name}}} {{{customer.last_name}}}!

Zur Generierung dieses Textes:

Hello Jack Smith!

Basistag

Syntax: {basic}

Wird zum Einfügen von Texten, Zahlen oder booleschen Werten verwendet.

Beispiele

Daten

{ 
  "a_first_name": "John",
  "a_last_name": "Smith",
  "a_number": 42,
  "a_boolean": true
}

Template


Template

Ausgeben


Template

Tag für vertikale Schleife

Syntax: {vl:loop}...{/loop} oder {#loop}...{/loop}

Ein {vl:loop}-Tag wird verwendet, um Kopien eines Zellenbereichs vertikal zu erstellen. Die kopierte Region wird durch die Position der Tags {vl:loop} und {/loop} bestimmt. Sowohl {vl:loop} als auch {/loop} sind in der Region enthalten. Zellen unterhalb des Bereichs werden nach unten gedrückt.

Informationen zur Eindeutigkeit von Schleifen-Tags finden Sie unter Labels.

Beispiel

Daten

{
  "customers": [
    {
      "name": "John Smith",
      "age": 23,
      "is_last_bill_paid": true
    },
    {
      "name": "Alice Martin",
      "age": 34,
      "is_last_bill_paid": false
    },
    {
      "name": "Joe West",
      "age": 45,
      "is_last_bill_paid": false
    },
    {
      "name": "Mary Moss",
      "age": 56,
      "is_last_bill_paid": true
    }
  ]
}

Template


Template

Ausgeben


Ausgeben

Tag für horizontale Schleife

Syntax: {hl:loop}...{/loop} oder {:loop}...{/loop}

Ein {hl:loop}-Tag wird verwendet, um Kopien einer Zellregion horizontal zu erstellen. Die kopierte Region wird durch die Position der Tags {hl:loop} und {/loop} bestimmt. Sowohl {hl:loop} als auch {/loop} sind in der Region enthalten. Zellen rechts vom Bereich werden nach rechts geschoben.

Informationen zur Eindeutigkeit von Schleifen-Tags finden Sie unter Labels.

Beispiel

Daten

{
  "days": [
    {
      "day_of_week": "Monday",
      "steps": 1023,
      "calories": 145
    },
    {
      "day_of_week": "Tuesday",
      "steps":2345,
      "calories": 267
    },
    {
      "day_of_week": "Wednesday",
      "steps": 3101,
      "calories": 345
    },
    {
      "day_of_week": "Thursday",
      "steps": 4523,
      "calories": 412
    },
    {
      "day_of_week": "Friday",
      "steps": 4321,
      "calories": 389
    }
  ]
}

Template


Template

Ausgeben


Ausgeben

Bedingte Tags

if-Tag

Syntax: {if:expression}...{/expression} oder {#expression}...{/expression}

Ein Tag {if:expression} in einem Arbeitsblatt zeigt den umschlossenen Zellenbereich nur an, wenn der Ausdruck in "true" aufgelöst wird. Wenn der Ausdruck "false" ist, wird der umschlossene Bereich entfernt, und der folgende Inhalt wird aufgehoben (vertikal).

Die expression kann entweder ein boolescher Wert oder ein boolescher Ausdruck wie expr(age<18) sein. Weitere Informationen finden Sie unter Bedingungsausdrücke im folgenden Abschnitt.

Beispiel

Daten

{
  "age": 18,
  "name": "Bob"
}

Template


Vorlage

Ergebnis


Ausgabe

Da wir "age": 18 haben, ist age<18 falsch. Dies verursacht:

  • Zellenbereich E2:F3, der entfernt werden soll.
  • Zellenbereich E4:F5, der abgerufen werden soll.

HIF-Tag

Syntax: {hif:expression}...{/expression} oder {:expression}...{/expression}

Ein Tag {hif:expression} in einem Arbeitsblatt zeigt den umschlossenen Zellenbereich nur an, wenn der Ausdruck in "true" aufgelöst wird. Wenn der Ausdruck "false" ist, wird der umschlossene Bereich entfernt, und der Inhalt auf der rechten Seite wird links gezogen (horizontal).

Die expression kann entweder ein boolescher Wert oder ein boolescher Ausdruck wie expr(age<18) sein. Weitere Informationen finden Sie unter Bedingungsausdrücke im folgenden Abschnitt.

Beispiel

Daten

{
  "age": 18,
  "name": "Bob"
}

Template


Vorlage

Ergebnis


Ausgabe

Da wir "age": 18 haben, ist age<18 falsch. Dies verursacht:

  • Zellenbereich B5:C6, der entfernt werden soll.
  • Zellenbereich D5:E6, der nach links gezogen werden soll.

staticIf-Tag

Syntax: {staticIf:expression}...{/expression} oder {##expression}...{/expression}

Ein Tag {staticIf:expression} in einem Arbeitsblatt zeigt den umschlossenen Zellenbereich nur an, wenn der Ausdruck in "true" aufgelöst wird. Wenn der Ausdruck "false" ist, wird der umschlossene Bereich leer, ohne den umgebenden Inhalt zu verschieben.

Die expression kann entweder ein boolescher Wert oder ein boolescher Ausdruck wie expr(age<18) sein. Weitere Informationen finden Sie unter Bedingungsausdrücke im folgenden Abschnitt.

Beispiel

Daten

{
  "age": 18,
  "name": "Bob"
}

Template


Vorlage

Ergebnis


Ausgabe

Da wir "age": 18 haben, ist age<18 falsch. Dies verursacht:

  • Zellenbereich E2:F3 muss leer sein.

Imagetag

Syntax: {im:image} oder {image:image} oder {%image}

Ein Tag {im:image} wird verwendet, um ein Bild in ein Arbeitsblatt einzufügen. Images können aus einem OCI Object Storage-Bucket oder aus einer URL bereitgestellt werden. Bilder müssen als Objekt bereitgestellt werden. Beispiel:

{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png"
  }
}

Allgemein

Das spezifische Schema für jeden Quelltyp wird unten beschrieben. Sie können auch die folgenden optionalen Eigenschaften in das Bildobjekt aufnehmen, um die Bildformatierung zu steuern:

  • Breite: Eine string mit Ziffern, gefolgt von einer Maßeinheit. E.G. 200px. Legt die Breite des Bildes fest.
  • Höhe: Eine string mit Ziffern, gefolgt von einer Maßeinheit. E.G. 200px. Legt die Höhe des Bildes fest.
  • alt_text: Eine string. Dies wird als alternativer Text des Bildes festgelegt.

Unterstützte Maßeinheiten:

Der Dokumentgenerator unterstützt die folgenden Maßeinheiten für Bilder:

  • px (Pixel)
  • in (Zoll)
  • cm (Zentimeter)
  • % (Prozentsatz)

Standardgröße der eingefügten Bilder:

  • Die ursprüngliche Größe bleibt erhalten.

Bildskalierung:

Wenn nur eine Bilddimension angegeben ist, berechnet Document Generator einen skalierten Wert für die fehlende Dimension, um das Seitenverhältnis beizubehalten. Beispiel:

  • Wenn Sie eine Breite, aber keine Höhe angeben, wird eine skalierte Höhe basierend auf den nativen Dimensionen des Images und der angegebenen Breite berechnet.
  • Wenn Sie eine Höhe, jedoch keine Breite angeben, wird eine skalierte Breite basierend auf den nativen Dimensionen des Bildes und der angegebenen Höhe berechnet.

Unterstützte Formate

Document Generator unterstützt die folgenden Bildformate:

  • PNG
  • JPG
  • GIF
  • BMP

Schemas

OCI Object Storage

  • source: muss auf OBJECT_STORAGE gesetzt werden
  • objectName: Pfad und Name der Datei
  • namespace: Der Namespace des Objektspeicher-Buckets
  • bucketName: Der Name des Buckets, der die Datei enthält
  • mediaType: Der Medientyp (MIME) des Images

Beispiel - Breite und Höhe angegeben

Daten
{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png",
    "width": "400px",
    "height": "200px"
  }
}
Template

Vorlage
Ergebnis

Ausgabe

URL

  • source: muss auf URL gesetzt werden
  • url: Die Bild-URL im Format string

Hinweis: Um Bilder aus dem Internet zu verwenden, benötigt der Dokumentgenerator ausgehenden Zugriff auf das Internet. Beispiel: Wenn der Dokumentgenerator in einem privaten Subnetz in OCI ausgeführt wird, können Sie ein NAT-Gateway einrichten, damit der Dokumentgenerator eine Verbindung zum Internet herstellen kann.

Beispiel - Breite und Höhe nicht angegeben

Daten
{
  "my_image": {
    "source": "URL",
    "url": "https://www.oracle.com/.../.jpg"
  }
}
Template

Vorlage
Ergebnis

Ausgabe

Daten-URL

Document Generator unterstützt auch Bilder, die als Daten-URLs bereitgestellt werden. Das Bild muss Base64-codiert sein.

  • source: muss auf URL gesetzt werden
  • url: Die Bild-URL im Format string

Beispiel - Nur Höhe ist angegeben

Daten
{
  "my_image": {
    "source": "URL",
    "url": "data:image/png;base64,iVBORw0KG...go",
    "height": "150px"
  }
}
Template

Vorlage
Ergebnis

Ausgabe

Barcode-Tag

Syntax: {bc:barcode} oder {barcode:barcode}

Ein Tag {bc:barcode} wird verwendet, um ein Barcodebild in einem Arbeitsblatt zu generieren. Folgende Barcodetypen werden unterstützt:

QuietZone

  • verticalSize: number - Größe der vertikalen Ruhezone (über und unter dem Barcode)
  • horizontalSize: number - Größe der horizontalen ruhigen Zone (rechts und links vom Barcode)

Beispiel

{
  "verticalSize": 10,
  "horizontalSize": 20
}

Eigenschaften, die allen Barcodes gemeinsam sind

  • barcodeType (erforderlich): CODE_128, CODE_39, DATA_MATRIX, EAN, QR, PDF417, UPC
  • data (erforderlich): Zeichenfolge - Zu codierende Daten
  • moduleWidth: number (Standard: 1) - Die Breite jedes Strichs im Barcode für 1D-Barcodes. Breite und Höhe jedes Punkts für 2D-Barcodes
  • quietZone: QuietZone: Der leere Bereich um einen Barcode
  • scale: number (Standard: 1.0) - Skalierungsfaktor für das Barcodebild. Alle Dimensionen werden mit diesem Faktor multipliziert, um ein größeres Bild (Skala > 1) oder kleineres Bild (Skala < 1) zu generieren
  • rotation: DEGREES_0(Standard), DEGREES_90, DEGREES_180, DEGREES_270
  • altText: Zeichenfolge - Alternativer Text für das Barcodebild

Code 128 - Spezifische Eigenschaften

  • barHeight: number (Standard: 40) - Höhe jeder Leiste
  • fontSize: number (Standard: 8) - Schriftgröße in Punkten für menschenlesbaren Text im Barcodebild
  • allowedCodeSets: A, B, C, AB, ABC (Standard)

Beispiel

{
  "barcodeType": "CODE_128",
  "data": "12345",
  "moduleWidth": 2,
  "quietZone": {
    "verticalSize": 10,
    "horizontalSize": 10
  },
  "scale": 0.5,
  "rotation": "DEGREES_90",
  "altText": "Code 128",
  "barHeight": 80,
  "fontSize": 10,
  "allowedCodeSets": "AB"
}

Code 39 - Spezifische Eigenschaften

  • barHeight: number (Standard: 40) - Höhe jeder Leiste
  • fontSize: number (Standard: 8) - Schriftgröße für menschenlesbaren Text im Barcodebild
  • moduleWidthRatio: number (Standard: 2) - Verhältnis der breiten Balkenbreite zur schmalen Balkenbreite. Zulässige Werte sind 2 oder 3
  • isExtended: boolean (Standard: false) - Gibt an, ob der erweiterte Code 39 zum Kodieren des vollständigen ASCII-Sets verwendet werden soll
  • checkDigitType: NONE(Standard), MOD_43

Beispiel

{
  "barcodeType": "CODE_39",
  "data": "12345?",
  "barHeight": 80,
  "fontSize": 10,
  "moduleWidthRatio": 3,
  "isExtended": true,
  "checkDigitType": "MOD_43"
}

Datenmatrix - Spezifische Eigenschaften

  • shape: SQUARE, RECTANGULAR: Wenn keine Angabe gemacht wird, wird die kleinste Ausprägung verwendet. Wenn die size angegeben ist, wird die Ausprägung nicht verwendet
  • size: Zahl (von 1 bis 30) - Größe der Datenmatrix. Wenn nicht angegeben, wird die optimale Größe basierend auf den zu codierenden Daten ausgewählt

Beispiel

{
  "barcodeType": "DATA_MATRIX",
  "data": "The quick brown fox jumped over the lazy dog.",
  "shape": "SQUARE",
  "size": 20
}

Internationale Artikelnummer (EAN) - Besondere Eigenschaften

  • barHeight: number (Standard: 40) - Höhe jeder Leiste
  • fontSize: number (Standard: 8) - Schriftgröße für menschenlesbaren Text im Barcodebild
  • eanType: EAN_8, EAN_13(Standard)

Beispiel

{
  "barcodeType": "EAN",
  "data": "12345",
  "barHeight": 80,
  "fontSize": 10
}

Quick-Response-Code (QR-Code) - Spezifische Eigenschaften

  • version: Nummer (von 1 bis 40) - QR-Code-Version. Bestimmt die Größe des Symbols und die Datenmenge, die es kodieren kann. Der Standardwert ist die Mindestversion, die zum Kodieren der Daten erforderlich ist
  • minEccLevel: LOW, MEDIUM, QUARTILE, HIGH. Mindestfehlerkorrekturebene. Der Standardwert ist die maximal mögliche Ebene für die ausgewählte Version und Daten
  • forceByteCompaction: boolean (Standard: false) - Gibt an, ob der Byte-Komprimierungsmodus erzwungen werden soll. Bei 'Falsch' wird der optimale Verdichtungsmodus basierend auf den zu kodierenden Daten gewählt.

Beispiel

{
  "barcodeType": "QR",
  "data": "https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functions_pbf_catalog_document_generator.htm"
}

PDF417 - Spezifische Eigenschaften

  • forceByteCompaction: boolean (Standard: false) - Gibt an, ob der Byte-Komprimierungsmodus erzwungen werden soll. Bei 'Falsch' wird der optimale Verdichtungsmodus basierend auf den zu kodierenden Daten gewählt.
  • rowHeight: Zahl (Standard: 3)
  • pdf417Type: NORMAL(Standard), TRUNCATED, MICRO
  • eccLevel: number (von 0 bis 8) - Die Menge des Barcodes, der den Fehlerkorrekturcodewörtern zugewiesen werden soll. Die Anzahl der Fehlerkorrektur-Codewörter wird durch 2^(eccLevel + 1) bestimmt. Wird kein Wert angegeben, wird ein Wert basierend auf den zu codierenden Daten ausgewählt. Ignoriert für Micro-PDF417-Barcodes

Beispiel

{
  "barcodeType": "PDF417",
  "data": "12345",
  "rowHeight": 6
}

Universal Product Code (UPC) - Spezielle Eigenschaften

  • upcType: UPC_A(Standard), UPC_E
  • barHeight: number (Standard: 40) - Höhe jeder Leiste
  • fontSize: number (Standard: 8) - Schriftgröße für menschenlesbaren Text im Barcodebild
  • guardPatternExtraHeight: number (Standard: 5) - Zusätzliche Höhe für Schutzmuster
  • showCheckDigit: boolean (Standard: true) - Gibt an, ob die Prüfziffer im menschenlesbaren Text angezeigt werden soll

Beispiel

{
  "barcodeType": "UPC",
  "data": "12345"
}

Beispiel

Daten

{
  "barcodeTypes": [
    {
      "name": "Code 39",
      "barcodes": [
        {
          "label": "default with alt text",
          "barcode": {
            "barcodeType": "CODE_39",
            "data": "12345",
            "altText": "an example Code 39 barcode"
          }
        },
        {
          "label": "module width 2",
          "barcode": {
            "barcodeType": "CODE_39",
            "data": "12345",
            "moduleWidth": 2
          }
        }
      ]
    },
    {
      "name": "Code 128",
      "barcodes": [
        {
          "label": "default with alt text",
          "barcode": {
            "barcodeType": "CODE_128",
            "data": "12345",
            "altText": "an example Code 128 barcode"
          }
        },
        {
          "label": "module width 2",
          "barcode": {
            "barcodeType": "CODE_128",
            "data": "12345",
            "moduleWidth": 2
          }
        }
      ]
    }
  ]
}

Template


Vorlage

Ausgeben


Ausgabe

Zellenstyling-Tag

Syntax: {cs:style} oder {cellStyling:style}

Ein {cs:style}-Tag wird verwendet, um eine Formatierung auf eine Excel-Zelle anzuwenden. Zu den Stylingoptionen gehören:

  • Schriftart
  • Horizontale Ausrichtung
  • Vertikale Ausrichtung
  • Hintergrundfarbe
  • Rahmen

Überlegungen zum Styling:

  • Mehrere Zellenstylingtags können auf eine Zelle angewendet werden. Sie werden von links nach rechts angewendet.
  • Das vorhandene Zellenstyling wird beibehalten, bevor ein zusätzliches Styling angewendet wird.
  • Der Stil wird auf die gesamte Zelle angewendet

StyleColor

  • colorType (erforderlich): OPAQUE_HEX_RGB
  • value: 6-stellige Hexadezimalzeichenfolge

Beispiel

{
  "color": {
    "colorType": "OPAQUE_HEX_RGB",
    "value": "FFFF00"
  }
}

Rahmenformat

  • borderStyle (erforderlich): NONE, MEDIUM, DOUBLE, DASHED, DOTTED, MEDIUM_DASHED, MEDIUM_DASH_DOT, MEDIUM_DASH_DOT_DOT
  • color: StyleColor

Beispiel

{
  "top": {
    "borderStyle": "MEDIUM",
    "color": {
      "colorType": "OPAQUE_HEX_RGB",
      "value": "FFFF00"
    }
  }
}

Schriftart

  • familyName: Zeichenfolge
  • sizeInPoints: Zahl
  • color: StyleColor
  • isItalic: Boolesch
  • isBold: Boolesch
  • isStrikethrough: Boolesch
  • underline: NONE, SINGLE, DOUBLE
  • textPosition: BASELINE, SUPERSCRIPT, SUBSCRIPT

Beispiel

{
  "font": {
    "familyName": "Cookie",
    "sizeInPoints": 20,
    "color": {
      "colorType": "OPAQUE_HEX_RGB",
      "value": "FF0000"
    },
    "isBold": true,
    "isItalic": true,
    "isStrikethrough": true,
    "underline": "DOUBLE",
    "textPosition": "SUPERSCRIPT"
  }
}

Horizontale Ausrichtung

  • horizontalAlignment: LEFT, CENTER, RIGHT, JUSTIFY

Beispiel

{
  "horizontalAlignment": "RIGHT"
}

Ausricht. vertikal

  • verticalAlignment: TOP, CENTER, BOTTOM

Beispiel

{
  "verticalAlignment": "TOP"
}

Hintergrundfarbe von Zelle

  • backgroundType (erforderlich): SINGLE_FILL_COLOR
  • color: StyleColor

Beispiel

{
  "background": {
    "backgroundType": "SINGLE_FILL_COLOR",
    "color": {
      "colorType": "OPAQUE_HEX_RGB",
      "value": "DDDDDD"
    }
  }
}

Rahmen

  • top: BorderStyle
  • bottom: BorderStyle
  • left: BorderStyle
  • right: BorderStyle

Beispiel

{
  "top": {
    "borderStyle": "MEDIUM",
    "color": {
      "colorType": "OPAQUE_HEX_RGB",
      "value": "FFFF00"
    }
  },
  "bottom": {
    "borderStyle": "DASHED",
    "color": {
      "colorType": "OPAQUE_HEX_RGB",
      "value": "FF00FF"
    }
  },
  "left": {
    "borderStyle": "DOTTED"
  },
  "right": {
    "borderStyle": "MEDIUM_DASHED"
  }
}

Beispiel

Daten

{
  "cookieBold": {
    "font": {
      "familyName": "Cookie",
      "sizeInPoints": 20,
      "isBold": true
    }
  },
  "products": [
    {
      "name": "Winter Gloves",
      "remaining": 444,
      "s1": {
        "font": {
          "underline": "DOUBLE"
        }
      },
      "s2": {
        "background": {
          "backgroundType": "SINGLE_FILL_COLOR",
          "color": {
            "colorType": "OPAQUE_HEX_RGB",
            "value": "DDDDDD"
          }
        }
      }
    },
    {
      "name": "Snow Shovel",
      "remaining": 11,
      "s2": {
        "font": {
          "color": {
            "colorType": "OPAQUE_HEX_RGB",
            "value": "FF0000"
          }
        },
        "background": {
          "backgroundType": "SINGLE_FILL_COLOR",
          "color": {
            "colorType": "OPAQUE_HEX_RGB",
            "value": "BBBBBB"
          }
        }
      }
    }
  ]
}

Template


Vorlage

Ausgeben


Ausgabe

Anmerkungen

Betrachten Sie Zelle B3. Die Vorlage enthält {name}{cs:cookieBold}{cs:s1}.

  • Die gelbe Hintergrundfüllung stammt aus dem ursprünglichen Zellenstyling.
  • {name} wird aus den Daten in "Winterhandschuhe" aufgelöst.
  • {cs:cookieBold} wendet die Cookie-Schriftart aus dem cookieBold-Stil an, der im Stamm der Daten definiert ist.
  • {cs:s1} wendet die doppelte Unterstreichung aus dem s1-Stil für Winterhandschuhe an.

Formeltag

Syntax: {fo:formula} oder {formula:formula} oder {>formula}

Mit einem Tag {fo:formula} wird eine Excel-Formel in ein Arbeitsblatt eingefügt.

Beachten Sie, dass der Inhalt der eingefügten Formeln nicht validiert wird.

Beispiel

Daten

{
  "value1": 22,
  "value2": 33,
  "formula1": "A3+B3",
  "formula2": "3 * 2",
  "formula3": "A3 * 2",
  "formula4": "SUM(A3:B3)",
  "items": [
    {
      "itemName": "Gloves",
      "quantity": 3,
      "unitPrice": 22,
      "total": "B11 * C11"
    },
    {
      "itemName": "Pants",
      "quantity": 2,
      "unitPrice": 55,
      "total": "B12 * C12"
    }
  ]
}

Template


Vorlage

Ausgeben


Ausgabe

Tag für Seitenumbruch

Syntax: {pb:expression} oder {pageBreak:expression}

Ein {pb:expression}-Tag fügt einen Seitenumbruch ein, wenn die expression-Bedingung wahr ist. Die expression kann entweder ein boolescher Wert oder ein boolescher Ausdruck wie expr(name=="Arrival") sein. Weitere Informationen finden Sie unter Bedingungsausdrücke im folgenden Abschnitt.

Beispiel

Daten

{
  "movies": [
    {
      "name": "Arrival",
      "actors": [
        {
          "name": "Amy Adams"
        },
        {
          "name": "Jeremy Renner"
        }
      ],
      "pageBreak_condition": true
    },
    {
      "name": "Groundhog Day",
      "actors": [
        {
          "name": "Bill Murray"
        },
        {
          "name": "Andie MacDowell"
        }
      ],
      "pageBreak_condition": false
    },
    {
      "name": "Notting Hill",
      "actors": [
        {
          "name": "Hugh Grant"
        },
        {
          "name": "Julia Roberts"
        },
        {
          "name": "Rhys Ifans"
        }
      ],
      "pageBreak_condition": false
    }
  ]
}

Vorlage


Vorlage

Ausgeben


Ausgabe

Zeilentag ausblenden

Syntax: {hideRow:expression}

Ein Tag {hideRow:expression} in einem Arbeitsblatt blendet die Zeile aus, die das Tag enthält, wenn der Ausdruck in "true" (ausblenden) oder "false" (anzeigen) aufgelöst wird. Die expression kann entweder ein boolescher Wert oder ein boolescher Ausdruck wie expr(age<18) sein. Weitere Informationen finden Sie unter Bedingungsausdrücke im folgenden Abschnitt.

Beachten Sie, dass, wenn mehrere {hideRow:expression}-Tags in derselben Zeile vorhanden sind, die oberste Priorität hat, da der Dokumentgenerator jede Zeile von der ersten Spalte zur letzten Spalte verarbeitet.

Beispiel

Daten

{
  "hideRowTrue": true,
  "customers": [
    {
      "name": "John Smith",
      "age": 23,
      "is_last_bill_paid": true
    },
    {
      "name": "Alice Martin",
      "age": 17,
      "is_last_bill_paid": false
    },
    {
      "name": "Joe West",
      "age": 36,
      "is_last_bill_paid": false
    },
    {
      "name": "Monica Richard",
      "age": 16,
      "is_last_bill_paid": true
    },
    {
      "name": "Mary Moss",
      "age": 18,
      "is_last_bill_paid": true
    }
  ]
}

Vorlage


Vorlage

Ausgeben


Ausgabe

Die Zeilen 7 und 9 sind versteckt, weil das Alter von Alice Martin und Monica Richard kleiner als 18 ist.

Spaltentag ausblenden

Syntax: {hideColumn:expression}

Ein Tag {hideColumn:expression} in einem Arbeitsblatt blendet die Spalte aus, die das Tag enthält, wenn der Ausdruck in "true" (ausblenden) oder "false" (anzeigen) aufgelöst wird. Die expression kann entweder ein boolescher Wert oder ein boolescher Ausdruck wie expr(age<18) sein. Weitere Informationen finden Sie unter Bedingungsausdrücke im folgenden Abschnitt.

Beachten Sie, dass, wenn mehrere {hideColumn:expression}-Tags in derselben Spalte vorhanden sind, der unterste gilt, da Document Generator jedes Excel-Arbeitsblatt von der oberen zur unteren Zeile verarbeitet.

Beispiel

Daten

{
  "hideColTrue": true,
  "customers": [
    {
      "name": "John Smith",
      "age": 23,
      "is_last_bill_paid": true
    },
    {
      "name": "Alice Martin",
      "age": 18,
      "is_last_bill_paid": false
    },
    {
      "name": "Mary Moss",
      "age":17,
      "is_last_bill_paid": true
    }
  ]
}

Vorlage


Vorlage

Ausgabe


Ausgabe

Spalte D ist ausgeblendet, weil das Alter von Mary Moss kleiner als 18 ist.

Tag überspringen

Syntax: {skip}

Ein Tag {skip} in einem Arbeitsblattnamen verhindert die Auflösung von Tags in diesem Arbeitsblatt.

Beispiel

Daten

{
  "name": "World"
}

Vorlage

In diesem Beispiel enthalten beide Blätter in der Vorlage ein Tag:


Vorlage - Sheet1

Vorlage - Sheet2

Ausgabe

In der Ausgabe wird nur das Tag im zweiten Arbeitsblatt aufgelöst:


Ausgabe - Sheet1

Ausgabe - Sheet2

Blattgenerierungstag

Syntax: {!dataRef} oder {sg:dataRef}

Ein Tag zur Blattgenerierung fungiert als Schleife oder bedingtes Tag über das gesamte Arbeitsblatt. Pro Arbeitsblatt ist nur eine zulässig.

  • Wenn die zugrunde liegenden JSON-Daten unter dataRef ein Array sind, wird das Arbeitsblatt für jedes zusätzliche Arrayelement dupliziert. Die Tags jedes Arbeitsblatts werden wie ein Schleifen-Tag im Kontext des entsprechenden Array-Elements ausgewertet.
  • Wenn die zugrunde liegenden JSON-Daten der boolesche Wert true sind, wird das ursprüngliche Arbeitsblatt normal verarbeitet.
  • Andernfalls wird das Arbeitsblatt entfernt.

Beispiel

Daten

{
  "region": "Midwest",
  "customers": [
    {
      "name": "Alice"
    },
    {
      "name": "Bob"
    }
  ]
}

Vorlage

Das Arbeitsblatt enthält das Blattgenerierungstag {!customers}, das auf das customers-Array in den JSON-Daten verweist. Es enthält auch zwei grundlegende Tags im Arbeitsblattraster und ein weiteres im Arbeitsblattnamen.


Vorlage - Blatt 1

Ausgabe

In der Ausgabe:

  • Es gibt ein Arbeitsblatt pro Kunde.
  • Das Basistag {name} wird durch den Namen des aktuellen Kunden aus dem JSON-Array ersetzt, einschließlich im Arbeitsblattnamen.
  • Das grundlegende Tag {region} wird durch die Region ersetzt, die auf der Stammebene der JSON-Daten angegeben ist.

Ausgabe - Blatt 1

Ausgabe - Blatt 1

Anmerkungen

  • Das Tag zur Blattgenerierung kann überall im Arbeitsblatt angezeigt werden.
  • Generierte Arbeitsblätter werden unmittelbar nach dem ursprünglichen Arbeitsblatt eingefügt.
  • Wenn der Name eines generierten Arbeitsblatts nicht eindeutig ist, wird eine Zahl an den Namen angehängt. Wenn das ursprüngliche Arbeitsblatt also "Kunde" heißt, generiert es "Kunde", "Kunde 2", "Kunde 3" usw.
  • Wenn das Arbeitsblatt entfernt wird und keine anderen Arbeitsblätter vorhanden sind, wird ein leeres Arbeitsblatt namens "Sheet1" erstellt, sodass die Ausgabedatei weiterhin gültig ist.

Bedingungsausdrücke

Bei einigen Tags kann Document Generator Ausdrücke verwenden, die in "true" oder "false" aufgelöst werden.

Diese Ausdrücke kombinieren JSON-Datenreferenzen, Operatoren (wie == und <), integrierte Funktionen (wie StartsWith) und Literale (wie "John" oder 23).

Regeln

  • Bei Zeichenfolgenvergleichen wird die Groß-/Kleinschreibung beachtet. Dabei wird der Unicode-Code-Point-Vergleich mit der NFC-Normalisierung verwendet.
  • Operatoren werden von links nach rechts ausgewertet. Priorität ist: Klammern, Vergleiche, &&, dann ||. Das Kurzschließen gilt für && und ||.
  • Typen sind streng: numerische Vergleiche erfordern Zahlen; Gleichheit vergleicht nur Zeichenfolge zu Zeichenfolge, Zahl zu Zahl, Boolescher Wert zu Boolescher Wert. Kein Cross-Type-Zwang.
  • JSON-Datenreferenzen müssen aus Buchstaben (a-z, A-Z), Unterstrichen (_) oder Ziffern (0-9) bestehen. Das erste Zeichen muss ein Buchstabe oder ein Unterstrich sein.
  • Fehlende oder Null-JSON-Daten führen dazu, dass der Ausdruck bei der Auswertung auf "false" aufgelöst wird.
  • Ungültige Ausdruckssyntax in der Vorlage führt dazu, dass der Dokumentgenerator stoppt und einen Fehler zurückgibt.

Liste unterstützter Operatoren

NameBeschreibungBeispiel
==True, wenn der linke Operand gleich dem rechten Operanden istage == 18
!=True, wenn der linke Operand nicht gleich dem rechten Operanden istage != 18
>True, wenn der linke Operand größer als der rechte Operand istage > 18
>=True, wenn der linke Operand größer als oder gleich dem rechten Operanden istage >= 18
<True, wenn der linke Operand kleiner als der rechte Operand istage < 18
<=True, wenn der linke Operand kleiner als oder gleich dem rechten Operand istage <= 18
&&True, wenn der linke Ausdruck und der rechte Ausdruck true sinda == 0 && c == 42
||True, wenn der linke Ausdruck oder der rechte Ausdruck true ista == 0 || c == 42

Liste unterstützter Funktionen

NameBeschreibungBeispiel
StartsWithDatenreferenz beginnt mit der angegebenen ZeichenfolgeStartsWith(movieName, "The")
StartsWithIgnoreCaseDatenreferenz beginnt mit der angegebenen Zeichenfolge (Groß-/Kleinschreibung wird nicht beachtet)StartsWithIgnoreCase(movieName, "the")
ContainsDatenreferenz enthält die angegebene ZeichenfolgeContains(movieName, "Matrix")
ContainsIgnoreCaseDatenreferenz enthält die angegebene Zeichenfolge (Groß-/Kleinschreibung wird nicht beachtet)ContainsIgnoreCase(movieName, "matrix")

Beispiele

AusdruckKommentar
age >= 18
a == b || c == d && e > 0c == d && e > 0 wird vor a == b ausgewertet
(title=="manager" || title == "director") && employeeCount > 2Klammern können verwendet werden
StartsWith(movieName, "The") && year == 1999Funktion StartsWith verwendet
Contains(movieName, "Matrix") || movies.0.actor != "Pitt"Funktion Contains verwendet. Verweis auf ersten Akteur im Array movies
(numberOfTomatoes > maxTomatoes) == falseEntspricht: numberOfTomatoes <= maxTomatoes
-1 >= -1.01 || UnknownName == "Smith"Da der erste Teil wahr ist, wird UnknownName == "Smith" nicht ausgewertet
Contains(drink, "Cafe\u0301")Unicode-Zeichen werden unterstützt

Labels

Ein Arbeitsblatt kann nicht mehrere Schleifen oder Bedingungen mit demselben Namen enthalten, da es in einigen Situationen schwierig ist zu bestimmen, welche Starttags zu welchen Endtags gehören. Verwenden Sie den Modifizierer |label:, um Schleifen zu unterscheiden, die dasselbe Array oder dieselben Bedingtags referenzieren, die dieselbe Bedingung aufweisen. Beispiel: Dies ist nicht gültig:

{vl:items} ... {/items}
{vl:items} ... {/items}

Dies gilt jedoch:

{vl:items|label:1} ... {/items|label:1}
{vl:items|label:2} ... {/items|label:2}

Tag - Erweiterte Beispiele

Schleifenverschachtelung

Dieses Beispiel enthält drei verschachtelte Schleifen: zwei vertikale Schleifen und eine horizontale Schleife.

Daten

Die drei Schleifenebenen in den Daten sind genres, movies und actors.

{
  "genres": [
    {
      "name": "Comedy",
      "movies": [
        {
          "name": "Groundhog Day",
          "actors": [
            {
              "name": "Bill Murray",
              "birth_year": 1950
            },
            {
              "name": "Andie MacDowell",
              "birth_year": 1958
            }
          ]
        },
        {
          "name": "Notting Hill",
          "actors": [
            {
              "name": "Hugh Grant",
              "birth_year": 1960
            },
            {
              "name": "Julia Roberts",
              "birth_year": 1967
            },
            {
              "name": "Rhys Ifans",
              "birth_year": 1967
            }
          ]
        }
      ]
    },
    {
      "name": "Science Fiction",
      "movies": [
        {
          "name": "Arrival",
          "actors": [
            {
              "name": "Amy Adams",
              "birth_year": 1974
            },
            {
              "name": "Jeremy Renner",
              "birth_year": 1971
            }
          ]
        },
        {
          "name": "The Matrix",
          "actors": [
            {
              "name": "Keanu Reeves",
              "birth_year": 1964
            },
            {
              "name": "Carrie-Anne Moss",
              "birth_year": 1967
            },
            {
              "name": "Laurence Fishburne",
              "birth_year": 1961
            }
          ]
        }
      ]
    }
  ]
}

Vorlage


Vorlage

Ausgabe

Durchlauf der Schleifenerweiterung in diesem Beispiel

Schleifen werden in jedem Arbeitsblatt von der oberen Zeile bis zur unteren Zeile aufgelöst. Jede Zeile wird von links bis rechts verarbeitet.

  1. Die Schleife B2:D6 (Genres) wird vertikal eingeblendet.
  2. Die Schleife B3:D6 (movies - Comedy) wird horizontal erweitert.
  3. Die Schleife B5:D5 (Aktoren - Groundhog Day) wird vertikal erweitert.
  4. Die Schleife E5:G5 (Aktoren - Notting Hill) wird vertikal eingeblendet.
  5. Schleife B9:D13 (Filme - Science Fiction) wird horizontal erweitert.
  6. Die Schleife B11:D11 (Aktoren - Ankunft) wird vertikal eingeblendet.
  7. Schleife E11:G11 (Aktoren - Die Matrix) wird vertikal eingeblendet.

Ausgabe

Anmerkungen

  • Alle Tags in Schleifen werden im Kontext ihrer Schleife aufgelöst. In diesem Beispiel wird das Basis-Tag {name} in jeder Schleife mit einer anderen Bedeutung verwendet (Genrename, Filmname, Schauspielername).

Diagramme

In diesem Beispiel wird eine Vorlage verwendet, die zwei Diagramme enthält. Die Diagrammdaten stammen aus einem Zellenbereich, der eine vertikale Schleife enthält. Der Diagrammtitel bezieht sich auf eine Zelle, die ein Basis-Tag enthält.

Daten

{
  "chart_title": "Revenue/Expense",
  "months": [
    {
      "month": "January",
      "revenue": 23,
      "expense": 19
    },
    {
      "month": "February",
      "revenue": 24,
      "expense": 22
    },
    {
      "month": "March",
      "revenue": 25,
      "expense": 18
    }
  ]
}

Vorlage


Vorlage