The plugin provides the panel Placeholder Options. The panel shows all information about the first placeholder of the current document selection. In the panel, local settings of the placeholder can be changed and the function variables of the placeholder can be configured. With a Partner License the placeholder scripts can be edited. In the lower part of the window, additional scripts such as Layout Rules and BuildSupport Scripts can be edited.

The values of all fields labeled in italics can be changed in the document. Use this option sparingly, and only during development and testing phases.

Click on to edit scripts.

Placeholder Options can also be set with cScript, see the function placeholder::change_tags.

In the third panel section you can see the list of defined function variables you can use to individualize placeholder scripts. You can find more information on this under Function Variables.

In the fourth panel section (labeled "Unnamed Object" here), you can see the ID of the object the placeholder is linked with. IDs consist of three numbers and a string.

For development purposes, you can copy this ID to the clipboard here.

In the lower panel section, you can edit any actions defined in your data pool. Select the action in the popup labeled Action. The action's ID is entered in the Script field. With you can edit the script. You can of course enter the ID into the field directly, if you wish.

Alternatively, you can also enter the path of an include file (e.g. [pubserver]/placeholderUtils.h) and temporarily change the contents of this file for your local tests. The changes will not be written back to the database and will be lost when the data connection ends!

Using the Save button you can store actions and includes of the PubServer directly directly on your computer. Attention: This option is only supported for active connections to a PubServer!

Attribute Description
ID and Name A placeholder's ID has to be unique. The name is only used in the placeholders panel.
Section With the section, it is possible to group placeholders, which should make finding specific placeholders easier for users.
Color Placeholders are highlighted in green in the text : . For better differentiation, placeholders can also be shown with other colors defined in the configuration data of data pool.
Type
Name SQL XML/SOAP Remarks
Text 1 text
Textframe 2 textframe
Imageframe 3 imageframe
XML Elements 4 xml element currently unused
Document 5 document currently unused
Repeating frames 6 multi frames
Repeating texts 7 multi text currently unused
Tables 8 table since Version 1.4, requires the Definition of table templates
Tables 8 table Requires the Definition of table templates
Cross References 9 crossref Definition of Cross References
Serial Text 10 serialtext Placeholder for serial texts
Serial Images 11 serialframe Placeholder for serial images
Serial Template 12 serialpageitem Templates for serail letters
Class The placeholder class ensures that a placeholder can only be linked with objects of the apporpriate type (e.g. with products). It equals the ClassID of the Comet panels.
Load/Table, Write, Sync, Object name, Text format IDs of the actions that should run in the respective contexts.
Table [since Version 1.4] For table placeholders, the laod ID contains the action that determines the table template ID.
Text format/Build Script/Productname

Name or ID of a text style with which the placeholder text should be formatted automatically

Build Script For repeating elements, ID of the action that determines repeating elements
Productname [since Version 1.4] ID of the Action that determines the object the table gets linked with
Delimiter Texts [since v3.2.3 R2450] Static texts that should be inserted into the document before/after the placeholder is loaded, see here.
Syncstatus Should the placeholder display a sync statuse?
Update Behaviour Synchronization can be expensive. Placeholders may therefore prevent it in certain circumstances.
Objectinfos The object the placeholder is linked with.

For performance reasons, when linking a text or frame with a placeholder, the definition srored in the data pool is copied into the document. Because of this, later changes to the definitions in the data pool will not affect the document.

Placeholder definitions in the document can be updated. To do so, in the placeholder panel, select the entry

    Update Placeholder Definitions

If you are using templates, you also need to update the definition in all templates.

All values in the panel labeled in italics can be changed manually. Value changes are immediately applied during editing. They only apply to the current document selection. Text or table placeholders that are only partially selected are updated as well. (To change a single placeholder's value, placing the cursor inside it will suffice because of this.)

cScript offers a number of functions for reading and updating placeholder values in the document, see the documentation for the placeholder module.

The Text Placeholder property is a text attribute such as font size or color. InDesign® organizes texts in chunks, where all text attributes are the same.

So, for instance, the text "bbb ccc ddd eee" consists of four chunks

If you place a placeholder over the text "bbb ccc ddd eee", the text still consists of four chunks. But each chunk also has the same placeholder attributes. In order to determine the limits of the placeholder, the chunks of the environment must also be checked: As long as a chunk has the same placeholder attributes, the text still belongs to the placeholder. Assuming that the same placeholder would be in front of the text now, this check could not see the difference and extend the placeholder accordingly. Threfore, between two identical placeholders there must be at least one separator!

Separators between the same placeholders are not a discussable implementation detail. They inevitably result from the management of formatted text used in InDesign®!

HAIR SPACE <0x200A> or even better ZERO WITH SPACE <0x200B> are particularly suitable as separators. Since placeholder delimiters are part of the placeholder they cannot be used as placeholder separators!

Placeholders are equal if the following conditions are fulfilled:

  1. Same placeholder ID
  2. Same objekct (product) ID
  3. [since v4.1.6 R25256] Same values of the function variables. Experimental! If this check should have an unexpectedly high support effort or unexpected side effects, we will remove this check again!

If you want to use the same placeholders without separators, you must therefore ensure that you first either link the first placeholder to an object and/or change its function variables from the default to a local value! Otherwise, the second placeholder is immediately combined with the first placeholder! Changes of the object link or the values of the function variables can lead to the merging of the placeholders!

[since Version 1.4]

Placeholders can automatically insert and build tables. For better differentiation, table placeholders are highlighted with a checkerboard pattern in the document. If a table placeholder is linked with an object, the text of the placeholder is replaced with the desired table. The table is built and its content loaded.

Table placeholders are defined just like all other placeholder. Use placeholder type 8 (for data bases) or "table" (for XML and SOAP) an.

The placeholder's load ID is the ID of an action that determines the table ID. In this Script the global variable gTableID specifies the ID of a table templates.

Here an example script. Bear in mind that gTableID is a pointer - in other words: don't foget the *prefix to gTableID.

int main ()
{
	showmessage ("Table Selection");

    *gTableID = 34;
    
    return 0;
}

In the Table Build panel, the name of the object the table is linked to can be seen on the tab Current Links. This name can be defined with the field Textformat/Build Script/Productname of the placeholder. Enter the ID of an action that should determine the name here. This action has to be a SQL/XML query, which returns exactly one result column of type string.

Here an example in XMLQuery for determining the product name.

"$MYFILE"
select name node products.product where id = <ID>

The table ID defined in the load script should refer to an existing table template. For information about how to create such a template, see here.

When replacing the placeholder with a table, the placeholder ID and the original placeholder text in stored in the new table. The text contains formatting. A maximum of 2000 characters is stored. You can replace a so-called managed Table with the original placeholder again. To do so, in the placeholder panel (or in the menu Plug-ins -> Placeholder), select the entries

    Replace all managed tables by placeholders

    Replace table by placeholder

The stored information is used when relinking texts. All managed tables of the text are restored to their original state before linking with a new product (Shift-Click in the first column of the product of placeholder::link with autoLoad = 1) and rebuild after the link.

[since v3.2.3 R2450] Text and Table placeholder can insert delimiter text before or after the actual placeholder. These texts are updating when loading the placeholder. They can choose between two texts : one for when the placeholder is empty, one for when it is not. The inserted text is automatically assigned an identifier that ensures that, in case the delimiter text changes, the old text in the placeholder definition or the document can be restored.

Delimiters are hichlighted with a zig-zag line beneath the text :

A placeholder's delimiters are displayed in the placeholder panel Placeholder Options in the block Delimiters.

Attention : The Delimiters block is only visible when the Placeholder Options panel is wide enouth. If the block is invisible, drag to resize the panel.

This is what it looks like in the document :

By editing the fields (or clicking the respective -Buttons), you can locally change the delimiter texts for the currently selected text placeholders of the document. The changes are stored in the document. You can locally change the definition of the delimiter texts in placeholders by selecting a text placeholder in the document and then changing the values in the fields. Alternatively you can click the respective symbols and change the value in the appearing dialog. Manual changes are lost on relinking placeolders and when updating their placeholder definitions.

If you use few delimiters and do not repeatedly reset placeholders, you do not need the data model extensions described below to use delimiters. The delimiters are read directly from the document at runtime.

All Delimiters may use the following shorthands. They are replaced before the text is applied :

Shortcut Description
/t Tabulator
/n

Softreturn

/r

new paragraph

/r+

[since v4.1 R23334] New paragraph of "successor" style of current paragraph style. In this case, the delimiter text must not contain any other text!

Warning : Here the slash (/)is expected, not the backslash (\).

Delimiters can be specified directly or consist of a sequence of instructions.

You can specify any text, even formatted text (that does not start with '#') as a delimiter. Delimiters may be %!TT-Text and contain Comet Character Formats. Special characters can be used directly or in <0xFFFF> notation. The \FFFF notation is not supported here!

Since v4.1 R2277 delimiter texts may contains placeholders (w2 tags) itself. But please note the following:

  1. The contents inserted this way are still delilmiter texts of the triggering placeholder. The placeholders in the delimiter text definition are removed after loading.
  2. Loading inner placeholders of direct text is supported only by in-direct TaggedText import.

Please note the following difference between tagged and plain text:

TaggedText (%!TT et al.) uses the current text attibutes (color, font size, character style) of the current paragraph. Local overrides at the insertion point are not continued!

To continue local overrides at the insertion point, please insert plain text only!

Delimiter instructions start with a #. After that, any number of space-separated delimiter instructions may follow. All supported instructions are explained in the table below :

Instructions Description Example
"Text"

Append to delimiter placeholder. The quotation marks are part of the definition!

"/r"

pStyle "pStyleName"

set Paragraph/Character formats placeholder text. For pStyle1, this only affects the first paragraph in the placeholder text.

If the style is not defined in the document, the global Variables of the settings are searched for a variable of that name, and the value of that variable used as the style name.

This field expects the name of a style definition, not TaggedText. Special characters in the style name may not be masked here!

The quotation marks are part of the definition!

pStyle "ItemList"

pStyle1 "pStyleName"

pStyle1 "Product:Motörhead"

cStyle "cStyleName"

cStyle "Red"

Script ID

Execute the Action with the specified ID.

In gPlaceholderID, the placeholder ID is accessible. The scripts have ClassID 50.

Script 12345

This example inserts a paragraph divider before the placeholder and formats the placeholder with paragraph style ItemList. If this style is not defined, the global variables are searched for a variable of that name. If one is found, the value of the variable Itemlist is used as the style name

# "/r" pStyle "ItemList"

Wwwith the -Buttons you can create the individual instructions. The dialog appends the new instruction to the existing sequence and looks like this:

Only one instruction can be appended at a time. The first part of the dialog (Paragraph style, Character style, script) that contains a value is appended.

Scripts to support prefixes and postfixes of placeholders are created as usual in the actions and get the ClassID 50. The scripts usually have two different tasks:

  1. Adjust placeholder formatting
  2. Change the text of the pre/postfix

The first case is a traditional placeholder script. The second is not a placeholder script. We can only start the script in one context and decided on the traditional case. This means that all text indices are relative to the placeholder and text changes only apply inside the placeholder.

If you want to change the pre or postfix, you have to use the global indices. Before each call to a text function, the function textmodel::use_global_index has to be called. You also have to make sure that the variables gStart and gLen are not mutated.

Warning: The function textmodel::use_global_index has to be called before each text function. The change only lasts for the duration of the next text function and is reset afterwards.

Here is a script to build a präfix text. Inserted text is automatically marked as delimiter text at the end of the script. However, if the text is added in several steps, the placeholder must removed in each step.

int myInsertBefore (char * txt)
{
    int 	oldLen	= textmodel::fulllength (1);
    int 	insertLen;
    
    textmodel::use_global_index ();
    textmodel::insert (txt, textmodel::start (1)); // 0 for reverse order of inserts
    insertLen = textmodel::fulllength (1) - oldLen;
    
    textmodel::use_global_index ();
    textmodel::clear_placeholders (textmodel::start (1)), insertLen, gFrame);
    
    return 0;
}

int main ()
{
    myInsertBefore ("111");
    myInsertBefore ("222");
    myInsertBefore ("333");

    return 0;
}

The following script inserts a paragraph separator as postfix, if the placeholder directly behind it has the length 1. Attention : In productive applications the test for length 1 should be replaced by the test for an empty placeholder (<0x200B>)!

int main ()
{
    int 	res;
    int 	pid, s, len;
    IDType	id 	=  idtype::alloc ();
                            
    res =  textmodel::get_placeholder (gFrame, gStart+gLen, &s, &len, &pid, id);

    if (res == 0 && len > 1)
    {
         textmodel::insert ((, gLen);
    }
                            
    return 0;
}

To define delimiter texts by cScript, use the script command placeholder::change_tags with the following info values

In w2 tags of TaggedText use the following keywords:

For more informations see here.

The easiest way to use delimiters should go over the definitions in the data pool. You have to extend the table/file placeholder with the following string fields.

Shortcut Datantype
prefix char*
prefixifempty

postfix

postfixifempty

The values of these fields are described and defined in the section Format.

You can add attributes to an XML file with any text editor that supports unformatted text. Simply replace a suitable end-tag with end-tag + newline + new tag - in the entire file.

Inserting the new elements in placeholder.xml by find and replace. If the element active does not exist, use another element in the first layer.

Find      </active>
Replace    </active>
           <prefix></prefix>
           <postfix></postfix>
           <prefixifempty></prefixifempty>
           <postfixifempty></postfixifempty>

The SQL statement required to add table attributes may vary depending on your particular database. As an example, we will use mySQL (although this should work on most systems).

alter table placeholder
    add prefix text,
    add postfix text,
    add prefixifempty text,
    add postfixifempty text;
update placeholder set
    prefix = '',
    postfix = '',
    prefixifempty = '',
    postfixifempty = '';
commit;

[Since v4.0.5 R14200] Sometimes it is desirable for a placeholder to remain unchanged when inserting a product, always showing the same content in all applications. To achieve this effect, a (text or frame) placeholder can be marked as Static Product Link in the panel:

In the document, such placeholders are marked with a red circle at the start of the placeholder:

The link of such placeholders can only be changed one of three ways:

With the cScript call placeholder::change_tags and the slot "StaticLink", a static product link can be undone (or set again).

In very rare cases, strange red dots appear in the document texts in addition to the colored placeholders:

These points are not errors in the document text or in the priint:comet plugins. They occur in case of serious and unexpected errors, as they can happen again and again during the configuration phase of a project. Such errors are of course normal, but the question is: Where do these points come from and how can they be removed again without deleting the entire text?

The dots (and the orange lines) mark a special kind of placeholders: They are generated from the <w2inlines> of the imported TaggedText when inserting inlines with TaggedText. After the actual import of the TaggedText, the corresponding inlines are immediately generated from these placeholders. This two-step import is necessary so that the inlines are created at the correct text positions. However, if InDesign® aborts or crashes during the creation of the inlines, the w2inline placeholder will remain in the document, but will of course no longer be replaced.

[Since v4.1.8 R29480] The fly-out menu Remove Red Dots from ~ of the Placeholder Options panel can be used to remove the red dots. If the text selection is active and not empty, the red dots are removed from the placeholders of the text selection. If the text selection is not active, the red dots are removed from the entire document.