CX_WORD_XML::Merge

CX_WORD_XML::Merge

Beschreibung:

Setzt alle Dokumentvariablen innerhalb des aufrufenden Word-Dokuments gemäß dem Plugspace.

Verweist eine Dokumentvariable auf ein CX_COM_OBJECT, CX_MULTIPLE_COM_OBJECT, CX_WORD_XML, oder ein CX_MULTIPLE_WORD_XML dann wird deren Dokument in die Dokumentvariable eingefügt (mit Bildern und sämtlicher Formatierung). Wenn ein Dokument viele Bilder enthält, dann kann das Zieldokument entsprechend groß werden. CX_WORD_XML versucht deshalb bereits importierte Bilder zu erkennen, damit gleiche Bilder nicht mehrfach importiert werden. Dies funktioniert jedoch nur bei CX_WORD_XML-Objekten. Verweist eine Dokumentvariable auf ein CX_COM_OBJECT, so wird dies vor jedem Einfügen in ein neues CX_WORD_XML-Objekt umgewandelt. Um also möglichst schnell zu mergen und möglichst kleine Zieldateien zu erhalten, sollten alle CX_COM_OBJECT-Objekte, die von Dokumentvariablen referenziert werden vor dem Merge in CX_WORD_XML-Objekte umgewandelt werden und im Zieldokument nur CX_WORD_XML-Objekte referenziert werden.

235380 können auch IF-, COMPARE-, =AND -und =OR-Felder (mit kleinen Einschränkungen) ausgewertet und ersetzt werden, wenn die Umgebungsvariable CX_WORD_XML_MERGE_MODE auf 1 gesetzt ist. Standardmäßig werden diese 4 genauso wie weitere Felder vom verwendeten Textverarbeitungsprogramm wie Microsoft Word oder LibreOffice ausgewertet, wobei nicht alle Programme alle Felder (vollständig) unterstützen.

Merge von CX_BITMAP

227732 unterstützt Merge auch das direkte Einfügen von Bilddateien, falls die Dokumentvariable auf ein CX_BITMAP zeigt. Dadurch wird das Bild direkt in das Word-Dokument eingefügt und im Gegensatz zum Feldbefehl INCLUDEPICTURE nicht einfach nur referenziert. Dadruch wird beim Aktualisieren der Felder von Word auch keine Sicherheitswarnung ausgegeben, da keine externen Dateien referenziert werden.

Die Größe des eingefügten Bilds errechnet sich aus der Bildauflösung (dpi) und der Bildgröße (in Pixeln). Für Bilddateien, die keine Auflösung in ihren Metadaten enthalten, wird eine Standardauflösung von 96 DPI angenommen (diese Auflösung wird auch von Word für solche Bilddateien genutzt).

Achtung: Jedes Bild muss BASE64 kodiert im XML abgelegt werden. Merge prüft bei Bildern nicht auf Duplikate, sodass durch mehrfaches Einfügen des gleichen Bildes das .docx-Dokument schnell sehr groß wird. Dieser Weg sollte deshalb nur für das Einfügen von dynamisch generierten Bildern (Bsp. QR-Codes) genutzt werden. Statische Bilder sollten über CX_WORD_XML -Objekte eingefügt werden, da Merge hier auf Duplikate prüft und die Bilddaten nur einmalig importiert.

Einfügesemantik von Merge

Wenn Dokumentvariablen gemerged werden, dann ist folgendes zu beachten:

• Dokumentvariablen, die auf STRINGs verweisen, werden dessen Zeilen absatzweise in das Dokument eingefügt. Jeder der Absätze hat die gleiche Formatierung. Sollte also eine Dokumentvariable, die in einem Aufzähungspunkt steht, aus mehreren Zeilen bestehen (also "\n" enthalten), dann wird jede Zeile in einem eigenen Aufzählungspunkt stehen.
• In Dokumentvariablen, die auf STRINGSs verweisen, können Tabs durch "\t" erzeugt werden.
• In Dokumentvariablen, die auf ganze Dokumente verweisen (CX_WORD_XML, CX_COM_OBJECT, ...), wird die Formatierung des Absatzes in welchem die Dokumentvariable erwähnt wird vollständig überschrieben mit der Formatierung des ersten Absatzes des einzufügenden Dokuments.
  Das hat unter anderem zur Folge, dass eine Dokumentvariable in einem Aufzählungspunkt nach dem Mergen ohne Aufzählungspunkt steht, weil das Quelldokument keine Aufzählung im ersten Absatz definiert hat.
  

  Zu den Formatierungen des Absatzes gehören:

  • Absatzeinstellung "Seitenumbruch oberhalb"
  • Tabstops
  • Textausrichtung (zentriert, linksbündig, ...)
  • Texteinzug
  • Abschnittswechsel/Absatzwechsel (aber kein Seitenumbruch)
  • Aufzählungszeichen
  • Schriftformatierungen, wenn sie auf den gesamten Absatz angewendet wurde.
• Dies hat auch zur Folge, dass wenn sich zwei Dokumentvariablen im gleichen Absatz befinden, die letzte von beiden die gesamte Formatierung des Absatzes bestimmt.
• Da es erlaubt ist, Dokumentvariablen in IF-Bausteine einzubauen, werden Dokumente in einem QUOTE-Baustein gekapselt eingefügt, damit deren Anführungszeichen nicht die Semantik des IF-Bausteins beeinflussen. Wenn die Dokumentvariable auf einen STRING zeigt, dann wird jedes Anführungszeichen einzeln durch einen QUOTE-Baustein geschützt.
• Word hat eine Limitierung, die besagt, dass sich nicht mehr als 20 Bausteine in einem anderen Baustein befinden dürfen. Somit sollte darauf geachtet werden, dass wenn eine Dokumentvariable in einem anderen Baustein steht, der STRING auf welchen sie verweist maximal 20 Anführungszeichen besitzt. Sollte die Dokumentvariable auf ein Dokument verweisen, dann darf dieses Dokument wiederum maximal 20 Bausteine enthalten.

Um Probleme zu vermeiden sollten folgende Richtlinien beachtet werden:

• Pro Absatz sollte es höchstens eine Dokumentvariable geben, die auf ein richtiges Dokument (und damit auf Formatierungsinformationen) verweist.
• Sollte eine Dokumentvariable auf eine Dokument verweisen, dann sollte der Absatz entweder nur aus dieser Dokumentvariable bestehen, oder keine Formatierungen enthalten.
• Dokumentvariablen, die auf Dokumente verweisen sollten durch Absätze getrennt werden und nicht durch einfache Zeilenumbrüche (Shift+Enter). Zeilenumbrüche können durch Absätze simuliert werden, indem in den Absatzeinstellungen oberen Absatzes Abstand nach auf 0 Pt. gestellt wird.
• Wenn irgendwie möglich sollte zum Einfügen von ganzen Dokumenten PutFormattedText verwendet werden.
• Dokumentvariablen in anderen Word-Bausteinen, wie IF sollte vermieden werden.

Auswertung von Bedingungs- und Vergleichsfelder

235443 können bei Bedarf, wenn beispielsweise das verwendete Textverarbeitungsprogramm wie LibreOffice nicht alle Felder im gewünschtem Umfang unterstützen, die IF-, COMPARE-, =AND -und =OR-Felder auch direkt von dieser Methode ausgewertet und ersetzt werden. Dafür muss die Umgebungsvariable CX_WORD_XML_MERGE_MODE auf 1 gesetzte werden. Für jedes CX_WORD_XML-Objekt wird dieser Wert dabei jeweils beim Erzeugen oder beim Laden der Instanz abgefragt.

Dabei ist zu beachten, dass in Ausnahmefällen das Ergebnis nicht identisch mit dem Ergebnis nach der Auswertung in Microsoft Word ist. Grund hierfür ist vor allem, dass Formschalter von dieser Methode nicht berücksichtigt werden. Zudem können nach dem Auflösen der Felder nicht mehrere Absatz-Eigenschaften in einem Absatz berücksichtigt werden. So kann im Open-XML-Format einer .docx Datei beispielsweise nur eine Einzugsweite pro Absatz berücksichtigt werden. Endet jedoch der ausgewertete Inhalt eines Felds, das im unausgewerteten Zustand in einem anderen Absatz endet, im ursprünglichen Absatz mit bereits vorhandenen Eigenschaften, dann kann Microsoft Word beim Anzeigen nur beide Eigenschaften berücksichtigen, da intern es noch verschiedene Absätze sind. Da hier die Felder jedoch zu normalen Textblöcken umgewandelt werden, können Eigenschaften durch die Eigenschaften ursprünglich späterer Absätze überschrieben werden. Style-Eigenschaften wie das Schriftbild oder die Farbe einzelner Zeichen/Wörter sind von dieser Einschränkung nicht betroffen und sollten nach der Auswertung von dieser Methode genauso vorhanden sein, wie nach der Auswertung in Microsoft Word.

Code-Beispiel:

Var(com, targetXml, insertXml, txn)

//Einzufügendes Dokument initialisieren
CreateTransObject(CX_WORD_XML) -> insertXml
insertXml Call(EmptyDocument)
"Dies wurde eingefügt" insertXml Call(PutText)

//Zieldokument öffnen und in XML umwandeln
CreateTransObject(CX_COM_OBJECT) -> com
"C:\\mywordDoc.docx" com Call(LoadFromFile)
com GetManager(COM) Call(GetToolObject) Call(GetXML) -> targetXml

//Plugspace setzen
CreateTransObject(CX_LINK_TXN) -> txn
insertXml txn Link(wordDoc) //Damit das Beispiel funktioniert sollte im Zieldokument die Dokumentvariable "wordDoc" vorkommen
[ txn ] PlugSpace

targetXml Call(Merge)
targetXml Call(AsCOM) Call(CX_Open)

Funktionsaufruf: Call(Merge)