Mit Hilfe des Modules kann auf Daten zugriffen werden, die in XML-Dateien definiert sind.
Die Funktionen des Moduls xmlquery dienen der Unterstützung der
gleichnamigen Abfragesprache xmlquery zur einfachen Bearbeitung von XML-Dateien.
Vor der Ausführung einer xmlquery-Anweisung werden alle
in der Anweisung enthaltenen Tags der aktuellen Anweisungsumgebung
und alle Funktionsvariablen durch ihre aktuellen Werte ersetzt.
Wichtiger Hinweis: xmlquery benötigt zur Auswertung von where-Bedingungen eine vollständig definierte XML-Struktur.
Fehlende Elemente und Attribute können mit dummy-Definitionen in den xentities definiert werden.
Die xmlquery Abfragesprache hat die folgenden Schlüsselwörter:
and und or in den where-Bedingungen mit der üblichen Bindung and vor or,
A || B && C hat also die Bedeutung A || (B && C)
Mit Hilfe des Programmes xmlquery können Sie XML-Query-Anweisungen testen.
Als Bezeichner für die Datenspalten werden die Elementnamen und Attribute der XML-Datei verwendet.
Für die Namen von Elementen und Attributen gelten die für XML gültigen Regeln:
Namen müssen mit einem Buchstaben oder Underscore (_) beginnen. Unicode-Buchstaben wie ä, ö, ü, א (U+05D0), ... sind erlaubt.
Namen dürfen nicht mit xml beginnen. Auch alle anderen Schreibweise wie XML oder Xml sind verboten.
Namen dürfen aus folgenden Zeichen bestehen:
Buchstaben Alle Buchstaben. Unicode-Buchstaben wie ä, ö, ü, א (U+05D0), ... sind erlaubt.
Ziffern 0-9
Worttrenner
Minus (-)
ARMENIAN HYPHEN (֊ U+058A)
MONGOLIAN TODO SOFT HYPHEN (᠆ U+1806)
KATAKANA-HIRAGANA DOUBLE HYPHEN (゠ U+00A0)
SMALL HYPHEN-MINUS (﹣ U+FE63)
FULLWIDTH HYPHEN-MINUS (－ U+FF0D)
DOUBLE OBLIQUE HYPHEN (⸗ U+2E17)
HYPHEN WITH DIAERESIS (⸚ U+2E1A)
CANADIAN SYLLABICS HYPHEN (᐀ U+1400)
DOUBLE HYPHEN (⹀ U+2E40)
Es gibt noch einige weitere Worttrenner, aber diese Zeichen werden bereits vom XML-Parser (jedenfalls auf dem Mac) abgelehnt.
Weitere Zeichen
Underscore (_)
Punkt (.)
Doppelpunkt (:)
Namen sind case-sensitive. Name und name bezeichnen also zwei verschiedene Elemente.
Enthalten die Namen andere Zeichen als Buchstaben, Zahlen, Underscore (_) oder Doppelpunkt (:), müssen die Spaltenname einzeln in
Accent Graves (z.B. `namespace.name`) eingeschlossen werden.
Dann können mit folgender Anweisung alle Adressen ermittelt werden, deren Büroadresse mit A beginnen. Beachten Sie
bitte auch, dass das Attribut tür keine Anführungszeichen benötigt (aber natürlich haben darf).
select `pp.büro`, `pp.büro`.tür
node `pp.adrässe⸗1`.`pp.förma`
where `pp.büro` like 'A%'
Elementpfade werden aus den durch Punkte (.) getrennten Elementnamen zusammengesetzt. (Einer der Gründe für die `-Anführungszeichen, wenn ein
Name einen Punkt enthält.)
Verweis auf die ID eines Unterobjektes
productdata.object.sub.id
[Ab v4.2 R32300] Mit dem Elementnamen child_N (mit N = {0, 1, ...}) können Sie
auf das (0-basierte) n-te Unterelement eines Elementes zugreifen. Der Name des Unterelementes wird dabei ignoriert.
Bitte beachten Sie, dass Attribute wie Elemente gezählt werden!
Verweis auf die ID des vierten Unterobjektes
productdata.child_3.id
Im Beispiel zeigt row.child_0 auf das Attribut row.num und row.child_3.name ist 'B'.
Auf übergeordnete Elemente kann mit .. zugegriffen werden. Drei Punkte bezeichnet zwei Ebenen weiter oben usw..
Die Mehrfachpunkte sind nur am Beginn eines Spaltennamens erlaubt.
Zugriff auf das Objekt aus der Ebene \span[src]{sub
..sub
In where-Bedignungen wird . (Punkt) durch den eigenen Inhalt ersetzt.
Mit folgender Anweisung kann der Displayname eines bestimmten keyattribute erfragt werden,
für A_FURNITURE_TYPE der Werbung mit der ID 228056984 also "Möbeltyp".
Im Normalfall kann auf eine Unterscheidung von Attributen und Elementen verzichtet werden. Nur wenn es Attribute mit
dem gleichen Namen wie direkte UnterElemente gibt, muss eine Unterscheidung gemacht werden. Dem Attributnamen wird
dafür ein @ (wie Attribut) vorangestellt. Elemente werden mit $ gekennzeichnet.
Fehlt die Kennzeichnung, werden die Attribute verwendet.
Unterscheidung der ids eines Objektes
@id
$id
CDATA-Blöcke in den XML-Dateien werden berücksichtigt und beim Schreiben der Dateien wiederhergestellt. Soll ein Element-Wert mit Hilfe
von CDATA definiert werden, können die Methoden xmlquery::send_cdata_begin und send_cdata_end oder xmlquery::input mit der
Typdefinition kCDATA verwendet werden. Innerhalb von CDATA-Blöcken darf der String ![[[CDATA[ nicht verwendet werden.
Anweisungen beginnen mit der (optionalen) Definition der Funktionsvariablen.
Danach wird zwingend die XML-Datei erwartet, auf der die Anweisung ausgeführt werden soll.
Schließlich folgt die eigentliche Anweisung:
Als Dateidefinition wird ein vollständiger Pfad zur XML-Datei erwartet.
Der Pfad darf mit einem definierten Alias beginnen.
In XML-Offline Datenverbindungen werden unvollständige Pfade zudem relativ zum Datenordner aufgelöst.
Selects beginnen mit einem der beiden (gleichwertigen) Schlüsselwörter select oder xmlget.
Danach folgt die Liste der Ergebnisspalten. Optional kann die Ergebnisliste durch eine vorangestellte
distinct-Definition auf eindeutige Ergebnisse reduziert werden.
Nach der Festlegung der Ergebnisse geben Sie die XML-Elemente an, in den gesucht werden soll. Die Suche
startet immer im Root-Element der gegebenen XML-Datei.
Mit einer orderby-Definition können die Ergebnisse zum Schluß sortiert werden.
Mit Hilfe des Schlüsselwortes distinct können die Ergebnisspalten
von select bzw. xmlget auf eindeutige Ergebnisse resuziert werden.
Fügen Sie dazu zwischen select und dem ersten Spaltennamen eine der
folgenden Angaben ein:
distinct : Die Ergebnisse sind in mindestens einer Spalte unterschiedlich
distinct(colName [, colname]) : [Ab v4.2 R32300] Die Ergebnise sind in der Kombination der angegeben Elementpfaden eindeutig.
Nicht in der Ergebnisliste enthaltene Spaltennamen werden ignoriert.
Als Ergebnisse eines Selects geben Sie eine komma-getrennte Liste von Elementpfaden und konstanten Werten (Zahlen und Strings) an.
Die Ergebnisse können zuätzlich mit Funktionenoder einfachen Operatoren bearbeitet werden:
Die Elementpfade beginnen immer beim letzten Element der node-Selektoren.
Darüberliegene Elternwerte können mit der Punkt-Notation erreicht werden.
Als Werte sind Elementpfade und Konstaneten (Ganzzahlen, Kommazahlen und Strings) erlaubt.
Elementpfade beginnen beim letzten Element der node-Selektoren.
Darüberliegene Elternwerte können mit der Punkt-Notation erreicht werden.
In Kommazahlen werden Punkt (.) und Komma (,) als Dezimaltrenner akzeptiert.
In den Rückgabespalten dürfen einfache Berechnungen gemacht werden. Die Formeln dürfen Spaltennamen enthalten, deren
aktuelle Werte vor jeder Berechnung eingesetzt werden. Erlaubt sind die folgenden Operatoren :
Klammerungen sind bisher nicht vorgesehen. Um zwischen Vorzeichen und Operatoren unterscheiden zu können, muss zwischen + bzw. -
und dem folgenden Wert ein Leerzeichen stehen. Die Bearbeitung der Formeln geschieht strikt von links nach rechts, alle Operatoren haben
die selbe Wertigkeit. Wenn möglich, werden Ergebnisse als Ganzzahlen dargestellt. Hier einige Beispiele:
1 + 2 * 3 = 9 // und nicht 7
1.1 + 1.8 = 2.900000 // aber 1.1+1.9 = 3 (ohne Nachkommastellen)
2 * id || name = "24Name" // mit id=12 und name="Name"
2 * id || name + 3.1 = 27.1 // mit id=12 und name="Name", name ist nicht in Zahl konvertierbar, also gleich 0
Zur Berechnung von Strings stehen die folgenden Funktionen zur Verfügung :
lower (str) : Umwandlung in Kleinbuchstaben
upper (str) : Umwandlung in Großbuchstaben
trim (str) : Entfernen von Whitespace um den String
reverse (str) : Umkehren des Strings
substr (str, from, len) : Teilstring ab from (0-basiert) der Länge len
rsubstr (str, from, len) : Wie substr, aber ausgehend vom Str#6#69;ng-Ende
token (str, n, delim_str) : n-tes Token des durch das erste Zeichen delim getrennten String.
Als Trenner sind nur ASCII-Zeichen erlaubt! Andere Zeichen können zum Absturz des Programmes führen!
[Since v4.1 R20224] folder (str)
[Since v4.1 R20224] file (str)
[Since v4.1 R20224] filename (str)
[Since v4.1 R20224] shortfilename (str)
[Since v4.1 R20224] extender (str)
Auch hier sind nur einfache Aufrufe erlaubt. Insbesondere dürfen die Parameter der Funktionen keine weiteren Berechnungen enthalten.
Hat ein Element oder Attribut ihrer XML-Datei einen der oben angegebenen Funktionsnamen,
muß dieser Name im Aufruf in Accent Graves (`..`) eingeschlossen werden, statt select filename node ... also select `filename` node ... .
node-Selektoren bestimmen die Auswahl der XML-Elemente, in denen die Anweisung suchen soll.
Sie bestehen jeweils aus einem Elementpfad und einer where-Bedingung.
Die Auswertung beginnt immer beim Root-Element der XML-Struktur und
die node-Selektoren müssen insgesamt einen einen durchgängigen Elementpfad beschreiben.
Der erste Selector beginnt also immer beim Root-Element der XML-Srtuktur.
Weitere node-Selektoren können den Elementpfad fortsetzen.
Die Ergebnisspalten setzen beim letzten Element der node-Selektoren auf.
Mit folgender Anweisung kann der Displayname eines bestimmten keyattribute erfragt werden,
für A_FURNITURE_TYPE der Werbung mit der ID 228056984 also "Möbeltyp".
Wichtiger Hinweis: xmlquery benötigt zur Auswertung von where-Bedingungen eine vollständig definierte XML-Struktur.
Fehlende Elemente und Attribute können mit dummy-Definitionen in den xentities definiert werden.
Mit Bedingungen kann die Menge der Elemente auf der Ebene jedes node-Selektors eingeschränkt werden.
Bedingungen können mit and und or verknüpft und geklammert werden. Auf der
linken Seite der Vergleiche sind Funtionen erlaubt:
and and or haben die allgemein Bindung and vor or,
A || B && C bedeutet also A || (B && C)
Das Ergebnis einer Bedingung wird durch den jeweiligen Vergleichsoperator bestimmt. Dabei gilt:
Bezeichner, die auf id oder sequencenr (case insensitive) enden oder mit id
beginnen und an dritter Stelle eine Zahl haben (etwa id2 oder id2Xid3)
erwarten als Vergleichswerte Ganzzahlen. Mit Hilfe der Konfigurationsdatei xentities.xml kann der Datentyp von Elementen
speziell festgelegt werden, mehr dazu siehe hier.
Am Schluß des Befehls kann ein orderby folgen.
Dahinter stehen ein oder mehrere, durch Komma getrennte Elementpfaden.
Erlaubt sind nur Elementpfaden, die auch in den Ergebnisspalten vorkommen.
Es dürfen bis zu 10 Sortierfelder angegeben werden:
Sortiert wird nach folgenden Kriterien:
Spalten mit den (case insensitiven) Namen "Date" oder "Datum" werden als Datum/Uhrzeit sortiert
Nach dem in den Typdefinitionen festgelegten Datentyp der Spalte
Spalten mit den (case insensitiven) Namen "Id" oder "Sequencenr" werden als Ganzzahlen sortiert
alphabetische Sortierung. Führende Ganz- oder Kommazahlen werden dabei als Zahlenwerte verglichen. Als Dezimaltrenner
wird der Punkt erwartet.Die Texte
00100
0020b
20a
bekommen also die Reihenfolge
20a
0020b
00100
[Ab v3.4 R5130] Die Kriterien, wie Spalten sortiert werden sollen, können mit den folgenden Angaben außer Kraft gesetzt werden:
asc_int, desc_int Werte als Ganzzahlen vergleichen.
asc_float, desc_float Werte als Kommazahlen vergleichen. Als Dezimaltrenner sind sowohl Punkt als auch Komma erlaubt.
asc_string, desc_string Werte alphabetisch vergleichen. Groß- und Kleinschreibung werden unterscheiden.
asc_ustring, desc_ustring Werte alphabetisch vergleichen. Groß- und Kleinschreibung sind egal.
asc_datetime, desc_datetime Werte als Datum/Uhrzeit vergleichen
Das Beispiel zeigt einen einfachen Select-Befehl, der die Namen und SubIDs aller
Produktdaten ausgibt, deren SubID = 1002 ist.
select
name,
sub.id
node productdata.object
where id > 0 and sub.id = 1002;
Der Befehl entspricht ein seiner Syntax dem Befehl xmlget mit dem Unterschied, dass hinter jeder Ergebnisspalte ein
durch '=' getrennter neuer Wert steht. Als Werte sind nur direkte Zuweisungen erlaubt. Zuweisungen der Art id = id+1 sind nicht implementiert.
Änderungen müssen mit commit bestätigt werden.
Das Beispiel zeigt einen einfachen Update-Befehl beim Name und SubID aller Elemente
mit der SubID 1002 geändert werden.
update
name="Hallo Hallo",
sub.id=33333
node productdata.object
where id > 0 and sub.id = 1002;
Der Befehl entspricht ein seiner Syntax dem Befehl xmlget mit dem Unterschied, dass hinter jeder Ergebnisspalte ein
durch '=' getrennter neuer Wert steht. Von jedem gefundenen Element wird eine Kopie angelegt, und in die bestehende Struktur eingefügt.
Soll genau ein Datensatz eingefügt werden, muss die where-Bedingung so gestellt sein, dass genau ein Datensatz ausgewählt wird, also etwa
where id = 0.
Ist die Kopie eingefügt, werden die angegebenen Spalten mit den Werten des Inserts gefüllt.
Neue Elemente können nur in Dateien eingefügt werden, die mindestens ein Element der gewünschten Struktur enthalten.
Änderungen müssen mit commit bestätigt werden.
Das Beispiel macht von allen Produktdaten, die Unterprodukte der id 1002 enthalten,
eine Kopie, fügt die Kopie an die bestehenden Produktdaten an und ändert die Namen und UnterIDs der neuen Produktdaten.
insert
name="Hallo Hallo",
sub.id=33333
node productdata.object
where id > 0 and sub.id = 1002;
Der Befehl entspricht ein seiner Syntax dem Befehl xmlget mit dem Unterschied, dass keine Ergebnisspalten angegeben
werden..
Änderungen müssen mit commit bestätigt werden.
Lösche alle Produktdaten, die Unterprodukte mit der id 1002 enthalten.
delete
node productdata.object
where id > 0 and sub.id = 1002;
Mit commit werden alle Änderungen in die XML Datei zurückgeschrieben. Nach commit sind Änderungen nicht
mehr rückgängig zu machen.
Optimierungen können für definierte Zieldateien gemacht werden, in denen sie gelten sollen.
Für alle Pfadangaben in den Optimierungen gilt:
Bleibt die Angabe leer, gilt die Definition für alle Dateien.
Unvollständige Pfade werden relativ zum XML-Ordner aufgelöst.
ALIAS-Namen von Dateien am Pfadanfang sind erlaubt.
Pfade dürfen als reguläre Ausdrücke gegeben sein.
(Achtung: Reguläre Ausdrücke sind etwas anderes als die Wildcards, die in
Pfadangaben von Konsolenanweisungen verwendet werden können! abc*.xml wäre eine
falsche Angabe, richtig wäre in diesem Fall abc[^\.]*.xml.)
Durch das Anlegen eines Indexes kann die Bearbeitung von xmlqueries um das 20-fache beschleunigt werden. Die Definition eines
Indexes ist den folgenden Fällen sinnvoll:
Auf die XML-Datei werden mehrere xmlqueries angewendet.
Die XML-Datei enthält ein sortierbares Element. Das Element kann String- oder Zahlenwerte enthalten, aber wenn ein Element
einen String/eine Zahl enthält, müssen alle Elemente einen String/eine Zahl enthalten.
In den where-Teilen der xmlqueries muss eine Bedingung enthalten sein, die das indizierte Elemente auf Gleichheit prüft, in der
obersten Ebene der Bedingungen steht und nicht durch or mit einer weiteren Einschränkung versehen ist. Ist das Element
name einer Datei indiziert, kann der where etwa name = "ABC" enthalten.
In den drei folgenden Beispielen für where-Bedingungen kann auf namekein Index angewendet werden:
name like "ABC%" : Keine Prüfung auf Gleichheit
name = "ABC" or name = "DEF" : Verknüpfung von zwei Bedingungen
titel like "A%" or (name = "ABC" and untertitel = "DEF") : Auf name kann kein Index angewendet werden, weil
das Attribut nicht in erster Ebene der Bedingungen steht
Indexe werden in der Datei xindex.xml im XML-Datenordner definiert und haben folgendes Format:
<indicees>
<index>
<file>...</file>
<nodepath>...</nodepath>
<unique>no</unique> <!-- yes | no -->
<enabled>yes</enabled> <!-- yes | no -->
</index>
</indicees>
Mit file wird festgelegt in welchen Dateien der Index angewendet werden soll.
In nodepath wird der vollständige XML-Pfad des zu indizierenden Attributes angebenen.
Pfadtrenner ist der Punkt (.).
Das Attribut unique definiert, ob ein Index eindeutige Werte enthält (yes) oder nicht (no).
Bei eindeutigen Indexen können wir das erste gefundene Objekt verwenden. Bei nicht-eindeutigen Indexen werden alle
Elemente gleichen Inhaltes in die Auswahl aufgenommen.
Mit enabled kann der Index abgeschaltet werden. Erlaubt sind die Werte yes und no.
Die jeweiligen Definitionen sind optional. Hier das Grundgerüst der Datei:
<?xml version="1.0"?>
<entities>
</entities>
Texte können Formatierungsanweisungen enthalten die in HTML oder InDesign®-TaggedText angegeben sind, etwa <B>Mein Text</B>.
Der XML-Parser würde diesen Text als Unterknoten des aktuellen Knotens interpretieren und ihm den Inhalt Mein Text geben. Um solche Fehlinterpretationen
zu vermeiden, können vor dem Einlesen der Datei Inhalte ersetzt werden. Die Ersetzungen können auf einzelne Dateien beschränkt werden.
Achten Sie bei der Definition vorbereitender Ersetzungen darauf, dass keine gültigen XML-Tags der Datei ersetzt werden. Oder, noch besser, versuchen sie
bei der Definition der XML-DTD auf Elementnamen zu verzichten, die in HTML oder InDesign®-TaggedText gebräuchlich sind (wie etwa <H1>, <TABLE> oder <P>)
Ersetzen definierter Textteile durch andere, z.B. Ersetzen von HTML-typischen Zeilentrennern (<BR>) durch
InDesign®-Zeilentrenner. Die Ersetzungen werden direkt beim Einlesen der XML-Dateien gemacht.
Die Definition der Ersetzungen kann auf einzelne Dateien eingeschänkt werden. Als Dateipfade können die in der
Palette Einstellungen
definierten
Aliasnamen verwendet werden.
Die folgenden Schlüsselwörter werden im Ersetzen-String replace automatisch durch ihre aktuellen Werte ersetzt :
$PATH Pfad der aktuellen XML-Datei
$NAME Name der aktuellen XML-Datei
$LINE Aktuelle Zeile der XML-Datei
Das folgende Beispiel beschreibt die Definition, die nötig ist, um alle Auftreten von AAAA zu ersetzen.
Um in der mit MYFILE bezeichneten Datendatei den Namen der aktuell verwendeten XML-Datei zu erhalten, kann die folgende
Definition verwendet werden. Jedes AAAA in der Datendatei wird dann durch den aktuellen Dateinamen ersetzt.
Diese Ersetzungen werden erst dann gemacht, wenn der Text eines XML-Elementes in ein InDesign®-Dokument eingesetzt
wird. Sie gelten nur für genau festgelegte Platzhalter. Hintergrund dieser Ersetzungen ist, dass beispielsweise die HTML-Angabe
<B> in Abhängigkeit von der Zielstelle im InDesign®-Dokument verschiedene Ersetzungen benötigt. Die Definitionen
können deaktiviert werden.
Das folgende Beispiel beschreibt die nötigen Definitionen, um ein <B> im Platzhalter 1 in eine bestimmte Schriftdefinition
umzusetzen. Es werden zwei Definitionen benötigt, für Anfang- und Ende-Tag.
Beachten Sie, dass Sie zwar <b> als Wert angeben können, dieses öffnende Tag wird automatisch ersetzt. Aber das
schließende Tag (</b>) muss in XML-kompatibler Schreibweise angebenen werden. Beachten Sie weiterhin, dass
die Definition der Schriftart (hier <cFont:Verdana>) als öffendes Tag in dieser Schreibweise angegeben werden darf, aber nicht
<cFont:Verdana Bold>, denn Verdana Bold ist wegen des Leerzeichens kein gültiger XML-Elementname.
Sie sollten in den Definitionen der Datei xentities.xml auf die bequeme <>-Schreibweise verzichten und die
Klammern immer in der Schreibweise <> verwenden.
Der Datentyp von Elementen wird für Vergleiche und Sortierungen
benötigt. Im Normalfall werden alle Elemente, die (case insensitive) mit id oder sequencenr beginnen,
oder auf diese Begriffe enden, als Zahlen betrachtet, alle anderen Attribute sind Strings. Mit typedef Elementen in der Entity-Datei
können diese Festlegungen geändert werden. Als Dateipfade können die
in der Palette Einstellungen definierten
Aliasnamen verwendet werden. Als mögliche Werte für type sind folgende Angaben erlaubt:
Ganzzahlen : int, integer
Kommazahlen : float, real, double,
Text : string, text
Bezeichner, die auf ID enden, werden automatisch als Zahlen betrachtet. Im folgenden Beispiel wird festgelegt, dass
ProductID der Datei products.xml als Zeichenkette verarbeitet werden soll.
Beim Einlesen der XML-Dateien können sogenannte Dummy-Knoten erzeugt werden. Auf die
Werte dieser Knoten kann in der üblichen Weise zugegriffen werden, als wären sie in der XML-Datei
definiert worden.
Sie geben die Datei an, für die
eine Definition gelten soll und den Elternknoten des Dummies. Als Dateipfade können die
in der Palette Einstellungen
definierten
Aliasnamen verwendet werden. Als Elternknoten dürfen keine TextElemente verwendet werden.
Der Dummy wird mit einem Namen und einem Wert definiert. Als Werte sind die folgenden Angaben zulässig :
lineno Zeilennummer in der XML-Datei
nodecounter Aktueller Knotenzähler
dummycounter Aktueller Knotenzähler der Dummies
tick Uhrzeit als Zahl (kann negativ sein)
now Uhrzeit im Format dd.mm.yyyy hh:mm:ss
Allen anderen Angaben werden wie folgt ausgewertet :
Beschreibung
Beispiel
@beliebiger Text
Verwende den hinter dem @ stehenden Text.
@Fehlendes Attribut
Fehlendes Attribut
[#]attributeName {attributeName}
Verwende den Hash-Code des Inhalt des Attributes attributeName.
Das Attribut muss neben dem fehlenden Attribut (also im selben XML-Element wie in <attr> angegeben) liegen.
[Ab v3.3 R2712, 16. Nov. 2011] Mit vorangestelltem # wird statt des Hash-Codes der direkte Inhalt des Attributes zurückgegeben.
[Ab v3.3 R2712, 16. Nov. 2011] Sie können eine beliebig lange Liste von Attributnamen angeben. Die Attributnamen müssen dabei jeweils mit einem Leerzeichen
getrennt werden. Diese Liste wird solange durchsucht, bis ein existierendes Attribut gefunden wird, dessen Inhalt dann verwendet wird.
#author image price
Verwende den Author des Produktes. Fehlt diese Angabe, verwende den Bildpfad. Fehlt auch der, dann nimm den Preis.
Vor dem Einfügen der Knoten wird geprüft, ob ein Knoten des gewünschten Namens bereits existiert. In diesem
Fall wird kein Dummy angelegt. Dummy-Definitionen können darüber hinaus festlegen, ob sie bei commit in
die XML-Datei geschrieben werden sollen oder nicht.
Für einen Elternknoten können beliebig viele Dummies erzeugt werden.
Dummyknoten des Typs lineno eignen sich gut dafür, die Sortierreihenfolge der Datensätze gemäß
ihrer Reihenfolge in der XML-Datei sicherzustellen.
Das folgende Beispiel legt beim Einlesen der Datei products.xml im Element products.product.grid
die zwei Unterlemente myid und myid2 an. Das erste Element enthält die aktuellen Zeilennummer der
XML-Datei, das zweite den Zähler der Dummy-Knoten. Der erste Knoten wird bei commit in die Datei products.xml
übernommen. Die dritte Definition legt für jeden Produktknoten ein Element an, dessen Inhalt den Namen des Produktes möglichst
eindeutig auf eine positive Zahl abbildet.
Platzhalterobjekte sind stets mit einer sogenannten classID(integer) versehen.
Diese Nummer steuert unter anderem, ob in einer Palette die Menübefehle zum Laden und Sichern von Platzhaltern aktiviert sind. So ist z.B. der
Befehl Aktualisiere Produkte der Textauswahl nur dann aktiv, wenn auch tatsächlich ein Platzhalter mit einem Produkt im Dokument ausgewählt ist.
Mitunter kommt es vor, dass Platzhalter mit eigenen Klassen-IDs versehen werden. In diesem Fall ist es wünschenswert, auch diese Platzhalter über eine
definierte Palette bearbeiten zu können. Mit <classmap> können die Zuordnungen gemacht werden. Die Definitionen werden in
den folgenden Fällen ausgewertet :
Platzhalter laden
Platzhalter sichern
Platzhalter überprüfen
Aufbau wiederholender Elemente
Im folgenden Beispiel wird festgelegt, dass alle Platzhalter der Klassen 4 und 400 auch über die
Palette Produktrecherche (classID 3) bearbeitet werden können.
Zusätzlich zur eigentlichen Datenabfrage muss die Anweisung natürlich wissen, in welcher XML-Datei sie arbeiten soll. Den Anweisungen wird daher (in Anführungszeichen)
die Datei, auf der gearbeitet werden soll, vorangestellt.
Das Panelstatement ermittelt die IDs und Namen aller Domains. Die Daten sind in der XML-Datei domains.xml enthalten.
"domain.xml"
xmlget id, name node domains.domain where id < 0
Pfade dürfen mit den üblichen Alias-Präfixen$HOME, $DESKTOP,
$DOCUMENTS, $PLUGINS, ... beginnen.
Unvollständige Dateipfade werden relativ zum aktuellen Datenordner aufgelöst.
Mit Hilfe der Palette Einstellungen können
weitere Aliasse definiert werden.
Aliasse werden in der Datei datafiles.xml definiert. Unvollständige Pfade in den Definitionen werden
relativ zum aktuellen Datenordner aufgelöst. Um die aktuellen Zuordnungen zu ermitteln oder zu ändern können die Funktionen
file::enable_datafile, file::setdatafile und file::getdatafile verwendet werden.
Hier ein Beispiel einer gültigen Datei. Der Alias
MYFILE wird viermal definiert. Ein Eintrag ist aktiviert. Die ersten beiden Definitionen zeigen auf zwei
Dateien im aktuellen XML-Datenordner, die letzte auf eine Datei des Desktops.
[Ab v4.1.5 R24666]
Plugnis und comet_pdf unterstützen XPATH 1.0 für das Lesen von Daten aus XML-Dateien.
This software is based on pugixml library (http://pugixml.org). pugixml is Copyright (C) 2006-2018 Arseny Kapoulkine.
Die Integration von XPATH in die priint:comet Software erfolgte in der Hoffung,
Ihnen die Arbeit zu erleichtern. Bitte haben Sie Verständnis dafür, dass die Implementierung
möglicherweise nicht alle Features und Funktionen von XPATH enthält.
Für die Lösung extrem spezieller Abfragen verwenden Sie bitte die Funkionen des Modules xmlnode.
Um Datensätze mit mehreren Ergebnisspalten zu erhalten, können Ergebnisse mit | verbunden werden.
Jeder Teilausdruck ergibt eine eigene Ergebnisspalte. Die Ausgabe erfolgt in der Reihenfolge
wie in der Anweisung. Unvollständige Datensätze werden übersprungen.
Bitte beachten Sie : Alle Elemente einer Ergebniszeile müssen exakt den gleichen Elternknoten in der XML-Daten haben!
Ergebnisse von Elementen verschiedener Eltern müssen in mehreren Abfragen ermittelt werden. (Und wenn Sie die Ergebnisse dieser
verschiedenen Listen zu Ergebnis-Tupeln zusammenstellen wollen, werden Sie auch feststellen, warum man
diese Einschränkung machen muß, wenn man gleichzeitig unvollständige und unsortierte Elemente erlauben will. )
... dann erhalten Sie folgende Ergebnisse.
Der erste Datensatz wird dabei in anderer Reihenfolge als in der XML ausgegeben, weil die Reihenfolge der Anweisung beachtet wird.
Der zweite Datensatz wird übersprungen, weil er unvollständig ist.
1, A
3, C
Die Definition von XPATH sieht offenbar keine 'Spalten' mit festen Werten vor - die mit | verknüpften Teile einer Anweisung müssen
sämtlich Elemente der XML-Struktur sein. Wir haben in unserer Implementierung deshalb eine kleine Erweiterung eingefügt: Mit der
Angabe
static-value "string"
können Sie Spalten mit festen Werten in die Ergebniszeilen einfügen. Enthält der statische String eine Zahl,
kann (muß aber nicht) dieser Wert auch als Zahl abgeholt werden. Sie können beliebig viele statische
Spalten definieren, aber die Anweisung muß mindestens eine variable Spalte enthalten.
Die Ergenisse des obigen Beispiels sollen eine zusätzliche zweite Spalte mit dem festen Wert 2024 erhalten:
/a/b/c | static-value "2024" | /a/b/d
Damit erhalten Sie die folgenden Ergebnisse:
1, 2024, A
3, 2024, C
static XMLTree xmlquery::open( char* path, int autoCommit = 0, int useTreeBuffer = 1, int autoUpload = 0, int isLocal = 0, int parseImmediate = 0)
Öffnen eines dateibasierten XML-Baumes.
Der erzeugte Baum muss mit close wieder geschlossen werden!.
Vollständiger Pfad einer existierenden XML-Datei. Der
Pfad darf mit einem definierten Datei-Alias beginnen.
In XML-Offline-, SOAP- und AEM®-Verbindungen können hier auch XML-Daten der Konfiguration
wie panelstatements.xml und actions.xml
gelesen werden.
autoCommit
int
0
Sollen Änderungen beim Schließen des XMLTrees automatisch gesichert werden?
Beachten Sie bitte, dass Konfigurationsdaten auch an anderen Stellen der
Plugins verwendet werden und Änderungen an diesen Daten zu Programmfehlern führen können!
XML-Daten, die aus einer SOAP- oder AEM®-Verbindung gelesen wurden, haben
keine lokale Datei, autoCommit auf diesen Bäumen
hat daher keine Auswirkung. Verwenden Sie dafür den Parameter autoUpload.
useTreeBuffer
int
1
Das Lesen von XML-Dateien kann zeitaufwändig sein. Gelesene
Dateien können deshalb gepuffert werden. Gepufferte XML-Daten werden
bei Trennen der Verbindung gelöscht.
autoUpload
int
0
Sende die XML beim Schließen des Baumes an die Ursprungsquelle der Datenverbindung.
Der Parameter hat nur Wirkung bei XMLs, die aus einer SOAP- oder AEM®-Verbindung geladen wurden!
isLocal
int
0
In SOAP- und AEM®-Verbindungen werden XML-Dateien automatisch aus der Datenquelle geladen.
Zum Laden lokaler Dateien setzen Sie den Parameter auf 1. Der Dateipfad path muss in diesem
Fall ein vollständiger Pfad sein!
parseImmediate
int
0
Sofort einlesen? Normalerwesie wird der Baum erst bei Bedarf eingelesen, da beim Öffnen noch nicht klar ist,
ob xmlquery oder XPATH als Abfragesprache verwendet werden soll und beide Methoden unterschiedliche interne Repräsentationen des Baums benötigen.
Lade den Inhalt eines Platzhalters aus der aktuellen Datendatei $DATAFILE. Wird
das gewünschte Produkt nicht gefunden, wird ein bedingter Text mit einer Fehlerbeschreibung
ins Dokument eingefügt.
#include "internal/types.h"
#include "internal/text.h"
int main ()
{
XMLTree tree = 0;
char name [5000];
int found = 0; strcpy (name, "");
tree = xmlquery::open("$DATAFILE"); xmlquery::send(tree, "select name node posters.poster where ID = ?");
xmlquery::input(tree, kInt, gRecordID);
xmlquery::output(tree, kString, name); xmlquery::exec(tree);
while (xmlquery::fetch (tree)) found = 1; xmlquery::close(tree);
if (!found)
{
strcpy (name, "%!TT<DefineCondition:ERRORCODE=<ConditionColor:1,0,0>");
strcat (name, "<ConditionIndicatorMethod:Highlight><ConditionVisibility:0>>");
strcat (name, "<cConditionalText:ERRORCODE>Product not found!<cConditionalText:>");
} textmodel::replace (name);
return 0;
}
Schreibe den Inhalt eines Platzhalters HTML-formatiert in eine XML-Datei zurück.
Version 1.1.7, Januar 2005 autoCommit und useTreeBuffer seit Version 1.1.9, 1. April 2004 autoUpload seit v4.1 R22423, 30. Apr 2018 isLocal seit v4.1.7 R26842, 22. Apr 2020 parseImmediate seit v4.2 R31950, 30. Nov 2022
static int xmlquery::close(XMLTree tree, int doFlush = 0)
Schließen eines XML-Baumes. Der Befehl muss für jeden mit xmlquery::open oder xmlquery::parse
erzeugten XML Baum gemacht werden. Wurde die XML-Datei mit autocommit geöffnet, werden Änderungen an der Datei zuvor
geschrieben.
Alle Comet-internen Daten der XML-Datei entfernen?
0 : nein
1 : ja. Die Datei wird beim nächsten öffnen neu gelesen.
Die Anweisung hat nur Wirkung für XMLTrees, die mit gesetztem useTreeBuffer
geöffnet wurden. Es darf kein XMLTree der gleichen Datenquelle mehr geöffnet sein.
Comet-Standard XMLTrees wie actions.xml, panelstatements. xml, ...
dürfen nicht "ge-flusht" werden.
Seit
Version 1.1.7, Januar 2005 doFlush seit v3.2.1 R2345, 9. März 2011
static int xmlquery::send(XMLTree tree, char* cmd)
Senden einer XML-Anweisung zum Ermitteln von Werten eines XML Baumes. Nachfolgende
Aufrufe von xmlquery::send, xmlquery::isend und xmlquery::fsend erweitern die XML-Anweisung.
Die Anweisung wird durch xmlquery::exec ausgeführt und danach auf "" zurückgesetzt.
Die Anweisung kann in xmlquery oder XPATH geschrieben werden.
static int xmlquery::send_cdata_begin(XMLTree tree)
Beginnen eines CDATA-Blockes in der xml-Anweisung. Die Anweisung ist identisch dem Aufruf xmlquery::send ("<![CDATA["),
aber wer kann sich das schon merken? Der Aufruf kann auch für Elemente verwendet werden, die in der XML-Datei bereits mit
CDATA definiert sind. Ein geöffneter CDATA-Block muss mit send_cdata_end wieder geschlossen werden.
Innerhalb von CDATA-Blöcken darf der String ![[[CDATA[ nicht verwendet werden.
Name
Typ
Default
Beschreibung
tree
XMLTree
-
Mit xmlqyery::open erzeugte Repräsentation einer XML-Datei
Beenden eines CDATA-Blockes in der xml-Anweisung. Die Anweisung ist identisch dem Aufruf xmlquery::send ("]]>"),
aber wer kann sich das schon merken? Der Aufruf kann auch für Elemente verwendet werden, die in der XML-Datei bereits mit
CDATA definiert sind.
Name
Typ
Default
Beschreibung
tree
XMLTree
-
Mit xmlqyery::open erzeugte Repräsentation einer XML-Datei
Senden einer Ganzzahl an eine XML-Anweisung. Der Befehl wirkt wie xmlquery::send mit dem
Unterschied, dass die Zahl als Text an die Anweisung angefügt wird.
Name
Typ
Default
Beschreibung
tree
XMLTree
-
Mit xmlquery::open erzeugte Repräsentation einer XML Datei.
i
int
-
Ganzzahl, die an die XML-Anweisung angefügt werden soll.
Senden einer Kommazahl an eine XML-Anweisung. Der Befehl wirkt wie xmlquery::send mit dem
Unterschied, dass die Kommaahl als Text an die Anweisung angefügt wird. Die Präzision der Zahlen ist auf 6 Nachkommastellen begrenzt.
Name
Typ
Default
Beschreibung
tree
XMLTree
-
Mit xmlquery::open erzeugte Repräsentation einer XML Datei.
f
float
-
Kommazahl, die an die XML-Anweisung angefügt werden soll.
Typ des Wertes. Der Datentyp, der zu einem
Variablenplatzhalter gehört, ergibt sich aus der jeweiligen Anweisung.
Es ist Aufgabe des Skriptprogrammierers, die richtigen
Wertetypen zu binden. kInt kFloatDie Präzision der Zahlen ist auf 6 Nachkommastellen begrenzt. kString kCDATA
value
depends
-
Dieser Wert wird an Stelle des zugehörigen Variablenplatzhalters (?)
an die Datenbank gesendet. Der Typ des Parameters hängt vom Wert type ab.
Passen type und Datentyp von value nicht zusammen, kann das zum Absturz von InDesign® oder zu
unerwarteten Daten auf der Datenbank führen!
kInt: int, short, long (z.B -1, 0, 1, 2) kFloat : float, real (z.B. -1.0, 1.0, 1.1), Die Präzision der zahle ist auf 6 Nachkommastellen begrenzt. kString : String oder char* (z.B. "", "paul") kCDATA : String oder char* (z.B. "", "paul")
static int xmlquery::output( XMLTree tree, int type, int* pointer)
xmlquery_output Binden von Variablen an die Ergebnisspalten der XML-Anweisung. Dabei wird das Ergebnis
der ersten Ergebnisspalte an die erste gebundene Variable übergeben usw.. Da XML-Dateien
keine Typinformationen enthalten ist der Typ der Ergebnisspalte beliebig. Es muss lediglich sichergestellt sein, dass
der Spaltenwert in den Zieltyp umgerechnet werden kann. Enthält die XML-Datei z.B.
Kommazahlen, kann die entsprechende Spalte sowohl an Strings, Ganzzahlen oder Kommazahlen
gebunden werden. Die Anweisung benötigt den Include #include "internal/types.h"
Das Binden von Variablen an die Ergebnisspalten kann vor oder nach xmlquery::exec erfolgen. Findet
xmlquery::fetch keine weiteren Ergebnisse mehr, werden die Bindungen zurückgesetzt.
Name
Typ
Default
Beschreibung
Return
int
1: Okay
0: Fehler
tree
XMLTree
-
Mit xmlquery::open erzeugte Repräsentation einer XML Datei.
type
int
-
Datentyp der folgenden Variable wie folgt : kInt : Zeiger auf eine Ganzzahl kFloat : Zeiger auf eine Kommazahl kString : char*-Variable. Wenn der Typ char* ist, muss die Variable
über genügend reservierten Speicher verfügen.
Größe des reservierten Speichers für Stringergebnisse. Wenn pointer vom Typ String ist, wird diese Angabe ignoriert Zu wenig Speicherplatz für
die Stringergebnisse sind eine häufige Usache für schwer nachvollziehbare Skriptabstürze.
Mit der Angabe der maximalen Länge des Strings wird sichergestellt, dass nur in reservierte
Speicherbereiche geschrieben wird. Ergebnisse werden bei Bedarf auf die angegebene Länge gekürzt.
Die Speicherlänge beinhaltet ein Byte für die stringabschließende 0.
0 : Fehlt die Angabe oder ist 0, werden die Rückgabewerte ohne Prüfung ihrer Länge vollständig in die Zielvariable eingesetzt.
static int xmlquery::exec(XMLTree tree, int showErrors = 0)
Ausführen der XML-Anweisungen. Der Aufruf setzt automatisch die XML-Anweisung des Queries zurück.
Name
Typ
Default
Beschreibung
Return
int
1 Okay
0 Fehler
Mit den Funktionen xmlquery::error und xmlquery::errnum kann eine Beschreibung des Fehlers geholt werden.
tree
XMLTree
-
Mit xmlquery::open erzeugte Repräsentation einer XML Datei.
showErrors
int
1
Sollen die Bearbeitungsfehler automatisch angezeigt werden?
0 - Fehler nicht in einem Fehlerdialog zeigen. Das Skript macht die Fehlerbehandlung selbst.
sonst - Standardfehler-Dialog zeigen
Eine Liste der möglichen Fehler und ihrer Beschreibung finden Sie hier. Beachten Sie bitte,
dass Warnungen z.B. über fehlende Attribute oder Elemente NICHT als Fehler sondern lediglich als
Warnungen angesehen werden und daher durch das Setzen von showErrors nicht gesehen werden. Verwenden
Sie für diesen Fall die Funktion xmlquery::get_exec_infos.
Seit
Version 1.1.7, Januar 2005 showErrors seit Version 1.2.2 (18. Oktober 2005)
Abholen der nächsten Ergebnisspalte der XML-Anweisung. Vor dem Abholen der Ergebnisse müssen
die Spalten an Variablen gebunden werden (siehe xmlquery::output). Findet
xmlquery::fetch keine weiteren Ergebnisse mehr, werden die Bindungen zurückgesetzt.
Name
Typ
Default
Beschreibung
Return
int
1 Ergebnis gefunden
0 keine weiteren Ergebnisse. Mit xmlquery::output gesetzte Variablenbindungen
werden zurückgesetzt.
tree
XMLTree
-
Mit xmlquery::open erzeugte Repräsentation einer XML Datei.
static int xmlquery::error(XMLTree tree, char* mess)
Fehlerbeschreibung der letzten XML-Anweisungsausführung. Eine Liste der möglichen Fehler finden Sie hier.
Beachten Sie bitte, dass Warnungen über fehlende Attribute oder Elemente NICHT als Fehler sondern lediglich als
Warnungen angesehen werden. Um vor fehlenden Attributen oder Elmenten zu warnen, verwenden sie die Funktion xmlquery::get_exec_infos.
Beachten Sie bitte, dass Warnungen über fehlende Attribute oder Elemente NICHT als Fehler sondern lediglich als
Warnungen angesehen werden. Um vor fehlenden Attributen oder Elmenten zu warnen, verwenden sie die Funktion xmlquery::get_exec_infos.
Die folgenden Tabelle beschreiben die Fehlercodes und Warnungen, die vn XML-Queries erzeugt werden können.
Fehlercodes von XML-Queries
Nr.
Beschreibung
0
Keine Fehler
-43
Datei nicht gefunden oder fehlerhaft.
1
Index must not point to the root Element.
2
xmlset : Error while changing values.
3
xmlinsert : Error while setting values.
4
Empty xmlget command.
5
Keyword xmlget, xmlset, xmlinsert or xmldelete missing.
6
Unexpected end of xmlget.
7
There should never be a where without a node.
8
Missing value in xmlset/xmlinsert, must be of type int, real or string.
9
Missing '|'.
10
There must be a where before the next node.
11
There should never be a where without a node.
12
Orderby is the last key word.
15
Orderby failed, column must be in the result xmlcolumns.
16
xmlcommit : Cannot write empty xml tree.
17
xmlcommit : Writing file failed.
Warnungen von XML-Queries
Fehlende Elemente oder Attribute führen zu Warnungen bei der Ausführung von Anweisungen. Zum Ermitteln möglicher Warnungen
einer XML-Anweisungen verwenden Sie die Funktion xmlquery::get_exec_infos.
Nr.
Beschreibung
0
Keine Warnungen und Fehler
1290
Node nodeName used in columns not found.
1293
Error on traversing nodes while creating index.
1299
Node nodeName used in where not found.
Name
Typ
Default
Beschreibung
Return
int
Fehlercode der letzten XML-Anweisungsausführung.
tree
XMLTree
-
Mit xmlquery::open erzeugte Repräsentation einer XML Datei.
Ermittle den aktuellen Programmpfad zu den iQuest Comet XML-Daten. Dieser Ordner wird global in
InDesign® eingestellt und enthält unter anderem die Datei placeholder.xml und den Ordner
actions, mit den die Platzhalter und ihre Aktionen definiert werden.
static XMLTree xmlquery::process( char* destinationPath, char* definition, long serviceId = -1, long sourceId = -1, int force = 0)
Generieren einer XML-Datei (und / oder internen Repräsentation) aus der angegebenen Service-Definition
(ggf. unter Verwendung eines bestimmten Service / einer bestimmten Datenquelle)
Verarbeitung erzwingen. Normalerweise wird vor Neu-Einlesen geprüft, ob
unter dem angegebenen XML-Zielpfad bereits geparste Daten noch aktuell sind bzw.
aus der XML-Zieldatei gelesen werden kann.
Serialisieren eines XML-Baums. Das Ergebnis wird in buffer kopiert.
Wenn buffer vom Typ char* ist, muss vorher ein ausreichend großer Speicher allokiert werden.
Auswahlkriterium für UnterElemente der Einstiegsebene oder "" für alle UnterElemente.
Das Auswahlkriterium wird ausschließlich auf direkte UnterElemente oder Attribute der Einstiegsebene
angewendet und muß folgende Syntax haben:
name operator value
Hat das zu exportierende Element kein Unterelement oder Attribut des gegebenen Namens wird
das Kriterium ignoriert und das Element exportiert.
Operator
Beschreibung
Beispiel
= == < <= > >= != <>
Ganz- und Komma-Zahlenvergleich
Nur Unterlemente mit id >= 1000 exportieren.
id >= 1000
? !
Textvergleich. Der Suchtext muß in Anführungszeichen gegeben werden.
Mit ? wird case-insensitive verglichen,
mit ! werden Groß- und Kleinschreibung unterschieden.
Mit Leerstring ('') als Suchtext wird das Kriterium ignoriert.
An Anfang und Ende des Suchstrings sind % als Wildcards erlaubt.
Mit \% wird der Wildcard ignoriert.
Nur Unterlemente exportieren, deren Namen mit "Artikel " beginnen.
name ? 'Artikel %'
Schreibe alle Cometgruppen des MetaDaten-Exports groups.xml, deren ID 89 enthält, in ein JSON.
Löschen der Comet-internen XML-Daten einer Datei.
Dadurch erzwingen Sie, dass die Datei beim nächsten Öffnen neu gelesen werden muss.
Die Anweisung hat nur Wirkung für XMLTrees, die mit gesetztem useTreeBuffer
geöffnet wurden. Es darf kein XMLTree der gleichen Datenquelle mehr geöffnet sein.
Comet-Standard XMLTrees wie actions.xml, panelstatements. xml, ...
dürfen nicht "ge-flusht" werden.
comet.xmltree.open