Unterstützung von generischen Platzhaltern und Tabellenaufbau.

In den Aktionen von Platzhaltern und Tabellenaufbau können Funktionsvariablen und deren mögliche Werte beschrieben werden. Die Werte selbst werden erst festgelegt, wenn der Platzhalter (die Tabelle) in einem InDesign®-Dokument verwendet wird: Bei Auswahl im Dokument, werden Funktionsvariablen und deren mögliche Werte in der Palette Platzhalterwerte (Tabellenaufbau) gezeigt und Sie entscheiden erst hier, welcher Wert verwendet werden soll.

In einer Tabelle werden Titel, Farben und Preise von Artikeln verwaltet. Um diese Werte in Platzhaltern verwenden zu können, waren bisher drei fast identische Aktionen nötig, die sich jeweils nur im Namen des Artikel-Attributes (Titel, Farbe, Preis) unterscheiden. Mit Funktionsvariablen schreiben Sie nur eine Aktion und teilen der Außenwelt lediglich mit, dass die Aktion Funktionsvariablen hat und welche Werte dafür möglich sind. Der tatsächlich verwendete Wert wird dann individuell im InDesign®-Dokument festgelegt wenn Sie dort einen Platzhalter mit dieser Aktion verwenden.

Im Screenshot wird für gKeyName noch Ihre Entscheidung erwartet : Titel, Farbe oder Preis?

Die Definitionen der Funktionsvariablen werden ausschließlich von den Paletten Platzhalterwerte und Tabellenaufbau verwendet, um dort die Variablen und deren mögliche Werte zu zeigen. Einstellungen an den Variablen werden direkt im Platzhalter (in der Tabelle) im Dokument hinterlegt. Beim Ausführen der Aktionen (Laden, Tabellenaufbau, ...) werden dann die so die hinterlegten Werte verwendet. Die Beschreibungen der Funktionsvariablen werden zu diesem Zeitpunkt nicht mehr benötigt und haben keinerlei Einfluß auf die Ausführung der Aktion.

Comet Versionen vor 4.1, die Funktionsvariablen noch nicht unterstützen, können Aktionen mit Funktionsvariablen nicht verwenden und werden die Syntax als fehlerhaft erkennen.

Achtung :  Sollen nur bestimmte Platzhalter eines Dokumentes bearbeitet werden (Auge der Platzhalter-Palette), werden die Platzhalter unabhängig von den individuellen Werten der Funktionsvariablen bearbeitet: Wird z.B. über eine Funktionsvariable festgelegt, ob ein Platzhalter den Namen oder den Preis eines Produktes laden soll, werden beim Aktualisieren dieser Platzhalter alle Name und alle Preise aktualisiert. Wollen Sie die Name und Preis unabhängig von einander aktualisieren, verwenden Sie wie bisher zwei unterschiedliche Platzhalter, die aber alle die gleiche Laden-Aktion haben.

Derzeit lassen sich Funktionsvariablen an folgenden Stellen verwenden:

• In der Palette 'Tabellenaufbau' für die Aktionen:
  • Zeile Kopieren, Einfügen
  • Zeile Kopieren, Auslassen
  • Spalte Kopieren, Einfügen
  • Spalte Kopieren, Auslassen
  • Berechnen der IDs der Zelle
• In der Palette 'Platzhalterwerte' für die Aktionen:
  • Laden
  • Schreiben
  • Sync
  • Aufbau (Bei wiederholenden Elementen)

Die Syntax zur Definition von Funktionsvariablen ist für cScript und direkte Anweisungen (xmlquery, SQL) die selbe:

#pragma var "name" "defaultValue" {"alternative_value"}

"#pragma var" ist die einleitende Direktive, die zwingend notwendig ist. Danach folgen der Defaultwert und beliebig viele optionale Werte.

Jede Variablendefinition muss immer am Anfang eines Skriptes/Statements auf einer eigenen Zeile stehen.
Zeilenumbrüche in den Definitionen sind nicht erlaubt!
Reservierte Symbole wie gFrame, gDocument oder documentID dürfen nicht überschreiben werden.

Der "name" ist ein frei wählbarer Begriff, der entsprechend den Syntax-Regeln der folgenden Anweisung(en) gebildet sein muß:

• In cScripten muß ein gültiger cScript-Bezeichner verwendet werden.
• In direkten Anweisungen muß der Name ein syntaktisch richtiger XML-Bezeichner sein.

Reservierte Symbole dürfen nicht als Namen verwendet werden.

• Reservierte Symbole in cScript-Skripten sind alle cScript-Schlüsselwörter, alle verwendeten Datentypen, alle verwendeten Funktionsnamen und alle definierten globalen Variablen. Und natürlich dürfen auch die weiter unten definierten Bezeichner aus dynamischen Definitionen nicht verwendet werden.
• Reservierte Symbole in direkten Anweisungen sind alle definierten Tag-Namen und alle Pubserver-spezifischen Tags.

Dem Namen folgt eine Liste von möglichen Werten jeweils Anführungszeichen und getrennt durch Leerzeichen. Der erste Wert dieser Liste ist der Standardwert. Dieser wird verwendet, wenn der Platzhalter/die Tabellenzelle keinen Wert für diese Variable definiert hat. Anführungszeichen innerhalb des Wertes müssen mit \ escaped werden.

Beispiel: Variablenname: "gLanguage", Mögliche Werte:"de", "en" und "fr".

#pragma var "gLanguage" "de" "en" "fr"

Beispiel: Variablenname: "gGreeting", Mögliche Werte:"Hallo", "Hallo du" und "Hallo Rest".

#pragma var "gGreeting" "Hallo" "Hallo du" "Hallo Rest"

Beispiel: Variablenname: "gSize", Mögliche Werte:"5 cm", "5"" (5 Zoll).

#pragma var "gSize" "5 cm" "5\""

Sie können auch eine ActionID hinterlegen, in der die Liste der möglichen Werte gefüllt wird. Die Syntax dazu sieht folgendermaßen aus:

#pragma var "variableName" "##actionID"

Wobei "variableName" der Name der Variable ist und "actionID" eine Zahl, welches die ID der Aktion ist, die die Liste füllt.

Diese Aktionen müssen mit den ClassIDs 55 (für Platzhalter) bzw. 56 (für Tabellenzellen) definiert werden.

Diese Aktionen müssen cScripte sein!

Innerhalb dieser Aktion sind folgende globale Variablen verfügbar:

Beispiel 1:

#pragma var "gLanguage" "##333"

In Aktion 333:

int main()
{
	stringlist::insert(gAvailableValues, "de", -1);
	stringlist::insert(gAvailableValues, "en", -1);
	stringlist::insert(gAvailableValues, "fr", -1);

	return 0;
}

Sie können das Laden der Werte über eine Aktion mit festen Werten kombinieren. Die Werte aus der Aktion werden dann in der Liste an der entsprechenden Stelle eingefügt.

Beispiel 2:

#pragma var "gLanguage" "de" "en" "##333"

Wenn sie eine doppelte Raute am Anfang ihres Wertes verwenden möchten, muss diese durch einen backslash escaped werden.

Beispiel 3:

#pragma var "gLanguage" "de" "en" "\##frFR"

Die Actions, die die Liste der möglichen Werte füllen, lassen sich verschachteln, so dass eine Aktion wiederum andere Aktionen aufruft, die ebenso die Listen füllen. Wenn in einer Action, die die gAvailableValues Liste füllt, als Name für einen Wert die Syntax mit der doppelten Raute verwendet wird, wird dies als weiterer Aufruf einer dynamischen Definition gewertet.

Beispiel 1:

In einer Laden-Aktion eines Platzhalters:

#pragma var "gLanguage" "##111"

int main()
{
	// Da es hier nur um die möglichen Werte einer 
	// Funktionsvariable geht, macht das Script nichts
	
	return 0;
}

Dann in Aktion 111:

int main()
{
	stringlist::insert(gAvailableValues, "de", -1);
	stringlist::insert(gAvailableValues, "en", -1);
	stringlist::insert(gAvailableValues, "##222", -1);
	stringlist::insert(gAvailableValues, "fr", -1);
		
	return 0;
}

Dann in Aktion 222:

int main()
{
	stringlist::insert(gAvailableValues, "jp", -1);
	stringlist::insert(gAvailableValues, "dk", -1);
		
	return 0;
}

Achten sie darauf, keine Endlosschleifen zu erzeugen, das bringt InDesign® dann nämlich schnell zum Absturz.

Funktionsvariablen müssen nicht zwangsweise wie oben beschrieben in ihren Scripten oder Statements definiert werden. Es ist möglich, eine Action ID anzugeben für die ein cScript hinterlegt ist, welches die Funktionsvariablen definiert.

Die Syntax dazu sieht folgendermaßen aus:

#pragma var "##123"

Wobei die 123 in diesem Beispiel die Action ID der Action ist, die die dynamische Definition durchführt. Alle weiteren Strings hinter der 123 werden ignoriert!

Das Statement dieser Action muss ein cScript sein und folgende ClassID haben: Bei Platzhaltern: 57; Bei Tabellenzellen: 58!

Diese Action muss eine Liste vom typ idtypelist mit dem Namen gFuncVars mit den Namen der Funktionsvariablen und deren möglichen Werten füllen.

Die Werte müssen dabei wie folgt aussehen:

(1, 0, 0, "Variablen1Name")
(1, 1, 0, "Variable1Wert1")
(1, 2, 0, "Variable1Wert2")
(2, 0, 0, "Variablen2Name")
(2, 1, 0, "Variable2Wert2")
usw...

Der erste Wert der ID ist dabei also eindeutig pro Variable, der zweite Wert der ID ist entweder 0 (Variablenname) oder der index des möglichen Wertes der Variable. Die Reihenfolge der Namen und Werte spielt dabei keine Rolle - wobei mögliche Variablenwerte ohne zugehörigen Variablennamen verworfen werden.

Beispiel 1:

In einer Laden-Aktion eines Platzhalters:

#pragma var "##333"

int main()
{
	// Da es hier nur um die möglichen Werte einer 
	// Funktionsvariable geht, macht das Script nichts

 	return 0;
}

Dann in Action 333:

int main()
{
	//definition Variable "gFruits"
	idtypelist::insert(gFuncVars, -1, 1, 0, 0, "gFruits//Früchte");
	idtypelist::insert(gFuncVars, -1, 1, 1, 0, "apples//Äpfel");
	idtypelist::insert(gFuncVars, -1, 1, 2, 0, "pears//Birnen");
	idtypelist::insert(gFuncVars, -1, 1, 3, 0, "bananas//Bananen");
	
	return 0;
}

Innerhalb dieser Aktion sind folgende globale Variablen verfügbar:

Dynamische Definitionen lassen sich ebenso wie Aktionen für mögliche Werte miteinander verschachteln. Wenn in einer Action, die die gFuncVars Liste füllt, als Name für eine Variable die Syntax mit der doppelten Raute verwendet wird, wird dies als weiterer Aufruf einer dynamischen Definition gewertet. Die Funktionsvariablen werden entsprechend ihrer Definitionsreihenfolge in das Dropdownmenu im Interface eingefügt.

Beispiel 1:

In einer Laden-Aktion eines Platzhalters:

#pragma var "##333"

int main()

{
	// Da es hier nur um die möglichen Werte einer
	// Funktionsvariable geht, macht das Script nichts
	
	return 0;
 }

Dann in Aktion 333:

int main()
{
	//definition Variable "gFruits"
	idtypelist::insert(gFuncVars, -1, 1, 0, 0, "gFruits//Früchte");
	idtypelist::insert(gFuncVars, -1, 1, 1, 0, "apples//Äpfel");
	idtypelist::insert(gFuncVars, -1, 1, 2, 0, "pears//Birnen");
	idtypelist::insert(gFuncVars, -1, 1, 3, 0, "bananas//Bananen");
		
	//zusätzlicher Aufruf einer weiteren dynamischen 
	//Definition mit der ID 444

	idtypelist::insert(gFuncVars, -1, 2, 0, 0, "##444"); 

return 0;
}

Dann in Aktion 444:

int main()
{ 
	//definition Variable "gTea"
	idtypelist::insert(gFuncVars, -1, 1, 0, 0, "gTea//Teesorte")
	idtypelist::insert(gFuncVars, -1, 1, 1, 0, "mint//Minze")
	idtypelist::insert(gFuncVars, -1, 1, 2, 0, "ginger//Ingwer")

	return 0;
}

Dabei müssen die IDs der Einträge in gFuncVars nur Skriptweit eindeutig sein.

Achten sie auch hier darauf, keine Endlosschleifen zu erzeugen, das bringt InDesign® dann nämlich schnell zum Absturz.

Es ist möglich, für die Anzeige im Dropdown (siehe Konfiguration - 'Wert der Variable') und den tatsächlich im cScript oder Statement verwendeten Wert unterschiedliche Werte zu vergeben. Das ist sinnvoll in Situationen, in denen die Werte Namen haben können (z.B. Ja, Nein), in den Anweisungen aber mit Werten (z.B. 0, 1) gerechnet wird. Name und Wert werden durch einen doppelten Schrägstrich (//) getrennt. Der Name wird dabei gemäß der cScript-Funktion translate übersetzt und erst dann angezeigt:

Allgemeine Sytnax zur Namensvergabe für Werte von Funktionsvariablen. Der Namensteil der Werte (hier name1, name2, ...) wird, wenn es eine Übersetzung dafür gibt, in der aktuellen Illustrator®-Sprache angezeigt..

#pragma var "variableName" "value1//name1" "value2//name2" ...

Beispiel:

Die Variable variableName kann die Werte 0 oder 1 bekommen. Angezeigt werden ja und nein (bzw. yes/no, oui/non). Die Übersetzungen von ja/nein sind im Standard der Plugins enthalten.

#pragma var "variableName" "1//ja" "0//nein"

Wenn sie einen doppelten Slash in ihrem Wert verwenden möchten, muss dieser durch einen Backslash escaped werden.

Beispiel:

#pragma var "gGeschirr" "Teller\//Tassen"

Wir erklären das am Besten mit einem Beispiel.

Hier ein ganz einfaches Ladenskript

#pragma var "variableName" "##456"

int main ()
{
	wlog ("", "(%s)\n",variableName);
	return 0;
}

Wenn Sie einen Platzhalter mit diesem Ladenskript ins Dokument gesetzt haben und anklicken, führen die Platzhalterwerte die Action 456 aus und erhalten eine Wertliste. Diese Werteliste wird in den Platzhalterwerten angezeigt. Der aus dieser Liste ausgewählte Wert wird im Platzhalter im Dokument hinterlegt.

Wie Sie sehen, enthält das Skript KEINE Deklaration der Variable variableName. Das darf es auch nicht, die Variable wird durch den Ladenprozess definiert! Der fügt vor dem Ausführen des Skripte dort die folgende Zeile ein:

char variableName [] = "Ihre Wahl";

Und dann kann der Platzhalter loslegen - hier also das Log vollschreiben.

ACHTUNG Funktionsvariablen sind IMMER char[]. Wenn man die Werte als int oder float benötigt, müssen sie mit val oder fval umgerechnet werden. Und! Die Strings dürfen nicht verändert werden!

Beispiel 1

#include "internal/types.h"

#pragma var "gLanguage//Sprache" "de//Deutsch" "en//Englisch" "fr//Französisch"
#pragma var "gAttributeTable//Tabelle" "comet_attribute"

int main()
{
	DBC 	dbc 	= sql::dbconnection();
	Query 	qu 		= sql::query(dbc);
	int 	id;

	query::send(qu, "select id from ");
	query::send(qu, gAttributeTable);
	query::send(qu, " where keyname = ? and infoobject_id = ? and lang = ? and active = 1 order by sort ");

	query::input(qu, kString, "Auflage");
	query::input(qu, kString, gRootTableRecordStringID);
	query::input(qu, kString, gLanguage);

	query::output(qu, kInt, &id);

	query::exec(qu);
	while (query::fetch(qu))
	{
		idtypelist::append(gProducts, 1, 0, 0, itoa(id));
	}
	query::close(qu);

	return 0;
}

Zusätzlich werden in cScripten zwei globale variablen vom Typ StringList zur Verfügung gestellt: gFuncVarNames und gFuncVarValues, in denen die Variablennamen und ihre eingestellten Werte abgefragt werden können. Die Variablennamen sind dabei immer die tatsächlichen Namen, nicht die Anzeigenamen.

Beispiel 2:

#include "internal/types.h"

#pragma var "gColor//Farbe" "red//Rot" "green//Grün" "blue//Blau"
#pragma var "gSize//Größe" "small//Klein" "medium//Mittel" "large//Groß"
			
int main()
{
	int 	i 				= 0;
	int 	funcvarCount 	= StringList::length(gFuncVarNames);
			
	wlog("", "Funcvar count: %d\n", funcvarCount);
			
	for (i = 0; i < funcvarCount; i++)
	{
		wlog("", 
			"Funcvar : name: %s, value: %s\n",
			StringList::get(gFuncVarNames, i),
			StringList::get(gFuncVarValues, i)):
	}
		
	return 0; 
}

Beispiel 2 Ausgabe im Logfile mit den Default-Werten:
Funcvar count: 2
Funcvar name: gColor ; Funcvar value: red
Funcvar name: gSize ; Funcvar value: small

Die oben genannten Listen gFuncVarNames und gFuncVarValues stehen in Statements nicht zur Verfügung.

In (SQL/XML)Statements müssen die Variablen zur Verwendung mit Spitzen Klammern umschlossen werden. Sie werden automatisch in einfache Anführungszeichen gesetzt. Ist dies nicht gewünscht verwenden sie folgende Syntax:

<*Unquoted_variableName>

Beispiel 1:

#pragma var "gLanguage" "de" "en" "fr"
		
select value_string 
from comet_attribute 
where 	keyname = 'Titel' 
		and infoobject_id = <StringID> 
		and lang = <gLanguage> 
		and active = 1

Beispiel 2:

#pragma var "gLanguage" "de" "en" "fr"
select value_string
from comet_attribute
where 	keyname = 'Titel' 
		and infoobject_id = <StringID> 
		and lang = '<*Unquoted_gLanguage>' 
		and active = 1

Funktionsvariablen werden in TaggedText innerhalb des <w2>-Tags als Tripel verwendet. Die Definition wird mit dem Schlüsselwort functionvariables eingeleitet, die Tripel folgen in einfachen Anführungszeichen. Jedes Tripel besteht aus Variablenname, Variablenwert und Aktionszugehörigkeit, jeweils in doppelten Anführungszeichen.
Die Aktionszugehörigkeit ist eine Zahl und beschreibt, für welche Aktion des Platzhalters die Variable definiert wurde. Folgende Werte sind möglich:

• 1 : Laden
• 2 : Schreiben
• 3 : Sync
• 4 : Aufbau

Beispiel:

<w2:
	30, 0, 0, 0, '',
	definition 3 1 30 0 -1 0 0 6 0 0,
	infos1 '', infos2 '',
	prefix '',
	prefixifempty '', postfix '', postfixifempty '',
	created '20170622154717', modified '20170622115641',
	rules '',
	functionvariables
		'"decimalPlaceCharacter" ";" "1"
		"formatString" "%s" "1"',
	valuehashes ''
>
AAA
<w2:>

In diesem Beispiel wurde der Taggedtext eines Textrahmens exportiert. Der Text "AAA" hat einen Platzhalter der zwei Funktionsvariablen definiert:

1. Variablenname: decimalPlaceCharacter, Variablenwert: ; (Semikolon), Aktionszugehörigkeit: 1 (Laden-Aktion)
2. Variablenname: formatString, Variablenwert: %s, Aktionszugehörigkeit: 1 (Laden-Aktion)

Aus Tabellenzellen werden Funktionsvariablen in Taggedtext als Teil des <w2Cell>-Tags verwendet. Die Syntax ist der von Textplatzhaltern sehr ähnlich, allerdings werden Sie hier durch das Schlüsselwort CellFunctionVariables eingeleitet. Der Rest der Syntax entspricht der von Textplatzhaltern. Die Werte für die Aktionszugehörigkeit sind folgende:

• 1 : Zeile kopieren, Einfügen
• 2 : Zeile kopieren, Auslassen
• 3 : Spalte kopieren, Einfügen
• 4 : Spalte kopieren, Auslassen
• 5 : Berechnen der IDs der Zelle

Beispiel:

<CellStart:1,1
	<w2Cell:
		ColActionID=2000 
		ColMany=0
		ColGroup='' ColGroupPrefix1='' ColGroupPrefixN=''
		ColID1=0 ColID2=0 ColID3=0 ColIDString=''
		RowActionID=0
		RowMany=0 RowGroup='' RowGroupPrefix1='' RowGroupPrefixN=''
		RowID1=0 RowID2=0 RowID3=0 RowIDString=''
		Groups=''
		ContentType=0 ContentTypeEntry=0
		ContentMap1=0 ContentMap2=0 ContentMap3=0 ContentMap4=0
		Preprocess='' Postprocess=''
		IdentMappings=''
		ContentID1=0 ContentID2=0 ContentID3=0 ContentIDString=''
		ColFirstLast=0 RowFirstLast=0
		ColOmitActionID=0 RowOmitActionID=0 RepeatContent=0
		ColBlockSize=1 RowBlockSize=1
		CellID1=30600005 CellID2=577563520 CellID3=0 CellIDString=''
		ColParentID1=0 ColParentID2=0 ColParentID3=0 ColParentIDString=''
		RowParentID1=0 RowParentID2=0 RowParentID3=0 RowParentIDString=''
		ReservedString2='' ReservedString3=''
		CellFunctionVariables=
			'"gUser" "Leo" "3"
			"gTable" "comet_config" "3"'
		ReservedID21=0 ReservedID22=0 ReservedID23=0 ReservedID2String=''
		ReservedID31=0 ReservedID32=0 ReservedID33=0 ReservedID3String=''
		ReservedID41=0 ReservedID42=0 ReservedID43=0 ReservedID4String=''
		ReservedLong4=0 ReservedLong5=0 ReservedLong6=0
	>
>

In diesem Beispiel werden für die Zelle zwei Funktionsvariablen definiert:

1. Variablenname: gUser, Variablenwert: Leo, Aktionszugehörigkeit: 3 (Spalte kopieren, Einfügen-Aktion)
2. Variablenname: gTable, Variablenwert: comet_config, Aktionszugehörigkeit: 3 (Spalte kopieren, Einfügen-Aktion)

Die Konfiguration der Funktionsvariablen erfolgt durch die jeweilig zuständige Palette (siehe Verfügbarkeit). In den Paletten gibt es Listen, die die aktuell definierten Variablen zeigen:

• 1. Status der Variable

  Die Symbole haben folgende Bedeutung:

Bild	Beschreibung
	Synchronisiert: Die Zelle/der Platzhalter hat einen Wert für diese Variable gesetzt welcher verwendet wird.
	Nur durch Aktion definiert: Die Zelle/der Platzhalter hat keinen Wert für diese Variable gesetzt. Es wird der Standardwert der Variable verwendet (oder leer wenn keiner definiert wird). Bei der nächsten änderung wird der selektierte Wert in die Zelle/in den Platzhalter gesichert.
	Nicht durch Aktion definiert: Diese Variable ist in der Zelle/im Platzhalter definiert, aber nicht in der Aktion. Sie hat keinerlei Effekt und wird bei der nächsten änderung verworfen.

• 2. Name der Variable

• 3. Trenner

  Diese Trenner werden zwischen jeder Aktion eingefügt, um Verwirrungen zu vermeiden (schließlich können zwei unterschiedliche Aktionen die selben Variablennamen verwenden).

• 4. Wert der Variable

  In dem Dropdown können die von der Definition vorgebenen Werte ausgewählt werden. Die Auswahl "Benutzerdefiniert" ermöglicht die manuelle Eingabe eines Wertes.

• 5. Benutzerdefinierter Wert

  Wenn bei (4) der Eintrag "Benutzerdefiniert" ausgewählt ist lässt sich hier per Mausklick ein eigener Wert von Hand eintragen.

• 6. Bearbeitung einschalten

  Wenn das Schloss geöffnet wird, wird die Bearbeitung der Variablen ermöglicht.
  Bei verriegeltem Schloss ist die Bearbeitung der Funktionsvariablen nicht möglich. Um Änderungen an den Variablen zu sichern, muss das Schloss mit gedrückter ALT-Taste verriegelt werden. Dabei werden Funktionsvariablen, die nicht durch die Aktion definiert sind (markiert mit Ausrufezeichen als Statussymbol) verworfen. Ohne gedrückte ALT-Taste werden die Änderungen rückgängig gemacht.
  Wird die Selektion im Dokument geändert oder die Palette geschlossen, wird das Schloss automatisch verriegelt ohne die Änderungen zu sichern.

Diese Anzeige ist abhängig vom gerade ausgewählten Platzhalter/Tabellenzelle und den gesetzten Aktionen.