Comet placeholders

Placeholders are the central objects of the Werk II plugins. They connect parts of the InDesign^® document with external values from the databases, XML or CSV files, Excel tables or special Internet services. Every placeholder can be connected with four actions :

• Load
• Write back
• Check its contents
• Building repeated elements

• SQL instructions
• xmlquery
• soap calls
• cscript

In order that scripts have access to the current document environment, various global variables are pre-defined. The following table describes these keys . Although the keys may be used in scripts like variables, these values of these variables should not be changed. In particular, variables may not be deleted (e.g. gItem or gFrame).gDocumentID}gDocumentPath}

Name	Data type	Definition area	Description
gRun	int	Request status for a script	See gRun
gRecordID	int	placeholder and doubleclick scripts	1st id of the object which is connected with the placeholder
gRecordID2	int		2nd id of the object which is connected with the placeholder
gRecordID3	int		3rd id of the object which is connected with the placeholder
gRecordStringID	char*		StringID of the object which is connected with the placeholder.
gRecordStringID1	char*		First part or RootTableRecordStringID of the |--| delimited Multi-StringID (or string id) of the object which is connected with the placeholder.
gRecordStringID2	char*		Second part or ColumnRecordStringID of the |--| delimited Multi-StringID (or empty) of the object which is connected with the placeholder.
gRecordStringID1	char*		Third part or RowRecordStringID of the |--| delimited Multi-StringID (or empty) of the object which is connected with the placeholder.
gStart	int	placeholder scripts	Start position of a text placeholder, see gStart
gLen	int		length of a text placeholder, see gLen
gItem, gFrame	ItemRef		For frame placeholders of the frame, for text placeholders of the frame of the text
gOutFrame	ItemRef		You may change the contents of this reference, see gOutFrame, item::copy
gPlaceholderID	int		ID of the placeholder
gPlaceholderType	int		Since v4.2 R32672 Type of placeholder: 1 text 2 textframe 3 imageframe 4 xml element 5 document 6 multi frames 7 multi text 8 autoTable 9 CrossRef 10 SerialText 11 SerialFrame 12 SerialPageitem
gCreated	char*		Placeholders creation date and time, format YYYYMMDDHHMMSS.
gModified	char*		Last time the placeholder was loaded, format YYYYMMDDHHMMSS.
gNewValue	char*		You may change the contents of this reference. Max: 2 GB. You can set the Text of "New Value:" caused by load-scripts in the ToDo-List-Panel. Only calls from the ToDo List allocates this variable. In all other calls to load scripts, its value is 0, so always check it! Never change the InDesign® document in case of gNewValue not equal 0!
gOldValue	char*		Set the document value of a placeholder shown in the ToDo panel. This value is taken from the document by default. Under some rare circumstances you may wish to set you owns values here. gOldValue is capable of 2 GB of characters. Always check whether the variable is not 0 (if (gOldValue) ...).
gSyncChanged	int*		load and sync script onlyThe placeholder state is set to Okay after load scripts automatically. In case you changed the placeholder state inside the script using placeholder::set_sync, you can suppress this behavior by setting *gSyncChanged = 1;. Vice versa the placeholders state is not set automatically after running a sync script. To change the placeholders state to Okay after a sync script automatically, simply call *gSyncChanged = 0; once inside the sync script. Anyway, script errors will change the placeholders state to Error in both script types.
gExportValue	char*		If the menu Behavior when loading placeholders -> Load and export to update folder is activated, placeholder content is stored to the update folder after inserting it into the document. If the load script is a cScript, the content of gExportValue is used. The content must not be longer than 6 MB. Longer content leads to an InDesign® crash! See here for more information. Information can also be found about the script functions prefs::set_updatetype, ... .
gTimestamp	int		The value in the current version is always 0.
gLink	char*		For frame placeholders of the complete path on the image, which is displayed in the frame. Otherwise the string is empty.
gLinkFolder	char*		For frame placeholders of the path on the image, which is displayed in the frame. The path contains no path delimiter at the end. Otherwise the string is empty.
gLinkName	char*		For frame placeholders of the name of the image, which are displayed in the frame. Otherwise the string is empty.
gRepagination	int		0 : Generell script call 1 : Automatic Comet repagination called (after loading all placeholders of the current document) or document::update_crossrefs, or book::repaginate called.
gScriptType	int	Product building (actions with classID 14)	1 kPreScript 2 kPreRule 3 kPostRule 4 kExtraPlacement 5 kTextflowPreScript 6 kTextflowPreRule 7 kTextflowPostRule
gPage	int*		1-based page number which are currently being built on. If the script sets up new pages, the contents of this variable must be adapted.
gMasterpage	char*		Parent page name. The value can be used in the script during set up of the new pages.
gProducts	ProductList		List of the products which are to be built up. The list can be processed in the kPreScript. Build scripts of the table module also have gProducts defined. But this is a list of data type IDTypeList instead!
gProduct	Product		This product is currently being built up. The variable only has a value in the script types kPreRule and kPostRule. The variable may not be deleted.
gIndexOffset	int*		Currently used index in the grid of the product build-up. The grid element are used in ascending order according to their ID. An increase in the value has the effect that during product build-up a corresponding amount of grid places are jumped over. If the end of the page is reached, a new page is created and the product is placed at the top of the new page.
gErrMess	char*		Error description, maximum 1023 characters.
gPageitemID	int*	Template substitution (Actions with classID 15)	Change the content of gPageitemID, if you want to use an other template instead of the given one. Do NOT change any other of the script globals!
gPageitemName	char*		Name of template "" : on calls outside page buildungs (e.g. manual product placements by drag and drop)
gPage	int		1-based page number
gLayer	char*		Current layer to place the template
gPositionX, gPositionY, gPositionX_out, gPositionY_out, gPosition_changed	float, float, float*, float*, int*		Position to place the template. AttentionSince the next free place inside the element (also) depends on the size of the template, the actual insertion position may differ from this specification. 0.0, 0.0: on calls outside page buildungs (e.g. manual product placements by drag and drop) See here for a discussion about gPositionX_out, gPositionY_out and gPosition_changed.
gGridPosX, gGridPosY	float, float		Insert position relative to the page element AttentionSince the next free place inside the element (also) depends on the size of the template, the actual insertion position may differ from this specification. 0.0, 0.0: on calls outside page buildungs (e.g. manual product placements by drag and drop)
gElementLeft, gElementTop, gElementRight, gElementBottom	float, float, float, float		Coordinates of the current page element AttentionSince the next free place inside the element (also) depends on the size of the template, the actual insertion position may differ from this specification. 0.0, 0.0, 0.0, 0.0: on calls outside page buildungs (e.g. manual product placements by drag and drop)
gElement, gElementName	int, char*		1-based page element and its name AttentionSince the next free place inside the element (also) depends on the size of the template, the actual insertion position may differ from this specification. 0.0, 0.0, 0.0, 0.0: on calls outside page buildungs (e.g. manual product placements by drag and drop)
gPageTemplateID, gPageTemplateName	int, char*		Aktuelles Seitentemplate des Aufbaus. 0, "" : on calls outside page buildungs (e.g. manual product placements by drag and drop)
gClicked	int	Double click scripts (actions with classID 18 - Product pool 19 - Documents 20 - Previews)	In 'Double click scripts' only: One row of the panel list was double clicked. The variable contains the 0-based row number.
gDocument	ItemRef	-	Current front document or document of the Document Watch.
gDocumentID	char*	Scripts of Doc Watch and Publication Scripts	Document-ID, see document::setid and document::getid Since R12535, 7. Sep 2016 the variable is also defined in placeholder scripts and in scripts of the table building module.
gDocumentPath			Path of document. Attention : Empty in scripts before open, after close and for new document!
gDocumentPathPDF			Path of the PDF of the document. Using comet_pdf the variable contains th complete path to the output PDF. In InDesign® only the file extension of the path is replaced by .pdf.
gBeforeMetaData	int		Before the metadata are generated (or could be generated), comet_pdf calls the DocWatcher "Before-Close" once. In this case gBeforeMetaData is 1. Otherwise the constant always has the value 0.
gSourcefolder	char*	Batch scripts (actions with classID 22)	Currently used folders of 'batch scripts'. Database based batches get this folders from the database, the folders can differ from set to set. Otherwise the currently defined hot folders are used and the destination folder is used as to be the error folder too.
gDestfolder
gErrorfolder
gObjectPath
gTemplatePath
gJobID	int		ID of current batch job
gEditionID, gEditionID2, gEditionID3	int	'Editions scripts' of panel Editions (Actions withclass ID 28)	ID of Edition
gEditionStringID	char*		string id of Edition
gEditionName	char*		Name of edition (First row in panel Editions)
gEditionPublication	char*		Type of edition (Second row in panel Editions)
gEditionPages	int		Pages of an edition (Thirst row in panel Editions)
gEditionDate	char*		Editions date (4th row in panel Editions)
gTableID	int*	Load script of table placeholders	This scripts are executed, to replace a table placeholder by its table. To build the table itself, so called table build scripts are called. In the script you define the table id (a template), which replaces the current text of the placeholder, see here for example.: *gTableID = 34;
gBuildTable	int*		Suppress table building : *gBuildTable = 0;. You should call table::build inside the load script of the frame in this case.
gTable	ItemRef	Table build scripts (actions with classID 23)	This scripts are executed, to get a list of products to be inserted in a table on table building. To replace a table placeholder by its table use a table placeholder load script. Table to be build. The table is reseted (see table::reset at this point.
gRow	int		Calling cell
gColumn
gProducts	IDTypeList		Insert all products you wish to insert in the table to this list by using calls like idtypelist::append (gProducts, 1, 0, 0, "");. Scripts for product building are also use a list named gProducts, but this list of type ProductList.
gMoreGroups	StringList		For every inserted product you may give one ore more groups to put the created table cells into. Group names must be unique. Group names must be divided by blanks. If a group name contains a blank, quote it: group_1 group_1 parent "group 1" parent To avoid mapping errors, insert a more groups entry for every product inserted into gProducts using calls like: char str[1000]; stringlist::append (gMoreGroups, sprintf (str, "\"Group %d\"", idtypelist::length (gProducts)+1));
gRootTableRecordID	int		Root-ID of table
gRootTableRecordID2
gRootTableRecordID3
gRootTableRecordStringID	char*
gColumnRecordID	int		ID of table column
gColumnRecordID2
gColumnRecordID3
gColumnRecordStringID	char*
gRowRecordID	int		ID if table row
gRowRecordID2
gRowRecordID3
gRowRecordStringID	char*
gCellRecordID	int		[since v3.3.1 R3387] ID of cell
gCellRecordID2
gCellRecordID3
gCellRecordStringID	char*
gTable	ItemRef	Table shape methodes (actions with classID 24)	Table to work on
gAreaLeft	int		Cells to work on. The range starts at Left, Top and ends before Right, Bottom.
gAreaTop
gAreaRight
gAreaBottom
gMasterFrame	ItemRef	itemlist::logical_groups scripts (actions with classID 34)	siehe itemlist::logical_groups
gCheckFrame
PubServer specific variables		Various	See here for mor information. Values only well defined in Comet4-PUBSERVER connections. DO NOT USE IN OTHER CONNECTIONS!

In SQL instructions, soap calls and xmlquery call of actions, access is possible to the current environment of the form <Tagname>. Tagnames are case sensitive.

All tags containing string values (type char*) are enclosed in single quotas by default. Single quotas inside the string are escaped. Use one pf the following prefixes to suppress this behavior.

The old tag StringID (case sensitive) is not quoted, but single quotes insinde its value are doubled by default.

Prefix	Description	Example	abc'def results in ...
	escape single quotas inside the string and enclose the string in single quotas	<layer>	'abc''def'
Unquoted_	escape single quotas inside the string	<Unquoted_layer> <parent.parent.Unquoted_Name>	abc''def
Content_	No changes are made	<Content_layer> <parent.parent.Content_Name>	abc'def
Not supported - this strings will produce errors			'abc'def'

Take care to insert the prefix in front of the last '_' delimited word of the tag.

ab R 1401, 1. Juli 2009 The following functions support handling of string tags (char*):

• lower
• upper
• trim
• reverse
• substr (from, len)
• rsubstr (from, len), pos and len counted from the end of the string
• token (num, delim_str), num 0 based, the first charcacter of delim_str is used is as the token delimiter

Get the file extender of a <document> tag:

<document reverse token (0, ".") reverse>
- String umdrehen (abc.indd wird zu ddni.cba)
- erstes durch '.' getrenntes Token (ddni)
- wieder zurückdrehen (indd)

The following tags are defined:

Name	Data type	Definition area	Description
ID	int	In placeholder and table actions only On table builing, the calling cell use to determine pages, layers, text contents, ...	1st id of the object with which the placeholder is connected
ID2	int		2nd id of the object with which the placeholder is connected
ID3	int		3rd id of the object with which the placeholder is connected
STRING	char*		StringID of the object with which the placeholder is connected.
STRINGID1	char*		First part or RootTableRecordStringID of the |--| delimited Multi-StringID (or string id). You may use the StringID1 too, but this key is not qouted automatically.
STRINGID2	char*		Second part or ColumnRecordStringID of the |--| delimited Multi-StringID (or empty). You may use the StringID2 too, but this key is not qouted automatically.
STRINGID3	char*		First part or RowRecordStringID of the |--| delimited Multi-StringID (or empty). You may use the StringID3 too, but this key is not qouted automatically.
text, textplus	char*		Current document text of the placeholder. The export corresponds to the result of the function textmodel::gettext with the format parameter kExport(Plus)Plain. The 'plus' variant also replaces all automatic page numbers, paragraph names and footnote markers by their current values.
text_notypografics, textplus_notypografics	char*		Current document text of the placeholder with all typografic quotes replaced by "normal" quotes. The export corresponds to the result of the function textmodel::gettext with the format parameter kExport(Plus)PlainNoTypografics. The 'plus' variant also replaces all automatic page numbers, paragraph names and footnote markers by their current values.
taggedtext	char*		Current document text of the placeholder in InDesign® TaggedText format. In creating the export, the settings ASCII, Windows line delimiter, extended are used. The export corresponds to the result of the function textmodel::gettext with the format parameter kExportTagged. Attention: Ab v3.3 R2580 (20.07.2011) Comet placeholders are part of the normal tagged text import/export since this release. See here for more information about placeholders in tagged text.
tttext	char*		Current document text of the placeholder in Werk II %!TT-Format. In creating the export, the settings ASCII, Windows line delimiter, extended are used. Paragraph and character style will not be exported. The export corresponds to the result of the function textmodel::gettext with the format parameter kExportTT. Attention: Ab v3.3 R2580 (20.07.2011) Comet placeholders are part of the normal tagged text import/export since this release. See here for more information about placeholders in tagged text.
w2text	char*		Current document text of the placeholder in Werk II %!TT-Format. In creating the export, the settings ASCII, Windows line delimiter, extended are used. Paragraph and character style will not be exported. In the export the textplaceholders of the document text will be inserted. The tag may not be used in order to export text from text placeholders. The export corresponds to the result of the function textmodel::gettext with the format parameter kExportW2. Attention: Ab v3.3 R2580 (20.07.2011) Comet placeholders are part of the normal tagged text import/export since this release. See here for more information about placeholders in tagged text.
unitext, unitextplus	char*		Pure text import, all special characters (Ascii > 127) are coded in the form \00FC. The export corresponds to the result of the function textmodel::gettext with the format parameter kExport(Plus)Unitext. The 'plus' variant also replaces all automatic page numbers, paragraph names and footnote markers by their current values.
xunitext, xmlunitext, unitextplus, xmlunitextplus	char*		Pure text import, all special characters (Ascii > 127) are coded in the form <0x00FC>. The export corresponds to the result of the function textmodel::gettext with the format parameter kExport(Plus)XUnitext resp. kExport(Plus)XMLUnitext. The 'plus' variant also replaces all automatic page numbers, paragraph names and footnote markers by their current values.
rtftext	char*		The export corresponds to the result of the function textmodel::gettext with the format parameter kExportRTF.
xhtml	char*		The export corresponds to the result of the function textmodel::gettext with the format parameter kExportHTMLWithStyles.
textlen	int		Length of the current placeholder in letters
link	char*		Complete path including file name to the image of a graphic frame or empty string
linkfolder	char*		Complete path without file name to the image of a graphic frame or empty string. Path delimiter at end of the path will be removed.
linkname, linknameN	char*		Name of the file or empty string displayed in a graphic frame. A positive whole number may stand after the name, it states the number of the path parts which are to be specified. For 2, the folder of the file will be with returned (bilder/name.jpg), for 3, the order o der Ordner des Ornders (aktuell/bilder/name.jpg) usw.. If the complete path is comprises of a few folders, the complete path will be returned.
random	char*		For testing purposes random number in area 0-255.
placeholderID	int	in placeholder actions only	[ab Release R 230] ID of calling placeholder
created	char*		[ab Release R 230] date and time of creation in the format yyyymmddhhmmss
modified	char*		[ab Release R 230] date and time of last modification in the format yyyymmddhhmmss
Placeholder Options	see column Type of table Placeholder Options		[ab Version 2.1 R 811] You may use all names of the tables in the form <Name>. Unquoted_ and Content_ allowed as prefixes.
document	char*	always	Name of InDesign® file
folder	char*		Folder in which the file is found. The path is specified in system-compatible form.
folderX	char*		Folder in which the file is found. In the path all Windows path delimiters (\) are replaced by /. (Recommended for xmlquery, soap, and the script language.)
path	char*		Complete path of the document. The path is specified in system-compatible form.
path9	char*		Complete path of the document in the format of Mac OS 9
pathX	char*		Complete path of the document. In the path all Windows path delimiters (\) are replaced by /. (Recommended for xmlquery, soap, and the script language.)
page	int		1-based number of the page in the document in which the placeholder is located. since v3.3 R3901 If no placeholder action is active, InDesign® Desktop returns the currently selected front page. On InDesign® Server the result is 0.
pagestr	char*		Page numbers used as they are in the document since v3.3 R3901 If no placeholder action is active, InDesign® Desktop returns the name of currently selected front page. On InDesign® Server the result is empty.
layer, layer.1 layer.2 layer.3	char*		Name of complete layer or, in case of .1, ..., nth #-delimited token of layer name If the current placeholder is on layer CH#de, then we get: <layer.1> = "CH" <layer.2> = "de" <layer.3> = "" since v3.3 R3901 If no placeholder action is active, InDesign® Desktop returns the name of currently selected front layer. On InDesign® Server the result is empty.
pages	int		Number of pages in the document
documentID	int		Comet of document, see document::setid and document::getid
documentID2
documentID3
documentSTRINGID	char*
application	char*		seit R1145 Complete path to the executing InDesign®
plugins			seit R1145 Complete path to the currently used plug-ins folder
comet			seit R1145 Complete path to the currently used priint:comet InDesign® Plug-Ins folder
xmlfolder			seit R1145 Complete path to the currently used xml pool or empty
cache			seit R1145 Complete path to the currently used Comet cache. On ODBC connection, the value is empty.
now	char*	always	Current date and current time. For string results, the information is given in the format of the presettings of the computer/user.
date	char*
time	char*
day	int
month	int
year	int
hour	int
minute	int
second	int
dayOfWeek	int
dayOfYear	int
weekOfYear	int
date_sep	char*
time_sep	char*
am	char*
pm	char*
os	char*	always	Operating system on which the plugin is run Mac OS X Windows
version	char*		Current version of the Werk II plugins
version_id	int		see system::version
is_server	int		see system::is_server
author	char*		Matthias [Paul] Seidel
vendor	char*		Werk II
currency	char*		Current currencey sign of the operation system
host	char*		Computer name
login	char*		Name, under which the user of computer is registered
lang	char*		see system::language
tcpip	char*		see system::tcpip
macid	char*		see system::macid
user	char*	for valid database or SOAP connections only	Information on the login to the database or the SOAP service
userid	int
server	char*
database	char*
client	char*
encoding	int		Following values defined : 0 : no coding 1 : UTF8 2 : Unicode 16Bit 3 : Unicode 32Bit
sessionId	char*		For valid PubServer connections only Current session Id, see also system::session_id
publication_id	int	In transmission planning and research when loading "Genre"
publication_code	char*
brandID	int	Work preparation when searching the List IDs (PanelStatement 19)	ID of the popup menu 'Search'
brand	char*		Value of the popup menu 'Search'
label	char*		Entry for 'labelling'
depth	int	Loading ID of double-click action	Loading the id of an action executed on a double click in the product pool panel (PanelStatement 95) or in the documents panel (Panelstatement 96). ausgeführt werden soll.
searchvalue1	char*	Loading the entries of product pool panel	Search fields in the panel appended automatically by the wildcard %. If the field is empty, the value is "%". Otherwise the the tag is replaced (case sensitive) by the field value.
searchvalue2
searchvalue3
searchvalue4
searchvalue1_nopercent	char*		Search fields in the panel without the % wildcard. If the field is empty, the value is "%". Otherwise the the tag is replaced (case sensitive) by the field value.
searchvalue2_nopercent
searchvalue3_nopercent
searchvalue4_nopercent
pageitemID	int		since v4.1.6 R24942 Template ID of product to open
type	char*	Loading entries of pageitems panel	Selected entry of the popup menu "Type" (name and ID).
typeid	int
RootTableRecordID	int	Table module	Record IDs of the table
RootTableRecordID2
RootTableRecordID3
RootTableRecordStringID	char*
ColumnRecordID	int		column record ids
ColumnRecordID2
ColumnRecordID3
ColumnRecordStringID	char*
RowRecordID	int		row record ids
RowRecordID2
RowRecordID3
RowRecordStringID	char*
CellRecordID	int		[since v3.3.1 R3387] cell record id
CellRecordID2
CellRecordID3
CellRecordStringID	char*
RowParent.	-		[seit v3.3.1 R3387] Get a parent ID of the cell. Open one of the ~Record~ID~ (except RootRecordIDs) keys this one or more Row- or ColParent prefixes (in any order) to walk through the cells parents and get their IDs. Examples     <RowParent.RowRecordID>     <RowParent.RowParent.CellRecordID>     <RowParent.ColParent.CellRecordID>
ColParent.
PubServer specific tags		Various	See here for mor information. Values only well defined in Comet4-PUBSERVER connections. DO NOT USE IN OTHER CONNECTIONS!

Every action can be written in cscript. In most cases it is however adequate (and faster) to execute an appropriate command from the data source, which gets or writes the required data:

• Data folder (XML-Offline) : xmlquery or (since v4.1.5 R24666) XPATH
• ODBC : SQL
• PubServer/SOAP : Comet SOAP Interface

Return : Exactly one text column. select name from products where id = <ID> "products.xml" select name node products.product where id=<ID>

On image placeholders the first row is taken as path to the image. The path must be complete but may begin with one of the supported short cuts like $DESKTOP. Placing infos and clipp settings can be given in optional rows:

Name	Data type	Default	Description
Image position	int	5	Position of image relativ to the frame, see Image positions
Image size / BoundingBox	float	0.0	Scale the image to the given maximum size. 0.0 : proporional scaling to the frame. Images smaller as the frame are left un-scaled. >0.0 : Scale image to the given maximum size. Images smaller than the given value are left un-scaled <0.0 : Like above, But allow images to increase too.
Clip path index	int	0	0 base index of clip path.   -1 : Use clip path name rather than the index. If the name is empty, no clipping is applied.
Name of clip path	String	""	Name of existing clipping path. Path names not supported using InDesign® Server, please use index in this case.
Flags for clipping and alpha channels	int	0	Bit field:   1: Invert the resulting path by combining with a path equal to the bounds of the image.   2: Force edge detection to use the high resolution source image (potentially much slower but higher quality. Although the 72 dpi proxy does a pretty good job).   4: For edge detection, do we remove the holes or leave them in.   8: For edge detection, do we only detect edges within the visible portions of the image? That is, do we crop the image to its frame before performing edge detection?
cliptoFrame	int	0	Use clip path as frame?   0 : No   1 : Yes
tolerance	float	0.0	A tolerance value specifying how close to the original path we must be if we smooth the path. 0.0 indicates a perfect match. Smoothing may simplify the path, reducing the number of points.
minPathSize	float	0.0	subpaths smaller than the minPathSize will be deleted
inset	float	0.0	how far to inset the path
Alpha channel index	int	-2	0-based alpha index in image   -2 : Do not use alpha channel   -1 : Use path name rather than te index.
Name des Alphakanales	String	""	Name of existing alpha channel. Path names not supported using InDesign® Server, please use index in this case.

Sync scripts are called to check whether the documents content of a placeholder is synchron to the datatpool content. Use placeholder::set_sync to set the placeholder sync state.

since v3.3 R2580 Sync scripts are very time-consuming. You may avoid this time by simply setting the sync ID of the placeholder to -1! In this case, the load action of the placeholder is called automatically. If this action is a statement, the plugins can calculate the sync state very easy. If the action is a script, the globale variable gNewValue is defined and you have to copy the placeholders new value into it (up to 2 MB).

Most of your sync scripts still containing gNewValue to retreive the "new value" for the placeholder in the "To Do" panel. Even this variable is now defined in load scripts called by the sync process too. You may input results up to 2 MB here.

In repeating elements please set the sync status to -1 always. Notes on implementing your own sync scripts for repeating elements can be found here.

Check, if gNewValue is not 0 (if (gNewValue) ...). If so, you are in a call from the "To Do" panel or an automatic sync call. In both circumstances the variable will get the same value. After setting gNewValue leave the script as soon as possible without changing the document.

The result of the load statement (or the content of gNewValue) is checked against the placeholders current values. For comparisons the "net weights" of the strings are used :

• Replace empty strings by a zero width space (Unicode 0x200B).
• Replace all UTF-8 letters by their (Unicode) tags <0xXXXX>.
• If the strings begins with %!TT, remove the ParaStyle right behind %!TT.
• Replace all other ParaStyles by paragraph delimiters (hard returns).
• Remove all remaining TaggedText tags.
• Replace every double quota by " and every singe quota by '.
• Replace every blank (Unicode 0x2000 - 0x200F) by space.
• Replace every hyphenation sign (Unicode 0x2010 - 0x2016) by minus.

Automatic Sync-Calls can also be used in image placeholders. In other frame placeholders they can be used, but they usually make little sense.

To build repeating elements, the build script of the placeholder is executed. Load, Sync and Store scripts have no meaning with these placeholders and are ignored. The call must return the following result columns:

• ID, ID2, ID3 (int, int, int), the ID of the object, with which the placeholder of the inserted template is to be connected.
• StringID (string), the string ID of the object, with which the placeholder of the inserted template is to be connected.
• classID (integer), the ClassID is only used if it is to be checked if an object of the specified ID already exists in the document (characteristic checker=if_not_exists)
• pageitemID (integer), Template which is to be inserted. If different variants for the left and right pages been defined for the specified template, the optimal template will automatically be used.
  
• formatString (string), Description of the build action.

The format string is build as a semi-colon divided list of definitions of the type Property=Value. The following table describes all characteristics and their associated values.
The format string is read anew for each template to be inserted but type, pin and cell are taken from the first element only.
If the same characteristic is set more than once in a format string, the final specified value will be used. THE sand-colored stored characteristics stored in the table are bit fields, the values are added here. Therefore the post characteristic have the values delete_parent and autoload, but the pin pin has a new value.

Here you can find an example of a repeating element with free placements.

Characteristic	Value(s)	Default	Description
type	row, column, table (cols), stagger, area	stagger	Arrangement of the elements. The value table requires the specification of a column number. The size of the first column can be defined in cell in this case. If table is specified, no table is created, but the entries placed like a table. Die Angabe des Types wird nur im ersten Element ausgewertet. Bei allen folgenden Elementen wird sie ignoriert!
			area : Ab Comet 4.1 R12400 Anordnung der Elemente basierend auf einem oder mehreren Layoutrahmen. Einstellungen zum Aufbautyp area machen Sie in der Palette Bereichsaufbau. Die Option ignoriert die Einstellungen pin, offset, scale, rotate und fit.
pin	lt, ct, rt, lc, ce, rc, lb, cb, rb [ + (float, float) ]	lt	At which corner of the repeating frame should the elements be inserted? The pin is only evaluated for the first element and is ignored in all other elements. Optionally, an offset in the format + (float, float) can be added after the reference point. The offset is evaluated for every element, but always refers to the pin of the first element.
cell	(float, float)	(0.0, 0.0)	Size of the table cells for stagger=table (N). If one of the two values is 0.0, the size of the first template will be used.
offset	(float, float)	(10.0, 10.0)	Horizontal and vertical distance from the previous template.
scale	(pin, float, float, fit)	(lt, 1.0, 1.0, ignore)	Scale the template by a specified factor following the insert. For the reference point of the scaling one of the values of pin must be specified. Following the scaling, the frame size can be fitted with one of the fit values.
rotate	(pin, float, fit)	(lt, 0.0, ignore)	Rotate the template by a specified angle following the insert. As the reference point of the rotation a value from pin must be specified. After the rotation the frame size can be fitted with one of the fit values.
layer	"string"	""	Create the new frames on this layer. If no layer is given, the layer of executing frame is used.
fit	frame, frame_content, ignore	ignore	Fit the frame to the content or the content to the frame
link	(classID1[, classID2]*)		Connect all placeholders of the specified ClassIDs with the passed object. As ClassIDs the comma separated list of numbers can be specified . With the specification of 0 all the placeholders of the template will be linked with the object. Specifications of the form link=(1, 2, 3, 0) are however not incorrect. But because the 0 links all placeholders, link=(0) is also adequate.
checker	if_not_exists, ignore_pagesize, check_pagesize, reset,		if_not_exists : Check if an object of the specified ID is already exists in the document. This option may take a lot of time. ignore_pagesize : Normally new frames must match the current page. Turn of this behavior by using this flag. check_pagesize : Turn on checking whether new created frames matches the current page (default behavior). reset : Reset all checkers to their defaults (do not check for existing objects, check page size).
post	delete_parent,delete_parent_always, autoload, group, reset actionID	ignore	The various flags will be evaluated at different times: autoload After the insert of a template all placeholders of the template will be loaded. delete_parent After inserting all templates the trigger frame will be deleted. The frame is not deleted in case of nothing was found. delete_parent_always since v3.3.1 R4500 Like delete_parent, but the trigger frame is deleted even if nothing was found. Attention Use exactly post=delete_parent_always WITHOUT any white spaces around the =! group After the insert of the last template all the inserted templates will be grouped. If the trigger frame has not previously been deleted, this frame will be added to the group. actionID (ab v3.3 R2688, 28.10.2011) Execute the action with the given ID. The action is performed at the very end of the process. The following globals are defined here: Variable Type Description gRecordID int ID of object gRecordID2 gRecordID3 gRecordStringID char* gRecordStringID1 gRecordStringID2 gRecordStringID3 gPlaceholderID int ID of placeholder gFrames ItemList List of created frames. You can find examples in Modul behavior.

After the insert of each template all the placeholders defined in the templates will be linked with the current object and loaded. After all repeated elements are inserted, these will be grouped in one frame.

link 	= (0);
post 	= autoload;
post 	= group;

Insert the currency images of a shrub staggered over (pin=lt) in the generating frame. The images are enlarged by 50% (scale=(lt, 1.5, 1.5, frame_content)). Finally the original frame is deleted.

type 	= stagger;
pin 	= lt;
offset 	= (20.0, 20.0);
link 	= (1, 3, 5, 6);
post 	= autoload;
post 	= delete_parent;
scale 	= (lt, 1.5, 1.5, frame)

The currency images of a shrub are fixed, diversified (rotate) centred under (pin=cb) in relation to the generating frame. The images are rotated around the right bottom corner. Furthermore, the specifications type and offset are important for the representation. The specified string for rotate will work only for connections to SQL databases where rownum is defined, e.g. for Oracle..

type 	= stagger;
pin  	= cb;
offset 	= (0.0, 0.0);
post 	= autoload;
rotate 	= (rb, '||to_char(rownum*-10.0)||'.0)

Since v3.3 r3860, 11. June 2013 The positions of the repeating elements are calculated using the values given in type, pin, cell and offset. You can change the position by setting gPositionX_out and gPositionY_out to the appropriate values in the Template script of the used template. To prevend from roundation errors, you have to commit this by setting gPosition_changed to 1.

Move every element by (10, 10)

∗gPositionX_out = ∗gPositionX_out + 10.0;
∗gPositionY_out = ∗gPositionY_out + 10.0;
∗gPosition_changed = 1;

Attention: Next positions are calculated depending on type, pin, cell and offset regardless of prior changed positions! And take care to set the Template script in the template of the element, not the product!

Since Comet 4.1 R19001 the data of this call can also be determined by cScript. For this purpose, global variables are defined in the script. The following global variables must be filled in:

For a valid result, the following criteria must be met:

• gProductIDs must not be empty
• gPageItemIDs must not be empty
• gProductIDs and gPageItemIDs must have the same lengths
• gFormat must not be empty

Build three products as repeating elements and use the templates with the IDs 45, 46 and 47.

int main()
{
 	string::set(gFormat, "type=area;post=autoload");

 	idtypelist::append(gProductIDs, 1, 0, 0, "");
 	idtypelist::append(gProductIDs, 2, 0, 0, "");
 	idtypelist::append(gProductIDs, 3, 0, 0, "");

 	list::append(gPageItemIDs, 45);
 	list::append(gPageItemIDs, 46);
 	list::append(gPageItemIDs, 47);

 	return 0;
}

Since v4.1 R19501, the global list gElements of type ElementList can also be filled. If this list contains values, other information (in gProductIDs, gPageItemIDs, gFormat, and gClassID) are ignored. Format string and ClassID will be taken from the first entry of the list.

This variant is particularly useful if the data of a repeating element are determined by calling a Java method; the integration is done almost automatically, as the example below shows:

get element data via Java method call from a customer Java method

#include "[pubserver]/plugin/com.plugin.data.ElementData.c"

int main()
{
   ElementList elements = loadChildBucketsAsElements(gPSRecordId, gPSEntityId);

   elementlist::add_all (gElements, elements, 1); // remove, but do NOT clear the elements from original list
   elementlist::release (elements);

   return 0;
}

Repeating elements are checked by the sync check of the ToDo list panel. To do this, the build-script of the placeholder is executed again to fill the gElements list.

In this sync call to the build script, the variables gPrivateSync, gState, ... (see above) are set to values uneuqal 0. If this values are left untouched, a built-in default sync is executed: gElements and the document must contain the same number of elements in the same order.

The script can also implement a custom sync. Using the function elementlist::get_area_built_elements you can get all products and frames contained in the element in the document. The obtained list can test by the script against the list gElements. The result of the test is set into the variable gState:

    *gState=...;

Important: Set gPrivateSync to one if you want to use the result of the your own sync methode:

    *gPrivateSync=1;

please check the the sync variables against 0 always before use, for instance:

    if (gPrivateSync) *gPrivateSync=1;

Complete example from comet artwork. Select all artworks available for a given artist. At the end of the script we demonstrate the usage of the sync data, but the script always returns the the sync state 'Deleted'.

#include  "internal/types.h"

int wframes (ItemList li)
{
         int		i, j, first = 1;
         ItemRef	fr 	= item::alloc ();
         ItemRef	frj	= item::alloc ();
         ItemList	sub;

         for (i = 0; i < itemlist::length (li); i++)
         {
             itemlist::get (li, fr, i);

             // The element can be an InDesign group.
             // Otherwise, the subloop can also be omitted.
             // 
             sub = itemlist::subframes (fr);
             for (j = 0; j < itemlist::length (sub); j++)
             {
                 itemlist::get (sub, frj, j);
                 if (!first)  	wlog ("", ", ");
                 else		wlog ("", "\t");
                 wlog ("", "%d", item::getint (frj));
                 first = 0;
             }
             itemlist::release (sub);
         }
         wlog ("", "\n");

         item::release (fr);
         item::release (frj);

         return 0;
}

int main ()
{
         Query 		qu 	= sql::query (sql::dbconnection ());
         int			i, id1, id2, id3, classid, templateid;
         String		sid	= string::alloc ();
         String		fmt	= string::alloc ();
         Element		e;
         ElementList	built;

         // Get artworks from database
         query::send (qu, "select ?, ?, id, \"\", 3, 1, \"type=area;post=autoload\"");
         query::send (qu, " from artworks where artistid = ?");

         query::input (qu, kInt, 		gRecordID);
         query::input (qu, kInt, 		gRecordID2);
         query::input (qu, kInt, 		gRecordID2);

         query::output (qu, kInt, 		&id1);
         query::output (qu, kInt, 		&id2);
         query::output (qu, kInt, 		&id3);
         query::output (qu, kString, 	sid);
         query::output (qu, kInt, 		&classid);
         query::output (qu, kInt, 		&templateid);
         query::output (qu, kString, 	fmt);

         query::exec (qu);

         while (query::fetch (qu))
         {
             wlog ("", "%d %d %d '%s' %d %d %s\n", id1, id2, id3, sid, classid, templateid, fmt);

             e = element::alloc (id1, id2, id3, sid);
             element::set_classid (e, classid);
             element::set_templateid (e, templateid);
             element::set_formatstring (e, fmt);

             elementlist::append (gElements, e);
         }

         query::close (qu);

         // Get artworks from document in case of syncs only
         if (gPrivateSync)
         {
             built = elementlist::alloc ();
             elementlist::get_area_built_elements (gFrame, built);
             for (i = 0; i < elementlist::length (built); i++)
             {
             	e = elementlist::get (built, i);
             	wlog ("", "%d	[%d %d %d] with template %d of parent frame %d (order no %d)\n",
             		i,
         		element::id (e),
         		element::id2 (e),
         		element::id3 (e),
         		element::templateid (e),
         		item::getint (element::masterframe (e)),
         		element::ordernumber (e));
         	wframes (element::frames (e));
             }

             *gPrivateSync		= 1;
             if (elementlist::length (gElements) == elementlist::length (built)) *gState = 1;
             else *gState = -1;

             string::set (gNewValue, "Artworks from DATABASE: %d", elementlist::length (gElements));
             string::set (gOldValue, "Already installed: %d", elementlist::length (built));

             elementlist::release (built);
         }

         return 0;
}

To set up a placeholder for repeated elements the following steps must be completed :

1. Set up a placeholder.

    -- data base
   insert into placeholder (..., RelatedToID, ...) values (..., 6, ...)
   

    -- XML, SOAP
   In the file placeholder.xml a new entry is set up.
   
   :
   <type>multi frames</type>
   :

2. Insert the ID (for example 301) for the action, which are to be completed for the generation of the elements.

    -- database
   update placeholder set CharacterStyleID = 301 where ID = ...
   

    -- XML, SOAP
   Ändern der Datei placeholder.xml.
   
   :
   <style>301</style>
   :

3. Set up the action with the corresponding ID

    -- Datenbank
   insert into actions (ID, ...) values (301)
   

    -- XML, SOAP
   Set up the new entry in actions.xml.
   
   :
   <id>301</id>
   :

4. Implementation of the action. Open the panel Placeholder Options, in the edit field Script: fill in the the action ID in the (301), press the button alongside the field and write the action as described above.

[Since Comet 3.1 R1864, 7. Mai 2010] In the of the priint:comet plugins, the name of an object can be displayed in various panels:

• In the middle part of the panel Placeholder Options above the IDs of the linked object
       
  
  
• When items from the ToDo panel are grouped to products
      
  
  

An objects name can be calculated by the placeholder via the data pool. For this an action is defined in actions, which can determine the name of the object by a given object ID. In the placeholder definition, the id of this action is specified in the following field:

You may implement the action as select or as a script. A select must return exactly one result column (the object name). In the script, you pass the object name of the globally defined variable gObjectName. It can be up to 7999 characters long. gObjectName may not be released! The following table contains all the global variables defined in the object name script:

If you have the object name computed by a script you should be careful that the script does not make any changes in the document

The example shows an XMLQuery for loading a product name

"$DATAFILE"
xmlget titel || "TODO-TITEL"
    node books.productgroup
    where productgroupID = <ID2>
    node bookwhere bookID = <ID>

And here'a a very simple simple script to calculate an objects name.

int main ()
{
    sprintf (gObjectName, "ObjectName [%d, %d, %d, \"%s\"]",
        gRecordID,
        gRecordID2,
        gRecordID3,
        gRecordStringID);
    return 0;
}

static int define(
  ItemRef frameRef,
  int plid,
  int id,
  int id2 = 0,
  int id3 = 0,
  char* sid = "",
  int startPos = -1,
  int len = 0)

Connect a frame with a placeholder and link the placeholder with an object. The placeholders content is NOT loaded by define. Please use load to load content.

The function checks whether the requested placeholder exists on the current datapool and has an appropriate type (frame placeholder for frames, text placeholder for text).

Name	Type	Default	Description
Return	int		0 or ErrorCode
frameRef	ItemRef	-	Valid frame reference 0 : Current script frame or script text
plid	int	-	ID of placeholder 0 : empty placeholder -2 : remove placeholder. Text-placeholders from the beginning to the end of the given text range are removed completely. If you removing a frame placeholder, the ID of a possible linked object is left untouched. To remove links to objects, call placeholder::link with an id of 0 (or -2), 0, 0, "" BEFORE executing placeholder::define. -3 : (text placeholder only) Remove placeholders exactly at the given range otherwise : id of a placeholder with matching type (see here)
id	int	-	ID of the object to link
id2	int	0	ID2 of the object to link
id3	int	0	ID3 of the object to link
sid	String or char*	""	StringID of the object to link. To learn more about StringIDs.
startPos	int	-1	Textposition of placeholder start. -1 Change the placeholder of the frame (and not text placeholders)
len	int	0	Length of text to work on. since R1112, 5. January 2009 A given length of -1 will set the placeholder until the end of the text in normal text. In tables the placeholder is defined until the end of the current table cell.

Preconditions

#include "internal/text.h"

#include "internal/types.h"
#include "internal/text.h"

int main ()
{
    placeholder::define (gFrame, -2, 0);
    placeholder::define (gFrame, -2, 0, 0, 0, "", 0, kEnd);

    return 0;
}

The following example changes all unknown placeholders in the Comet Group of a frame.

#include "internal/types.h"

int relink (Link lk, int pid, IDTypeList infos)
{
    int 		result 		= 1;
    int 		pos;
    IDType 		info;
    String 		label		= string::alloc ();
    String 		title		= string::alloc ();
    String 		dialogSpec	= string::alloc ();
    String 		v			= string::alloc ();
    int 		newID;

    while (1)
    {
        if (pid <= 0)
        {
            result = 0;
            break;
        }

        pos = idtypelist::find (infos, pid);
        if (pos >= 0)
        {
            // This placeholder ID has already been found and edited.
            // We'll do the same now.
            //
            info 	= idtypelist::get (infos, pos);
            newID 	= idtype::id2 (info);
        }
        else
        {
            // Ask for the new placeholder id.
            //
            string::set (v, "%d", pid);
            if (link::pos (lk) >= 0)	
            {
                string::set (title, "Replace Text Placeholder %d", pid);
                string::set (label, "TEXT %d [%d, %d] : New Text Placeholder", item::getint (link::frame (lk)), link::pos (lk), link::pos (lk)+link::length (lk));
                textmodel::select (link::frame (lk), link::pos (lk), link::length (lk));
            }
            else
            {
                string::set (title, "Replace Frame Placeholder %d", pid);
                string::set (label, "FRAME %d : New Frame Placeholder", item::getint (link::frame (lk)));
                frame::select (link::frame (lk));
            }

            if (!askstring (v, label, title, "Replace", 0, 0)) 
            {
                result = -1199;
                break;
            }
            if (string::length (v) == 0) break;
            newID = string::to_int (v);
            if (newID <= 0) break;

            idtypelist::append (infos, pid, newID, 0, "");
        }

        if (newID > 0)
        {
            result = placeholder::define (
             		link::frame (lk),
             		newID,
             		link::id (lk),
             		link::id2 (lk),
             		link::id3 (lk),
             		link::sid (lk),
             		link::pos (lk),
             		link::length (lk));
        }
        else
        {
            result = 0;
        }

        break;
    }
    string::release (title);
    string::release (label);
    string::release (dialogSpec);
    string::release (v);

    return result;
}

int main ()
{
    int 		cid			= frame::get_cometgroup(gFrame);
    ItemList 	M 			= itemlist::get_cometgroup_members (0, cid, 1);
    LinkList	lli			= linklist::alloc ();
    Link		lk;
    int 		pid;
    DBC			dbc			= sql::connection ();
    XMLTree		tree;
    Query 		qu;
    IDTypeList 	pids 		= idtypelist::alloc ();
    IDTypeList 	new_pids 	= idtypelist::alloc ();
    int 		pos;
    int 		result;

    // Sanity check
    //
    if (gRun > 1)	return 0;
    if (!itemlist::length (M))
    {
        showmessage ("No frame selected or the frame is not in a Comet Group.");
        return 0;
    }

    // Get all defined placeholders of the data pool
    //
    if (dbc)
    {
        qu = sql::query (dbc);
        query::send (qu, "select ID from placeholder where ID > 0");
        query::output (qu, kInt, &pid);
        query::exec (qu);
        while (query::fetch (qu))
        {
            idtypelist::append (pids, pid, 0, 0, "");
        }
        query::close (qu);
    }
    else
    {
        tree = xmlquery::open ("placeholder.xml", 0, 1);
        xmlquery::send (tree, "select id node metadata.placeholder where id > 0");
        xmlquery::output (tree, kInt, &pid);
        xmlquery::exec (tree);
        while (xmlquery::fetch (tree))
        {
            idtypelist::append (pids, pid, 0, 0, "");
        }
        xmlquery::close (tree);
    }

    // Collect all placeholders used in the
    // Comet Group of gFrame
    //
    linklist::collect_any (lli, M, "--list--");

    // Walk through all placeholders
    //
    for (lk = linklist::first (lli); lk != 0; lk = linklist::next (lli))
    {
        pid = link::placeholderid (lk);
        if (idtypelist::find (pids, pid) < 0)
        {
            result = relink (lk, pid, new_pids);
            if (result)
            {
                if (result == 1)	beep ();
                else if (result != -1199)
                {	
                    showmessage ("Error %d while replacing placeholder %d\n\n%s", result, pid, serror (result));
                }
                break;
            }
        }
    }

    // Clean up
    //
    linklist::release (lli);
    itemlist::release (M);
    idtypelist::release (pids);
    idtypelist::release (new_pids);

    return 0;
}

Since

sid since Version 1.3 (Build 96)
startPos and len since Version 2.1, R 1014 ,1. Nov. 2008

Available

priint:comet InDesign^® Plug-Ins, Illustrator

See Also

item
comet.placeholder.set

static int link(
  ItemRef placedItem,
  int classid,
  int id,
  int id2 = 0,
  int id3 = 0,
  int textStart = -1,
  int textLen = -1,
  char* sid = "",
  int doLoad = 0,
  int applyRules = 0,
  int changeStatics = 0)

Link all placeholders of given classID of a frame and all its subframes with the given object.

Name	Type	Default	Description
Return	int		0 or ErrorCode
placedItem	ItemRef	-	Frame. When the value is empty (=0), the call attempts to use the text model or the frame of the script.
classid	int	-	Class ID issued by Werk II Only those placeholders of the ID object are loaded, which are contained in in the classid. When the value is 0 all placeholders will be loaded.
id	int	-	ID of the database object
id2	int	0	ID2 of the database object
id3	int	0	ID3 of the database object
textStart	int	-1	Start position in text >=0 : Start working at the given text position. textLen must be > 0 in this case. -1 : Link all text and frame placeholders -2 : Link only the frame placeholder since Version 3.2 R2267, 7. Feb. 2011
textLen	int	-1	Length of the text, the placeholders of which are to be changed.
sid	String or char*	""	StringID of the connected database object. A product is only then detected when all 3 IDs and the string ID conform with one another. If no string IDs are used the value is specified with "".
doLoad	int	0	Load placeholders right after linking?? 0 : No 1 : Yes. Like placeholder::load with placeholder = 0 and recordids = 0 directly after calling placeholder::link. The only difference is that tables inserted by table placeholders are linked and loaded correctly.
applyRules	int	0	since Version 3.1, R1550 Apply layoutrules "After load" () after successful execution on text ranges too? 0 : No 1 : Yes
changeStatics	int	0	Can change static product links too? 0 : No 1 : Yes

int main ()
{
    ItemList			masters	= itemlist::selected ();

    itemlist::apply (placeholder::link, masters, 1, 0, 3, 1, 0, 0, -1, -1, "116507", 1, 1);

    return 0;
}

Since

Parameter doLoad und applyRules ab v3.3 R3042, 6. Sept. 2012
Parameter changeStatics since v4.0.5 R14200, 9. Dec 2016

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

item
textmodel::restore
link2
comet.placeholder.link
comet.CFrame.link

static int link2(
  ItemRef placedItem,
  int classid,
  int id,
  int id2 = 0,
  int id3 = 0,
  char* sid = "",
  int textStart = -1,
  int textLen = -1,
  int doLoad = 0,
  int applyRules = 0,
  int changeStatics = 0)

Same as link, but another sequence of the IDs. The string ID argument directly follows the three integer IDs.

Name	Type	Default	Description
Return	int		0 or ErrorCode
placedItem	ItemRef	-	Frame. When the value is empty (=0), the call attempts to use the text model or the frame of the script.
classid	int	-	Class ID issued by Werk II Only those placeholders of the ID object are loaded, which are contained in in the classid. When the value is 0 all placeholders will be loaded.
id	int	-	ID of the database object
id2	int	0	ID2 of the database object
id3	int	0	ID3 of the database object
sid	String or char*	""	StringID of the connected database object. A product is only then detected when all 3 IDs and the string ID conform with one another. If no string IDs are used the value is specified with "".
textStart	int	-1	Start position in text >=0 : Start working at the given text position. textLen must be > 0 in this case. -1 : Link all text and frame placeholders -2 : Link only the frame placeholder since Version 3.2 R2267, 7. Feb. 2011
textLen	int	-1	Length of the text, the placeholders of which are to be changed.
doLoad	int	0	Load placeholders right after linking?? 0 : No 1 : Yes. Like placeholder::load with placeholder = 0 and recordids = 0 directly after calling placeholder::link. The only differnce is that tables inserted by table placeholders are linked and loaded correctly.
applyRules	int	0	since Version 3.1, R1550 Apply layoutrules "After load" () after successful execution on text ranges too? 0 : No 1 : Yes
changeStatics	int	0	Can change static product links too? 0 : No 1 : Yes

int main ()
{
    ItemList			masters	= itemlist::selected ();

    itemlist::apply (placeholder::link2, masters, 1, 0, 3, 1, 0, 0, "116507", -1, -1, 1, 1);

    return 0;
}

Since

Parameter doLoad und applyRules ab v3.3 R3042, 6. Sept. 2012
Parameter changeStatics since v4.0.5 R14200, 9. Dec 2016

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

item
textmodel::restore
link
comet.placeholder.link

static int change_tags(
  ItemRef placedItem,
  int classid,
  char* info,
  int value,
  int dest = 3,
  int startPos = 0,
  int len = -1,
  int updateActions = 0,
  int takeCareOnMe = 0)

In a specified frame all the found placeholders will be changed. The following table details the Placeholder Options which can be changed. The specifications are (in opposite to the tagnames) case insensitive.

Name	Typ	Remarks
Placeholder, Placeholder	int	The associated placeholder definition should be in existance and be of the correct type (see RelatedTo).
ID		Objekt-ID, comprised of three numbers and a string.
ID2
ID3
STRINGID STRINGID1, STRINGID2, STRINGID3	char*
Class	int	Class ID of the object, which can be linked with this placeholder.
Select		IDs of the actions which can be executed from the placeholders. ObjectNameID since version 3.1 R1880, 7. May 2010
Sync
Update
Lov
ObjectNameID
RelatedTo		Type of the placeholder    0 : Undefined    1 : text    2 : textframe    3 : imageframe    4 : xmlelement    5 : Document action    6 : multi frames (Repeated Element)    7 : multi text (Repeated Text)    8 : table    9 : crossref    10 : serialtext    11 : serialframe    12 : serialpageitem    -2000 : Excel-supported table (Plugin XCell)
Color		ID of a color. The color is used to present the placeholder in the placeholder panel and in the document.
SyncStateInvisible		Can the placeholder display a status (see get_sync) or not?    0 : do not show    1 : Status can be shown
LoadConstraint		Unused. Following values are foreseen:    0 : Undefiniert    1 : always ask    2 : ask once    3 : never ask
Format		For repeating elements the ID of the action is specified here, which is to be executed if the elements are to be set up. Otherwise this field remains unused.
Group		Group ID of a placeholder frame. The group ID is allocated for Document build, so that frames are located on the same grid locations even though these are not grouped in InDesign®.
Name	char*	For Excel-supported tables contains the path of the associated Excel table. Relative paths are determined depending on the document.
Table		Check sum, do NOT change!
Created		Date information in the format YYYYMMDDHHMMSS
Modified
Grid	int	Deprecated
GridElement
PreRule
PostRule
PreRuleParams	char*
PostRuleParams
AdParams
Infos1	char*	Additional information to the placeholder. The specifications are limited to 4000 characters. If the specification is longer than 4000 characters, the empty string is used. Infos2 can additionally be used to display a text label on the placeholder. The label is shown only in frame placeholders! Here is a screenshot: Labels must start with the key msg_Color. The following colors are supported: red, comet, orange, yellow , blue. Then the text to be displayed follows. The text shown in the screenshot is generated by the Infos2 text msg_comet Das ist mir eine Last, 2,3,4.
Infos2
SequenceNr	int	Sequence in which the template is to be inserted in the frame. If no sequence number is given (0), the frames are loaded in a sequence defined in InDesign®. The specification only has significance for the insert of templates which are comprised of several frames. Use the same sequence for the script which is to be executed following the insert (PostScript).
PostScript		Following the insert of the frame using a template, the post-processing procedure can be executed. The ID gives the number of the action which is to be executed. The action frame postscripts must have the class ID 16. If a template is comprised of several frames, the sequence of the execution can be defined using sequence number.
ShowPostScript		If the sequence number and the postscript ID in the document is to be displayed. The display is only made, if the placeholders are also displayed.
TextflowType	int	How to use the frame in case of a text flow? 0 : Insert text content 1 : Insert as inline 2 : Do not insert
TextflowOnly		If the frame is part of a template, this value controls, how to deal with the frame in normal (drag'n drop, build products, ...) template inserts. 0 : Take this frame to the document 1 : Do not insert this frame into the document unless a text flow build is running.
TextflowUsage		Internal, do not change!
AdaptSequ		Internal, do not change!
AdaptGroup	char*	Internal, do not change!
PageitemID	int	Id of template, which inserted me. Template-ID vs. Product template ID Imagine, you inserted a product using template 100 and the templates creates the three frames 1, 2, and 3. Frame 2 creates two additional frame (4 and 5) using document::place_items with template ID ID 300. Until v3.2.3 the inserted frames having the following template IDs : Frame 1 : 100 Frame 2 : 100 Frame 3 : 100 Frame 4 : 300 Frame 5 : 300 The template ID is not unique and reorganizing the document may fail, because the process may use the wrong template ID 300. Thats why since v3.3 all frames of a product will get the (unique) product template ID : Frame 1 : 100 Frame 2 : 100 Frame 3 : 100 Frame 4 : 100 Frame 5 : 100 Using PageitemDirectID (available since v3.3 R2701) you can refer to the ID of template which created the frame.
PageitemDirectID	int	Since v3.3 R2701 ID of triggering template, see PageitemID.
OrgPageitemID	int	Since v3.3.1 R3212 A \URL[TemplateID script]{../InDesign/Plugins/pageitems.html#Vorlagenskript) has changed the template. This is in memoriam of the original template (used only for products build by the product build process).
SmartInfo	char*	Template behavior releated infos. You may change this string, but take care about its syntax. The parts of the string are delimited by single white spaces. Wrong smart infos may crash your InDesign® or destroy documents. Do not append any own data to the string. The string is subject to change by Werk II. Please use Infos1 and Infos2 for your own data. See frame::get_smart_item_data and frame::set_smart_item_data for additional information. Type               Description String Frame label, one character only. int [0-23] Color-ID int [0-6] Type of frame 0 : undefined 1 : left 2 : right 3 : continuation left 4 : continuation right 5 : spread 6 : continuation spread int [0-3] Continuation type 0 : normal 1 : continue frame (triangle) 2 : repetition (unused) 3 : continue frame with fixed height (empty triangle) String Internal ID. Do not change! int Flags (bit field) 0x00000001 : Load frame placeholders 0x00000002 : Load text placeholders int [0-3] Area type 0 : Bounding Box 1 : Path (Star) 2 : Path with holes (empty star) 3 : ignore (Minus)
ObjectNameID	int	ID of action to retreive the objects name
BuiltByID, BuiltByID2, BuiltByID3, BuiltByStringID	int, int, int, char*	ID of product built this frame
BuildRemains	int	Since v4.1.6 R26360 Number of elements that could not be inserted because the repeating frame is full, see here for more information.
Chapter	int	[unused] Chapter id
ChapterRule	int	[unused] 0 : new left page, 1 : new page, 2 : new right page
HeightFromTemplate	char*	Original height from the templates. Use fval to get a float.
OriginBBox	char*	Original bbox of frame from the template. Blank delimited string of four floats. Use string::get_token_count, string__get_token and string::to_float to get the floats.
Prefix[+Apply] Postfix[+Apply]	char*	Text to insert into the document before/behind the placeholder, if the placeholder is not empty. Pre- and postfixes are applied only when the placeholder is reloaded. With the +Apply specification the text is applied immediately (and without reloading).
PrefixIfEmpty[+Apply] PostfixIfEmpty[+Apply]	char*	Text to insert into the document before/behind the placeholder, if the placeholder is empty. Pre- and postfixes are applied only when the placeholder is reloaded. With the +Apply specification the text is applied immediately (and without reloading).
Continue	int	Unique id (0, 1, 2, ...) of the continuing template the frame belongs to.
PageBreakID	int	since v3.3 R2718, 17.11.2011 New chapter-ID. This ID is shown in left top corner of the Comet groups and is used for page breaks in document reorganizings. All products with the same (or an empty) chapter ID are containing to the same chapter. Every change of the chapter ID forces a page break. Page template and page type are read from PageBreakTemplateID and PageBreakType. Set the chapter ID in all frames of a Comet group. By default we use page UIDs as to be chapter IDs, but you may use any unique number here. Good candidates may be the Comet group ID or the UID of a frame of the list. Example :     itemlist::apply (placeholder::change_tags, frames, 1, 0, 0, "PageBreakID", groupID, kFramePlaceholder);
PageBreakTemplateID		seit v3.3 R2718, 17.11.2011 Page template applied to the new page. You may use same page template as in the previous chapter.
PageBreakType		since v3.3 R2718, 17.11.2011 0 : new left page 1 : new page 2 : new right page
PageBreakLayers	char*	since v3.3 R2718, 17.11.2011 Layout layers for the chapter. Include all layers into double quotas and use single blanks as delimiters. The given layers must not exist in the document. Use the following definitions for variable layers : "ab++#--background" : All layers behind the current "ab++#--except layerName" : All layers except layerName "ab++#--behind layerName" : All layers behind layerName Example "\"aaa\" \"bbb\" \"ab++#--background\""
RepetitionParent	int	UID of repetition parent. If the frame was not created as a repetition child, the value is 0. Use item::define to define a valid ItemRef from this value. The value is NOT defined in the repetitions 'post' script. Use gFrame in the 'post' script instead.
LayoutRules	char*	String for defining the layout rules. You can find more information here.
StaticLink	int	Static product link property of placeholder
BuildUsage	int	How should the frame be used in text flow builds? 0 : Insert content 1 : Insert frame as inline 2 : Do not use See here for more information.
FunctionVariables	char*	Function Variables, see here
HashValues	char*	Fixed contents of the placeholder, see here.

Name	Type	Default	Description
Return	int		0 or ErrorCode
placedItem	ItemRef	-	Frames
classid	int	-	Only process placeholders of this class or 0
info	string	-	Which information of the tag is to be changed ? See above Table Placeholder Options
value	int/String or char*	-	new value. The data type must correspond to the above table. You can also use String when the data type in the table is char*.
dest	int	kAnyPlaceholder	Change only this type of placeholders : kFramePlaceholder frame placeholder kTextPlaceholder Placeholders in the text. If the text contains inlines frames, the placeholders of this frames are changed too. kAnyPlaceholder Change all placeholders
startPos	int	0	Start changing placeholder at this text position. If dest = kFramePlaceholder this value is ignored.
len	int	kEnd	Length of text to change, If dest = kFramePlaceholder this value is ignored.
updateActions	int	0	Load action and color IDs in case of placeholder ID changes (info = "Placeholder" or "Platzhalter") 0 : No otherwise : Yes, try to update load, store, sync, list of values and color IDs [since v4.2 R33300] In addition, the 'relatedTo' property of the placeholder is also aupdated.
takeCareOnMe	int	0	In load actions the changes made by this call may effect the current placeholder too. Shall I change this placeholder or not? 0 : nein 1 : ja

Preconditions

#include "internal/text.h"
#include "internal/types.h"

char	dt[256];

placeholder::change_tags (placedItem,
 	0,
 	"Modified",
 	system::now (dt, kShortDateLongTime));

Get, change and get agian some placeholder vaues. The current text selection should be inside a text placeholder while executing the script. Don't forget to copy the results of multiple sget_value calls to local variables.

#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    Table		T			= table::alloc ();
    ItemRef 	frame		= item::alloc();
    List		cols		= list::alloc ();
    int 		start, len, l, t, r, b;
    int			pstart, plen;
    char		stringid	[2000];
    char		infos1	[2000];
    int			placeholderID;

    textmodel::selection (&start, &len, frame, 0, T, &l, &t, &r, &b);
    if (start < 0)		return 0;

    // read values
    placeholderID	= placeholder::get_value (gFrame, "Placeholder", start, &pstart, &plen);
    strcpy (stringid, placeholder::sget_value (gFrame, "STRINGID", start));
    strcpy (infos1, placeholder::sget_value (gFrame, "Infos1", start));
    wlog ("", "Placeholder %d (before) [%d, %d]\n", placeholderID, pstart, pstart+plen);
    wlog ("", "\tStringID\t: '%s'\n", stringid);
    wlog ("", "\tInfos1\t: '%s'\n", infos1);

    // change values
    placeholder::change_tags (gFrame, 0, "STRINGID", "stringid changed", kTextPlaceholder, start, len);
    placeholder::change_tags (gFrame, 0, "Infos1", "info changed", kTextPlaceholder, start, len);

    // re-read values
    strcpy (stringid, placeholder::sget_value (gFrame, "STRINGID", start));
    strcpy (infos1, placeholder::sget_value (gFrame, "Infos1", start));
    wlog ("", "Placeholder %d (after) [%d, %d]\n", placeholderID, pstart, pstart+plen);
    wlog ("", "\tStringID\t: '%s'\n", stringid);
    wlog ("", "\tInfos1\t: '%s'\n", infos1);

    return 0;
}

Since

Parameter dest since version 1.4 (R334), 13. April 2007 Parameter startPos and len since version 1.4 (R472), 13. Juni 2007 Parameter updateActions since sersion 2.1 (R1760), 19. Feb. 2010

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

item
placeholder::get_value
comet.placeholder.setTagValue

static int get_value(
  ItemRef itemRef,
  char* info,
  int textIndex = -1,
  int* startPos = 0,
  int* len = 0)

If a frame is linked with a placeholder, the value of the specified slots is ascertained. Value <0 signalises an error, e.g. the frame does not have a placeholder or the reference is no frame. If textIndex is greater than -1, itemRef must point to a text frame. We are looking for a placeholder at the given text index, and, on success, we will return the requested value.

Name	Type	Default	Description
Return	int		Value of the placeholder slots. Only those values are ascertained, which are specified in the table Placeholder Options as int values. For string values see sget_value.
itemRef	ItemRef	-	Frames
info	String or char*	-	What information of the placeholder is to be ascertained? See above Table Placeholder Options. With this function, only int slot values can be determined.
textIndex	int	-1	text position <0 :check frame otherwise : Check text at the given position. itemRef must point to a valid text frame in this case.
startPos	int*	0	if the text is linked with a placeholder at the given text index, it contains the start index of the placeholder.
len	int*	0	if the text is linked with a placeholder at the given text index, it contains the length of the placeholder.

Preconditions

#include "internal/text.h"
#include "internal/types.h"

Get, change and get again some placeholder vaues. The current text selection should be inside a text placeholder while executing the script. Don't forget to copy the results of multiple sget_value calls to local variables.

#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    Table		T			= table::alloc ();
    ItemRef 	frame		= item::alloc();
    List		cols		= list::alloc ();
    int 		start, len, l, t, r, b;
    int			pstart, plen;
    char		stringid	[2000];
    char		infos1		[2000];
    int			placeholderID;

    textmodel::selection (&start, &len, frame, 0, T, &l, &t, &r, &b);
    if (start < 0)		return 0;

    // read values
    placeholderID	= placeholder::get_value (gFrame, "Placeholder", start, &pstart, &plen);
    strcpy (stringid, placeholder::sget_value (gFrame, "STRINGID", start));
    strcpy (infos1, placeholder::sget_value (gFrame, "Infos1", start));
    wlog ("", "Placeholder %d (before) [%d, %d]\n", placeholderID, pstart, pstart+plen);
    wlog ("", "\tStringID\t: '%s'\n", stringid);
    wlog ("", "\tInfos1\t: '%s'\n", infos1);

    // change values
    placeholder::change_tags (gFrame, 0, "STRINGID", "stringid changed", kTextPlaceholder, start, len);
    placeholder::change_tags (gFrame, 0, "Infos1", "info changed", kTextPlaceholder, start, len);

    // re-read values
    strcpy (stringid, placeholder::sget_value (gFrame, "STRINGID", start));
    strcpy (infos1, placeholder::sget_value (gFrame, "Infos1", start));
    wlog ("", "Placeholder %d (after) [%d, %d]\n", placeholderID, pstart, pstart+plen);
    wlog ("", "\tStringID\t: '%s'\n", stringid);
    wlog ("", "\tInfos1\t: '%s'\n", infos1);

    return 0;
}

Since

textIndex, startPos, len since version 2.1 R 811, 7.7.2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

item
placeholder::change_tags
sget_value
textmodel::get_placeholder
comet.placeholder.getTagValue

static char* sget_value(
  ItemRef itemRef,
  char* info,
  int textIndex = -1,
  int* startPos = 0,
  int* len = 0)

If a frame is linked to a placeholder, the value of the specified slot will be ascertained. If textIndex is greater than -1, itemRef must point to a text frame. We are looking for a placeholder at the given text index, and, on success, we will return the requested value.

Name	Type	Default	Description
Return	char*		0 : Error Otherwise : Value of the placeholder slot. Only those values are ascertained, which are specified in the Table Placeholder Options as char* values. For integer values see get_value. The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.
itemRef	ItemRef	-	Frames
info	char*	-	Which information of the placeholder are to be ascertained ? See above Table Placeholder Options With this function, only the string slot values can be ascertained.
textIndex	int	-1	text position <0 :check frame otherwise : Check text at the given position. itemRef must point to a valid text frame in this case.
startPos	int*	0	if the text is linked with a placeholder at the given text index, it contains the start index of the placeholder.
len	int*	0	if the text is linked with a placeholder at the given text index, it contains the length of the placeholder.

Preconditions

#include "internal/text.h"
#include "internal/types.h"

Get, change and get agian some placeholder vaues. The current text selection should be inside a text placeholder while executing the script. Don't forget to copy the results of multiple sget_value calls to local variables.

#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    Table		T			= table::alloc ();
    ItemRef 	frame		= item::alloc();
    List		cols		= list::alloc ();
    int 		start, len, l, t, r, b;
    int			pstart, plen;
    char		stringid	[2000];
    char		infos1		[2000];
    int			placeholderID;

    textmodel::selection (&start, &len, frame, 0, T, &l, &t, &r, &b);
    if (start < 0)		return 0;

    // read values
    placeholderID	= placeholder::get_value (gFrame, "Placeholder", start, &pstart, &plen);
    strcpy (stringid, placeholder::sget_value (gFrame, "STRINGID", start));
    strcpy (infos1, placeholder::sget_value (gFrame, "Infos1", start));
    wlog ("", "Placeholder %d (before) [%d, %d]\n", placeholderID, pstart, pstart+plen);
    wlog ("", "\tStringID\t: '%s'\n", stringid);
    wlog ("", "\tInfos1\t: '%s'\n", infos1);

    // change values
    placeholder::change_tags (gFrame, 0, "STRINGID", "stringid changed", kTextPlaceholder, start, len);
    placeholder::change_tags (gFrame, 0, "Infos1", "info changed", kTextPlaceholder, start, len);

    // re-read values
    strcpy (stringid, placeholder::sget_value (gFrame, "STRINGID", start));
    strcpy (infos1, placeholder::sget_value (gFrame, "Infos1", start));
    wlog ("", "Placeholder %d (after) [%d, %d]\n", placeholderID, pstart, pstart+plen);
    wlog ("", "\tStringID\t: '%s'\n", stringid);
    wlog ("", "\tInfos1\t: '%s'\n", infos1);

    return 0;
}

Since

textIndex, startPos, len since version 2.1 R 811, 7.7.2008

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

item
placeholder::change_tags
get_value
textmodel::gt_placeholder
comet.placeholder.getTagValue

static int can_create_items(ItemRef frameRef)

Is a frame linked with a placeholder and does this placeholder contain a Build Action?

Name	Type	Default	Description
Return	int		Does the frame contain a placeholder, which can contain sub-entries?
frameRef	ItemRef	-	Frame

@itemable = placeholder::can_create_items (item);

Since

Available

priint:comet InDesign^® Plug-Ins

static int update_link_states(int classid = 0)

Update the link button in the panel. In order to completely re-load the data components of a panel, you can use the command list::reload.

Name	Type	Default	Description
Return	int		0 or ErrorCode
classid	int	-	panel numbers defined by Werk II 0 - Update all opened panels

err_code = placeholder::updade_link_states (1);

Since

Available

priint:comet InDesign^® Plug-Ins

See Also

list::reload

static int prepare_statement(int classid = 0)

Replace all <tags> of the statement by their current values of the given placeholder.

Name	Type	Default	Description
Return	int		0 or ErrorCode
frameRef	ItemRef	-	Valid frame reference 0 : Current script frame
textStart	int	-	Text position >=0 : Use text placeholder at the given text position < 0 : Use frame placeholder
stmt	String oder char*	-	Statement whose <tags> are to be replaced. The replacements are made directly in the input string. So the parameter must be a variable (and not a fixed value) in any case! ATTENTION : When using char*, the variable must be allocated large enough to hold the result!
int	actionType	-	The specification is only necessary for the replacement of the function variables of the placeholder: kLoadAction (1) kWriteAction (2) kSyncAction (3) kBuildAction (4)
int	maxLen	-1	Maximum length of the result in the parameter stmt. The specification has a meaning only for stmt of type char*. -1 : Any length (Or in other words : I am sure that my char* variable has enough space.)

Preconditions

#include "internal/types.h"

Since

v4.2 R30123, 2. March 2022

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int load(
  ItemRef frameRef,
  int classid = 0,
  int textStart = -1,
  int textLen = -1,
  int applyRules = 0,
  List placeholders = 0,
  IDTypeList recordIDs = 0)

Load all Placeholders of a frame or text incl. its sub-objects. The selection of placeholders can optionally be limited to a specific class. The command fulfills that which is triggered by the linking of a frame by clicking on an object from the object list of the class (e.g. the list of the products) following the setting of the IDs by the activated green arrow bottom right in the window.All the placeholders with the specified classshrubs ID are newly loaded with the specified object in the whole text and the text of all inline frames and all sub-frames.

Name	Type	Default	Description
Return	int		0 or ErrorCode
placeItem	ItemRef	-	Frame. If the specification is empty (=0), an attempt is made to use the text model or the frame of the script.
classid	int	0	Class ID defined by Werk II. Only those placeholders of the ID object are loaded are used which contain the specified class ID. When specifying 0 all placeholders are loaded.
textStart	int	-1	Start position in text >=0 : Start working at the given text position. textLen must be > 0 in this case. -1 : Load all text and frame placeholders -2 : Load only the frame placeholder since Version 3.2 R2267, 7. Feb. 2011
textLen	int	-1	Length of the text the placeholder of which are to be changed.
applyRules	int	0	since Version 3.1, R1550 Apply layoutrules "After load" () after successful execution on text ranges too? 0 : No 1 : Yes
placeholders	List	0	List of placeholder ids. If given, the function only loads this placeholders
recordids	IDTypeList	0	List of object ids. If given, the function only loads placeholders linked againts this objects.

In order to link a frame (and its sub-objects) and to load it, the following sequence is required:

placeholder::link (item, 1, 4, 2, 2);
placeholder::load (item, 1);

Since

The automatic access to the text model or frame of the script and the limitation of the text area are possible from Version 1.1.7, January 2005.

Parameter applyRules since version 3.1, R1550, 18. Sept. 2009

placeholders und recordids since version 3.2 R2220, 6. Dec. 2010

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

placeholder::link
comet.placeholder.load
comet.CFrame.load

static int store(
  ItemRef itemRef,
  int classid = 0,
  int textStart = -1,
  int textLen = -1)

Write the data of all placeholders of a frame or text incl. its sub-objects on the database. The selection of the placeholder can optionally be limited to a certain class.In all texts and the texts of all inline frames and all subframes, all placeholders with the specified class ID are written with the specified object.

Name	Type	Default	Description
Return	int		0 or ErrorCode
itemRef	ItemRef	-	Frames. If the specification is empty (=0),it will be attempted to use the text model or the frame of the script.
classid	int	0	Class ID defined by Werk II. Only those placeholders of the ID object are loaded are used which contain the specified class ID. When specifying 0 all placeholders are loaded.
textStart	int	-1	Start position in text >=0 : Start working at the given text position. textLen must be > 0 in this case. -1 : Store all text and frame placeholders -2 : Store only the frame placeholder since Version 3.2 R2267, 7. Feb. 2011
textLen	int	-1	Length of the text the placeholder of which are to be changed.

err_code = placeholder::store (item, 1);

Since

The automatic access to the text model or frame of the script and the limitation of the text area are possible from Version 1.1.7, January 2005.

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

comet.CFrame.store

static int sync(
  LinkList lli,
  LinkList results,
  int doExec = 0,
  ItemRef frameRef = 0)

Ascertain the current value of placeholders in the document. The function is equal to linklist::sync.

Since

v4.0.5 R13178, 16. Sep 2016

static int build(ItemRef itemRef)

Execute the build action of a frame. This action should normally create the repeating elements for this frame. The placeholder of the frame must be:

	Placeholder Type	Skript
XML, SOAP	type = multi frames	styleid > 0
Datenbank	RelatedToID = 6	CharacterStyleID > 0

Name	Type	Default	Description
Return	int		0 or ErrorCode
itemRef	ItemRef	-	Rahmen

Preconditions

#include "internal/text.h"
#include "internal/types.h"

err_code = placeholder::build (item);

Since

Available

priint:comet InDesign^® Plug-Ins

See Also

comet.placeholder.build
comet.CFrame.build

static char* path(ItemRef itemRef, char* path)

Get the path of an image of a graphic frame. The function can return 0.

Name	Type	Default	Description
Return	String or char*		(Depends on parameter path) Complete path of the image file, same as parameter path
itemRef	ItemRef	-	Frame
path	String or char*	-	Reserved memory for the result

The example does not include the 0-test, only image frames may be selected.

int main ()
{
    char s[800];

    showmessage (placeholder::path (gFrame, s));
    return 0;
}

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int sync_definitions(int type = 0)

Update thedefinitions of the placeholders of the entire documentss. When setting the placeholders in the document, the current database definitions of the placeholders are written in the in the document. If the definitions of the database are changed, the corresponding document values cannot automatically be matched. The updating is completed using sync_definitions.

The method can, moreover, be used in order to match the placeholder definitions of the entire document to a new plugin version. This step is recommended for the updating of the Werk II plugins of July 2005 to newer versions. Here is a list of the updates

• Date, since July 2005
• Build rules, from R93
• Infos, from R118
• Sequence numbers from R121

Name	Type	Default	Description
Return	int		0 or ErrorCode
type	int	0	What data is to be changed? 0 : Placeholder value 1 : Initialise date (set/changed) 2 : Initialise build rules 3 : Initialise info 4 : Initialise sequence numbers -1 : Initialise all from date

Since

Version 1.1.6

Available

priint:comet InDesign^® Plug-Ins

static int get_sync()

Get the sync status of the placeholder which has triggered the script.

Name	Type	Default	Description
Return	int		-1199 : Status could not be ascertained Marker State Value Description kLoadError -4 Error during loading kHide -3 Hide marker kNoObject -2 No object kChanged -1 Changed (out of sync) kDeleted 0 Deleted kOkay 1 Okay kNotUnique 2 Object not unique

Preconditions

#include "internal/text.h"
#include "internal/types.h"

Since

Version 1.1.6

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int set_sync(int state)

Change the sync status of the placeholder which has triggered the script. The call only has a effect in scripts which are to be called from the sync and store action of a placeholder.

The placeholders state is set automatically by the script environment normally. If you changed the state inside the script, you have to tell it the environment by setting

   *gSyncChanged = 1;

The environment leaves the placeholder state untouched in this case.

If the script was called as sync script (placeholders with syncID -1, see here), gSyncChanged is handled like in load scripts : If gSyncChanged is set to 1 by the script, the sync state is left untouched by the plug-ins.

The scripts environment expects, that YOU set the placeholders state. If you do not set state, tell it the environment by setting

   *gSyncChanged = 0;

In case the environment sets the state.

Name	Type	Default	Description
Return	int		0 or ErrorCode
value	int	-	new value You need to include "internal/types.h" Error during loading No object Marker State Value Description kLoadError -4 kHide -3 Hide marker kNoObject -2 kChanged -1 Changed (out of sync) kDeleted 0 Deleted kOkay 1 Okay kNotUnique 2 Object not unique

Preconditions

#include "internal/text.h"
#include "internal/types.h"

Since

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

static int replace(
  int placeholderID,
  char* str,
  int maxlen = -1)

Placeholder specific replacements in a string.Placeholder-specific substitutions of the XML results can be defined using the XML configuration file xentities.xml. In sync scripts, in particular, in which the original values of placeholders are compared with those in the InDesign^® document, it is necessary to be able to manually execute the automatically implemented substitutions defined by means of the entities. The command placeholder::replace changes the specified string in such a way as if it was loaded by the placeholder with the specified ID. The string str is changed by means of the call. When the data type is char*, it must be allocated in a sufficiently large size to be able to accommodate for the substitutions.

Name	Type	Default	Description
Return	String or char* (Depends on parameter str)		To facilitate the use of the the passed string str will be used as the return value.
placeholderID	int	-	Placeholder ID
str	String or char*	-	String, in which the in replacements are to be made. When the data type is char*, the variable must have sufficiently large reserved memory in order to accommodate for the replacements.
maxlen	int	-1	maximal length of the result. The parameter is evaluated, if replacements have actually be made in the string str and the data type of str is char*. -1 - We can deal with this ourselves otherwise - Strings will, when required, cut-off at this length and end with 0. Please take note that in this case another byte will be required for the terminating 0.

char		str[31];

:

placeholder::replace (12, str, 30);

Since

Available

priint:comet InDesign^® Plug-Ins

static int reload_panel(long classid, int reloadAll = 0)

Reload the data records of a panel list. To reload the complete list, set reloadAll to 1. If you want only to update the linkbuttons of the list(s), you can use the command placeholder::update_link_states.

Name	Type	Default	Description
Return	int		0 or ErrorCode
classid	int	-	Palettennummer specified by Werk II 0 - update all open and supported panels The following panels are supported: kPanelProducts kPanelPublications kPanelPreviews kPanelURLLink kPanelPageTemplates (since v4.1.8 R30020)
reloadAll	int	0	Reload complete list? 0 : No, only reload list entries 1 : Yes, reload the complete list

Since

Parameter reloadAll neu seit Version 2.1 R 684, 25 April 2008

Available

priint:comet InDesign^® Plug-Ins

See Also

placeholder::update_link_states
list::reload

static int to_xml_element(
  ItemRef frame,
  int pos,
  int len,
  char* parent,
  char* name = 0,
  int index = -1)

Create XML-Elements for Comet placeholders. You may create elements for a frame or for text placeholders. The following attributes are added to the elements :

• PlaceholderID, ID of placeholder
• ID, ID of linked object
• ID2
• ID3
• StringID
• ClassID, class id of linked object

Use xml::to_placeholder as the opposite function.

Name	Type	Default	Description
Return	int		0 or ErrorCode
frame	ItemRef	-	valid frame reference 0 : current text frame
pos	int	-	start position in text kTotalEnd Use the frame itself, not its text. In this case, the frame must not be a text frame. If the frame has no placeholder, the function does nothing. kSelection Use current text selection. otherwise : 0-based text position
len	int	-	Length of text (ignored if pos kTotalEnd or kSelection) . kEnd Bis zum Textende
parent	String or char*	""	Parent node for frame XML element. If the path does not exist, it will created. If an XML element already exists at an other place in the hierarchy, the element is moved to the requested place. The XM elements for the text placeholders are located inside the frames element. If no frame element exists, it will created. (In this case, parent means grandparents.) If a frame element already exists, all elements pointing to the given text range are removed at first.
name	String or char*	""	Name of XML element (renamend, if exists). "" : Use the placeholders name. In this case you have to take care, that all placeholders have XML conform names (starts with an ascii letter, contains only ascii letters, digits and _). Non XML conform characters replaced by '_'. If the element does not exist and the placeholder name is empty, the name Frame_NNN with the frame UID (see item::getint) as NNN is used as name. otherwise : XML-conform name of element
index	int	kEnd	0-based child position of the element. Ignored for text placeholders (they always use their text positions). . kEnd append

Preconditions

#include "internal/text.h"
#include "internal/types.h"

Create XML elements for all frame and text placeholders of the document. Frame elements are collected in elements for every page.

#include "internal/text.h"
#include "internal/types.h"

int main ()
{
    int 		result;
    ItemList	frames	= itemlist::pageframes (-1);
    ItemList	frames1	= itemlist::alloc ();
    int 		len		= itemlist::length (frames);
    ItemRef		frame	= item::alloc ();
    ItemRef		frame1	= item::alloc ();
    int			i		= 0;
    int			pg;
    char		pgstr 	[512];
    char		parent 	[512];
    int 		a, b, idx;

    page::get_str (pgstr, gFrame);
    pg = page::get (gFrame);
    sprintf (parent, "/Page_%s", pgstr);

    / Work on the first frame on text models only.
    while (i < len)
    {
        itemlist::get (frames, frame, i++);
        if (frame::is_textframe (frame, &a, &b, &idx, frame1))
        {
            if (itemlist::get_pos (frames1, frame1) < 0)
            {
                itemlist::append (frames1, frame1);
            }
        }
        else itemlist::append (frames1, frame);
    }

    len = itemlist::length (frames1);
    i 	= 0;
    while (i < len)
    {
        itemlist::get (frames1, frame, i++);
        wlog ("", "# Tagging placeholders of %d\n", item::getint (frame));

        / Frame
        result = placeholder::to_xml_element (
        frame,
        kTotalEnd, 0,
        parent, "", 		// use default name
        -1);				// append

        / Text content
        if (result == 0 && frame::is_textframe (frame))
        {
            result = placeholder::to_xml_element (
            frame,
            0, kEnd,
            parent, "", 		// use default name
            -1);				// append
        }

        wlog ("", "# Tagging placeholders of %d done with '%s'\n",
        item::getint (frame),
        serror (result));
    }

    return 0;
}

Since

Version 2.1 R 1155, 22.2.2009

Available

priint:comet InDesign^® Plug-Ins

See Also

define
xml::to_placeholder

static int get_prefix(int* start, int* len)

Is there a prefix placeholder for the current script placeholder and, if so, return its position and length. See here for more information about prefixes and postfixes of placeholders..

In scripts for creating a separator text, the function does not return saved values!

Here you can find more information about prefixes and postfixes of placeholders..

Name	Type	Default	Description
Return	int		Prefix placeholder of the current script placeholder. If no prefix exists or in case of errors, the function will return 0. 1 : prefix placeholder found 0 : no prefix placeholder found To check for errors, please use parameter pos. If pos is >= 0 all is okay.
start	int*	0	Output : Text relativ start of the prefix -1 : Error or no text placeholder defined in the script
len	int*	0	Output : Length of prefix

Preconditions

#include "internal/text.h"
#include "internal/types.h"

Deprecated

since v4.1 R24701

Since

v3.3 R3243, 30.10.2012

Available

priint:comet InDesign^® Plug-Ins

static int get_postfix(int* start, int* len)

Is there a postfix placeholder for the current script placeholder and, if so, return its position and length.

In scripts for creating a separator text, the function does not return saved values!

Here you can find more information about prefixes and postfixes of placeholders..

Name	Type	Default	Description
Return	int		postfix placeholder of the current script placeholder. If no postfix exists or in case of errors, the function will return 0. 1 : postfix placeholder found 0 : no postfix placeholder found
start	int*	0	Output : Text relativ start of the postfix -1 : Error or no text placeholder defined in the script
len	int*	0	Output : Length of postfix

Preconditions

#include "internal/text.h"
#include "internal/types.h"

Deprecated

seit v4.1 R24701

Since

v3.3 R3243, 30.10.2012

Available

priint:comet InDesign^® Plug-Ins

static int is_valid_funcvar(
  ItemRef frameRef,
  int textIndex,
  char* name,
  int actionType = 1)

Check wether a function variable is valid.

The function checks wether a function variable has a defined value. The function does NOT check wether the variable is defined in the script itself!

Name	Type	Default	Description
Return	int		0 : Error or not defined 1 : The variable has a defined value
ItemRef	frameRef	-	valid frame reference 0 : current script frame
int	textIndex	-	text index of placeholder >= 0 : text index of text placeholder < 0 : frame placeholder
String or char*	name	-	name of variable
int	actionType	1	script of function variable 1 : load script 2 : save script 3 : sync script 4 : build script

Since

v4.1 R14341, 4. Jan 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

get_funcvar_val
set_funcvar_val

static char* get_funcvar_val(
  ItemRef frameRef,
  int textIndex,
  char* name,
  int actionType = 1)

Get the value of a function variable of a placeholder.

Name	Type	Default	Description
Return	char*		Value of given function variable. "" : In case of some errors, the function will return "". To check whether this is the current value or an error, please use is_valid_funcvar. The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.
ItemRef	frameRef	-	valid frame reference 0 : current script frame
int	textIndex	-	text index of placeholder >= 0 : text index of text placeholder < 0 : frame placeholder
String or char*	name	-	name of variable
int	actionType	1	script of function variable 1 : load script 2 : save script 3 : sync script 4 : build script

Since

v4.1 R14341, 4. Jan 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

is_valid_funcvar
set_funcvar_val
comet.placeholder.getFuncVarValue

static int set_funcvar_val(
  ItemRef frameRef,
  int textIndex,
  char* name,
  int actionType = 1,
  char* newValue = "")

Set the value of a function variable of a placeholder.

if a variable does not exist, a new assignment is created for the given placeholder (Not for Illustrator!). To avoid new assignments for undefined function variables, please use is_valid_funcvar to check whether the variable exists already.

Changing values of variables of the current script will NOT change the value of the corresponding script value. (You may use the new value directly in your script in this case.)

Name	Type	Default	Description
Return	int		0 or ErrorCode
ItemRef	frameRef	-	valid frame reference 0 : current script frame
int	textIndex	-	text index of placeholder >= 0 : text index of text placeholder < 0 : frame placeholder
String or char*	name	-	name of variable
int	actionType	1	script of function variable 1 : load script 2 : save script 3 : sync script 4 : build script
String or char*	newValue	""	New value of variable

Since

v4.1 R14341, 4. Jan 2017

Available

priint:comet InDesign^® Plug-Ins, comet_pdf, Illustrator

See Also

is_valid_funcvar
get_funcvar_val
comet.placeholder.setFuncVarValue

Author

Paul Seidel

Version

16.10.2024, 11:40 Uhr

Alphabetic index HTML hierarchy of classes or Java