Snippet Resolver

Owned by Daniela Zimmermann
Last updated: Jun 16, 2023 by Dinah Bolli
10 min read

Über den SnippetResolver können Texte in ein Dokument eingefügt werden. Die Texte können hierfür auf verschiedene Arten spezifiziert werden:

  • Es können primedocs interne Textbausteine über die "id" festgelegt werden.

  • Es können primedocs externe Textbausteine in Text oder im HTML-Format übermittelt werden.

  • Der Inhalt kann im OPC-Flat Format übergeben werden.

Grundsätzlich gehen alle Varianten nach demselben Schema vor: Man übergibt den Inhalt und definiert über ein Bookmark in der Vorlage wo dieser Inhalt eingefügt wird. Die Anzahl der Textbausteine ist dabei beliebig. Inhalte, die während der Vorlagenerstellung in dem Bookmark hinterlegt wurden, werden dabei mit den neuen Inhalten ersetzt.

HINWEIS
Der entsprechenden Vorlage muss die Dokumentfunktion SnippetResolver ("Textbausteine") angehängt sein.

Schnellbausteine

Es gibt zudem noch eine weitere Funktion die der "SnippetResolver" übernimmt. primedocs Textbausteine können als "AutoText" bzw. "Schnellbausteine" in die generierte Vorlage hinterlegt werden. Die so eingebundenen "AutoText" Textbausteine stehen damit als normale Schnellbausteine in Microsoft Word zur Verfügung.

Im Standardfall werden automatisch immer alle "AutoText" Textbausteine die dem Benutzer zur Verfügung stehen hinterlegt. Dieses Verhalten kann sowohl über die Konfiguration der Dokumentfunktion bzw. über Connect über dieses "Setting" übersteuert werden:

<?xml version="1.0" encoding="UTF-8"?> <OneOffixxConnectBatch xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Entries> <OneOffixxConnect> <Arguments> ... </Arguments> <Function name="SnippetsResolver" id="dd752747-733e-4175-9fc7-028ab7472742"> <Settings> <Value key="AutoTextDisabled">true</Value> </Settings> <Arguments> ... </Arguments> </Function> </OneOffixxConnect> </Entries> </OneOffixxConnectBatch>

primedocs Textbausteine

Folgendes Szenario: Es soll ein neues Dokument erstellt und mit Textbausteinen (Snippets) befüllt werden. Die Id des Textbausteins kann mit Hilfe des Textbausteineditors ausgelesen werden. Jede Id ist eindeutig und ändert sich nach dem Anlegen nicht mehr. Die Sprache wird über die Dokumentsprache festgelegt.

<?xml version="1.0" encoding="UTF-8"?> <OneOffixxConnectBatch xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Entries> <OneOffixxConnect> <Arguments> <TemplateId>6bb49520-1ebd-4f68-bb5f-02f46a9e1ec8</TemplateId> <LanguageLcid>2055</LanguageLcid> </Arguments> <Function name="SnippetsResolver" id="dd752747-733e-4175-9fc7-028ab7472742"> <Arguments> <Snippet id="A7835D23-E945-4A39-81B9-3CEC067E26C0" bookmark="Bookmark1" /> <Snippet id="B8235D23-D945-5A39-31B9-23EC067E2120" bookmark="Bookmark1" /> <Snippet id="43535D23-45D5-6A39-81B9-DE1C067E2112" bookmark="Bookmark2" /> <Snippet id="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" bookmark="Bookmark3" /> </Arguments> </Function> </OneOffixxConnect> </Entries> </OneOffixxConnectBatch>

Mehrere Textbausteine können in einer Textmarke (z. B. "Bookmark1") gruppiert werden, indem im Attribut "Bookmark" der gleiche Name steht. Die Textbausteine werden in der gleichen Reihenfolge eingebaut wie sie im XML stehen. Es ist auch möglich, den "_OneOffixxOpenAt"-Bookmark zu verwenden. Dadurch wird der Text an der Cursor-Position, die in der primedocs Vorlage definiert ist, eingefügt.

Externe "Text"-Textbausteine

Möchte man aus einer Fachapplikation unformatierten Textinhalt übergeben, kann man dies so erreichen:

<?xml version="1.0" encoding="UTF-8"?> <OneOffixxConnectBatch xmlns="http://schema.oneoffixx.com/OneOffixxConnectBatch/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Entries> <OneOffixxConnect> <Arguments> <TemplateId>6bb49520-1ebd-4f68-bb5f-02f46a9e1ec8</TemplateId> <LanguageLcid>2055</LanguageLcid> </Arguments> <Function name="SnippetsResolver" id="dd752747-733e-4175-9fc7-028ab7472742"> <Arguments> <Snippet bookmark="Bookmark3"> Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas porttitor congue massa. Fusce posuere, magna sed pulvinar ultricies, purus lectus malesuada libero, sit amet commodo magna eros quis urna. Nunc viverra imperdiet enim. Fusce est. Vivamus a tellus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin pharetra nonummy pede. Mauris et orci. Aenean nec lorem. In porttitor. Donec laoreet nonummy augue. Suspendisse dui purus, scelerisque at, vulputate vitae, pretium mattis, nunc. Mauris eget neque at sem venenatis eleifend. Ut nonummy. </Snippet> </Arguments> </Function> </OneOffixxConnect> </Entries> </OneOffixxConnectBatch>

Externe "HTML"-Textbausteine

Um formatierten Inhalt in das Dokument einzufügen, empfiehlt es sich den Inhalt als "HTML"-Snippet zu übergeben. primedocs bietet einen eigenen HTML-Parser und erkennt zudem primedocs eigene Attribute um Style- und Formatierungsoptionen direkt in OpenXML Eigenschaften zu übersetzen.

Grundaufbau

Der Aufbau ist fast identisch, jedoch wurde ein zusätzlicher Parameter "parser" beim Snippet hinzugefügt. Im "parser" muss "primedocs" angegeben werden.

primedocs-Attribute

Um Style- oder "Rendering"-Informationen weiterzugeben, können folgende Attribute genutzt werden:

  • data-oo-style: Der angegebene Style wird dem entsprechenden Open-XML Element zugewiesen.

    • Styles können auf <p>, <ul> / <ol> oder <table>-Elemente angewendet werden.

  • data-oo-align: Definiert die Ausrichtung.

    • Mögliche Werte: left, right, center

    • Das Attribut kann auf <p>, <td> oder <th>-Elemente angewendet werden

  • data-oo-table-...: Definierte Angaben für <table>-Elemente.

  • data-oo-image-...: Definierte Angaben für <img>-Elemente.

  • data-oo-background: Definiert eine Hintergrundfarbe.

    • Mögliche Werte: HEX-Farbcodes, z. B. E2001A

    • Das Attribut kann auf Absatz (<p>, <h1>, etc.), <td> oder <th>, oder Text (<span>, <strong>, etc.)-Elemente angewendet werden.

  • data-oo-foreground: Definiert eine Schriftfarbe.

    • Mögliche Werte: HEX-Farbcodes, z. B. E2001A

    • Das Attribut kann auf Absatz Text (<span>, <strong>, etc.)-Elemente angewendet werden.

WICHTIG
Es können nur bestehende Styles verwendet werden, d.h. diese müssen im Wordprocessing-Dokument bzw. in der Style-Vorlage existieren. Zudem wird die 'StyleId' genutzt, welche von dem angezeigten Name in Microsoft Word abweichen kann. (z. B. aus 'Überschrift 1' kann Office eine Style mit der Id 'berschrift1' erstellen).
Falls ein Style bei einer Liste verwendet wird, wird dieser nur angewandt, wenn an diesem Style 'Auflistungsformatierungen' definiert sind.

HINWEIS

Zu CSS und anderen Attributen:
CSS Angaben oder Attribute werden (bis auf die Ausnahmen "colspan" bei der Tabelle und "src" bei Bildern) ignoriert.

Zu Textangaben:
Der Parser kann sowohl UTF8 als auch HTML kodierte (z. B. ü) Texte direkt ins Open XML wandeln. Ausgenommen davon sind folgende Zeichen, die zwingend in HTML encodiert werden müssen:

Typographie-Elemente

Diese Elemente werden in die entsprechenden OpenXML Elemente umgewandelt. Dabei wird versucht, den jeweiligen Stil einzuhalten, sodass ein <b> entsprechend "fett" formatiert wird.

Elemente für OpenXML Paragraphen:

  • <p>

  • <h1>, <h2>, <h3>, <h4>, <h5>, <h6>

  • <pre>,<blockquote>,<address>

Elemente für OpenXML Text:

  • <span>

  • <u>

  • <s>

  • <sub>

  • <sup>

  • <i>

  • <em>

  • <b>

  • <strong>

  • <code>,<time>,<label>

  • <a> (nur der Link-Text wird übernommen)

Elemente für OpenXML-Linien:

  • <hr>

    • Optionale Attribute:

      • data-oo-hr-type="---": Erzeugt eine Linie ähnlich wie beim AutoFormat "---"

      • data-oo-hr-type="___": Erzeugt eine Linie ähnlich wie beim AutoFormat "___"

      • data-oo-hr-type="###": Erzeugt eine Linie ähnlich wie beim AutoFormat "###"

      • data-oo-hr-type="~~~": Erzeugt eine Linie ähnlich wie beim AutoFormat "~~~"

      • data-oo-hr-type="***": Erzeugt eine Linie ähnlich wie beim AutoFormat "***"

      • data-oo-hr-type="===": Erzeugt eine Linie ähnlich wie beim AutoFormat "==="

    • Ohne Attributangabe wird ein Linienelement erzeugt.

Elemente für OpenXML-Zeilen-, Spalten- oder Seitenumbrüche:

  • <br>

    • Optionale Attribute:

      • data-oo-br-type="textWrapping": Erzeugt einen Zeilenumbruch.

      • data-oo-br-type="page": Erzeugt einen Seitenumbruch.

      • data-oo-br-type="column": Erzeugt einen Spaltenumbruch, falls der Abschnitt mehrere Spalten enthält.

    • Ohne Attributangabe wird ein normaler Zeilenumbruch erzeugt.

Elemente in denen nach bekannten Kindelementen gesucht wird:

  • <html>,<body>,<form>,<div>

Verschachtelte <p>- oder <h1>-(etc.) Elemente werden nicht unterstützt. Diese Elemente sind auch laut HTML-Spezifikation nicht dafür ausgelegt.

Bild-Elemente

Bilder können als Data-URL übermittelt werden.

Elemente:

  • <img>

 

Unterstützte Bildformate (angegeben über den MIME-Type in der Data-URL) sind:

  • image/bmp

  • image/png

  • image/gif

  • image/jpeg

  • image/tiff

 

primedocs-Attribute:

  • data-oo-image-title: definiert den (optionalen) Titel eines Bildes.

    • Das Attribut kann auf <img>-Elemente angewendet werden.

  • data-oo-image-desc: definiert die (optionale) Beschreibung eines Bildes.

    • Das Attribut kann auf <img>-Elemente angewendet werden.

  • data-oo-image-width: definiert die Breite des Bildes im Dokument.

    • Das Attribut kann auf <img>-Elemente angewendet werden.

    • Es wird eine Zahl ohne Komma erwartet.

  • data-oo-image-height: definiert die Höhe des Bildes im Dokument.

    • Das Attribut kann auf <img>-Elemente angewendet werden.

    • Es wird eine Zahl ohne Komma erwartet.

  • data-oo-image-sizeunit: definiert die Einheit. Standardmässig wird Pixel (px) gewählt.

    • Mögliche Werte: px, cm, mm

    • Es wird eine Zahl ohne Komma erwartet.

    • Weitere Informationen im Abschnitt Bilder.

 

Bilder können im Fliesstext, als einzelner Paragraph, in Listen oder Tabellen eingesetzt werden.

Für die Berechnung der Bildgrösse gibt es verschiedene Varianten:

  • Falls keine expliziten Höhen- ("data-oo-image-height") oder Breiten-("data-oo-image-width") Angaben vorhanden sind, wird die Pixel-Grösse des Bildes genutzt.

  • Falls eine Höhen- oder Breiten-Angabe vorhanden ist, wird das Seitenverhältnis des Ursprungsbild beibehalten und entsprechend die Grösse berechnet.

  • Falls sowohl Höhen- als auch Breiten-Angaben vorhanden sind, werden diese als Grösse genutzt – egal welches Seitenverhältnis das Bild hat.

Optional können über die "data-oo-image-title" und "data-oo-image-desc" Beschreibungen im OpenXML hinterlegt werden.

Tabellen-Elemente

HTML Tabellen können ebenfalls umgewandelt werden, jedoch werden ohne Style-Angabe, die später thematisiert wird, keine Tabellenränder oder ähnliches dargestellt.

 

Elemente:

  • <table>

  • <thead> - innerhalb der <table>

  • <tbody> - innerhalb der <table>

  • <tfoot> - innerhalb der <table>

  • <tr> - innerhalb von <thead>, <tbody> oder <tfoot>

  • <td> - innerhalb von <tr>

  • <th> - innerhalb von <tr>

  • Alle Typographie-Elemente, Bilder und Input-Controls innerhalb eines <td>

  • Listen innerhalb eines <td>

  • Tabellen innerhalb eines <td>

Das "colspan"-Attribut gilt für <td>-Elemente.

 

primedocs-Attribute:

  • data-oo-table-width: definiert die Breite der Tabelle in Prozent oder "Twip" (1cm = 567). Ist optional wenn data-oo-table-columns-Werte als cm Angabe gemacht werden.

    • Das Attribut kann auf <table>-Elemente angewendet werden.

  • data-oo-table-width-unit: Pct/Dxa/Nil/Auto. Standardmässig wird Pct genommen. Dxa steht für die Twip-Angabe.

    • Das Attribut kann auf <table>-Elemente angewendet werden.

  • data-oo-table-layout: Fixed/AutoFit. Standardmässig wird Fixed genommen. Bei AutoFit wird bei überlangen Spalten die jeweilige Spalte vergrössert.

    • Das Attribut kann auf <table>-Elemente angewendet werden.

  • data-oo-table-columns: definiert die Breite der jeweiligen Spalten innerhalb einer Tabelle in Prozent oder als cm-Angaben.

    • Das Attribut kann auf <table>-Elemente angewendet werden.

    • Die Werte sind kommasepariert, jeweils pro Spalte, anzugeben.

  • data-oo-table-look-*: Durch diese Attribut kann die Word-Tabelle genauer spezifiziert werden, z. B. ob eine Ergebniszeile sichtbar ist oder nicht. Die Eigenschaften decken sich mit den TableLook-Properties vom OpenXML SDK.

  • data-oo-table-look-firstRow: True/False - Überschrift: Besondere Formatierung für die erste Zeile anzeigen.

  • data-oo-table-look-lastRow: True/False - Ergebniszeile: Besondere Formatierung für die letzte Zeile anzeigen.

  • data-oo-table-look-firstColumn: True/False - Erste Spalte: Besondere Formatierung für die erste Spalte anzeigen.

  • data-oo-table-look-lastColumn: True/False - Letzte Spalte: Besondere Formatierung für die letzte Spalte anzeigen.

  • data-oo-table-look-noHBand: True/False - Gebänderte Zeilen: Besondere Formatierung für gerade bzw. ungerade Zeilen anzeigen.

  • data-oo-table-look-noVBand: True/False - Gebänderte Spalten: Besondere Formatierung für gerade bzw. ungerade Spalten anzeigen.

Input-Control-Elemente

Bestimmte HTML-Input Controls können auch in das jeweilige Open XML "Custom-Control" umgewandelt werden.

 

Elemente:

  • <input type="checkbox" >

    • Das "checked" Attribut wird ausgewertet.

  • <input type="datetime" >

    • Das "value" Attribut wird ausgewertet.

  • <input type="text" >

    • Das "value" Attribut wird ausgewertet.

  • <textarea >

    • Der Textinhalt wird ausgewertet.

Diese Controls können sowohl einzeln auch auch im normalen Textfluss stehen.

Listen-Elemente

HTML Listen können ebenfalls umgewandelt werden, jedoch werden diese nur mit minimalen Style-Angaben versehen, falls man keinen expliziten Style angibt.

 

Elemente:

  • <ul> - ohne Style-Angabe als Bullet-List dargestellt.

  • <ol> - ohne Style-Angabe als Numeric-List dargestellt.

  • <li> - innerhalb von <ul> oder <ol>

  • Alle Typographie-Elemente, Bilder und Input-Controls innerhalb eines <li>

  • Verschachtelte Listen, wobei der 'Numbering'-Style der Hauptliste beibehalten wird, innerhalb eines <li>

 

Hinweis zu Word-Listen und Absatz-Styles:

Listen werden im Word über zwei verschiedene Arten von "Word-Formatvorlagen", also von Styles, gesteuert. Es gibt "Listentypen", welche die Einrückung, Zeichen und Nummerierung steuern (z. B. die Zahlen 1. und 1.1 und 1.1.1). Diesem Listentyp kann ein anderer Style angehängt werden, der sich auf den eigentlichen Text neben der Nummerierungsangabe auswirkt. Damit primedocs die HTML-Liste entsprechend richtig konvertieren kann, sollte folgendes Vorgehen eingehalten werden:

Pro "Haupt"-'<ul>' bzw. '<ol>' sollte ein Listentyp definiert werden. Dieser Listentyp sollte mit einem Style (z. . "ListText") verbunden werden. Im Connect gibt man immer nur den Namen des eigentlichen Style (z. B. wie oben "ListText") an – der Listentyp ist indirekt verknüpft. Aktuell ist es erforderlich auf jeder neuen "<ul>" bzw. "<ol>" Ebene den Style anzugeben. Man kann auch verschiedene Styles verwenden. Ohne Angabe nutzt Word den Standardabsatz-Style.

 

Zusammenfassung:

Man kann beliebig viele Styles erstellen um den Text in einer Liste zu formatieren. Das muss jeweils auf jeder Ebene angegeben werden. Man muss einen Listentyp erstellen, welcher mit dem "primären" Style verbunden ist. Dieser Listentyp steuert die Nummerierung, Einrückungen etc.

Beispiel

Externe "Office HTML" Textbausteine

Bei der Übermittlung von HTML Inhalten, ist der "type" Html anzugeben. Es können generell alle von Microsoft Office zugelassenen HTML Inhalte übermittelt werden.

 

Einfache Texte:

 

Texte in definiertem Word-Style:

Überschriften wie H1-H4 sowie die normalen Formatierungen (bspw. fett resp. <strong>) werden automatisch in den entsprechenden Überschriftenstyle (bspw. <h1> = Überschrift1) dargestellt.

Texte können durch die Angabe von "mso-style-name:" einem bestimmten Word-Style zugeordnet werden.

 

Tabellen:

Als HTML können auch Tabellen übermittelt werden.

 

Bilder:

Bilder können als Data-URI übermittelt werden.

Externe "FlatOPC"-Textbausteine

Es können auch Textbausteine im Flat OPC Format entgegen genommen werden. Dabei werden allerdings keine Styles oder Numberings übernommen, sondern nur der Body-Part. Die Variante sollte nur in Ausnahmefällen genutzt werden, da der primedocs HTML Parser mit Style-Informationen umgehen kann und somit die bessere Wahl darstellt.

 

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland