Comet placeholders

Version :
12.06.2024, 12:35 Uhr

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 :

For the description of the action, the following instruction types can be used : In addition every Werk II panel can be expanded with its own so-called panel actions. These actions are inserted in the respective panel menu and must be created in cscript. Actions are created by Werk II and partners of Werk II and must be adapted to each of the available data sources.

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*):

Functions are delimited by blanks from the tag name. You may append as much functions as you want. Every function works on the current tag value. You must not nest function nor use functions in the parameters. The same functions are available in the columns of an xmlquery.

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:

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 :

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:

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:

Variable name Data type Description
gProductIDs IDTypeList List of products to be built as repeating elements
gClassID int (classID of products
gPageItemIDs List List of templates the for the products products in gProducts. Must be exactly as long as gProductIDs.
gFormat String FormatString, see below
gElements ElementList ab v4.1 R19501 List of products to be built. If the list has at least one entry, the other variables are ignored. See here for more information.
gPrivateSync int* since v4.1 R21400 The variables are used for customized calculations of the synchronization status of repeating elements. They are defined in sync calls only. Otherwise they have the value 0. Before accessing the variables, at least one of the variables must be checked against 0! The elements in the document can be found using the function

   elementlist::get_area_built_elements function.
  • gPrivateSync Default 0. Set the value to 1 (*gPrivateSync=1;), to enable your customized sync. Otherwise the default behavior is executed.
  • gState Default 1 (Okay). Set the desired status of the repeating element here, see set_sync.
  • gSyncChanged Default 0. If you call set_sync in your script, set this variable to 1 (*gSyncChanged=1;).
  • gOldValue Default "". The string is shown in the ToDo panel as the Document text. Please note that the variable is of type String.
  • gNewValue Default "". The string is shown in the ToDo panel as the Data pool text. Please note that the variable is of type String.

gState int*
gSyncChanged int*
gOldValue String
gNewValue String

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

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:

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:

Data pool Type Attribute
XML, SOAP int metadata.placeholder.objectnameid of file placeholder.xml
ODBC u~nd Oracle int ObjectNameID of table placeholder

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:

Variable Type Description
gRecordID, gRecordID2, gRecordID2 int ID of the object whose name is to be determined
gRecordStringID,

gRecordStringID1, gRecordStringID2, gRecordStringID3

char*
gPlaceholderID int ID of the calling placeholder
gCreated char* Date and time when the placeholder was created/last modufied in the document.

Format : YYYYMMDDHHMMSS

gModified
gObjectName char [8000] Fill in the objects name here.

The name must not be longer than 7999 characters. The variable must not be released.

gFrame ItemRef On frame placeholder the UID of frame otherwise 0
gDocument ItemRef Document of placeholder

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

Why not use the name of the product shown in product pool?

  1. The panel may use various instructions for loading products in which the product may also have different names.

  2. A product does not have to be shown pby the product pool.

  3. The product is a sub entry of a closed entry of the product pool.

  4. The product hierarchy can contain different perspectives on a product.

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.
#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; }

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

priint:comet InDesign® Plug-Ins, Illustrator

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; }

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

priint:comet InDesign® Plug-Ins, comet_pdf

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; }

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

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

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 insensitve.
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
#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; }

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

priint:comet InDesign® Plug-Ins, comet_pdf

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.
#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; }

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

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

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.
#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; }

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

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

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);


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);


priint:comet InDesign® Plug-Ins

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.)
#include "internal/types.h"

v4.2 R30123, 2. March 2022

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);

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

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

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);

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.

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

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.

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
#include "internal/text.h"
#include "internal/types.h"
err_code = placeholder::build (item);


priint:comet InDesign® Plug-Ins

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; }


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

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

Version 1.1.6

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
#include "internal/text.h"
#include "internal/types.h"

Version 1.1.6

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
#include "internal/text.h"
#include "internal/types.h"


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);


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

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

priint:comet InDesign® Plug-Ins

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 :

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
#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; }

Version 2.1 R 1155, 22.2.2009

priint:comet InDesign® Plug-Ins

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
#include "internal/text.h"
#include "internal/types.h"

since v4.1 R24701
v3.3 R3243, 30.10.2012

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
#include "internal/text.h"
#include "internal/types.h"

seit v4.1 R24701
v3.3 R3243, 30.10.2012

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

v4.1 R14341, 4. Jan 2017

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

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

v4.1 R14341, 4. Jan 2017

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

is_valid_funcvar
set_funcvar_val

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

v4.1 R14341, 4. Jan 2017

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

is_valid_funcvar
get_funcvar_val

Author
Paul Seidel
Version
12.06.2024, 12:35 Uhr

Alphabetic index HTML hierarchy of classes or Java