comet.placeholder

Methods

comet.placeholder.set(frame, placeholderID, ID=None, position=-1, length=0)

Set a placeholder for the specified frame or text part and connect it to the specified record ID. The content of the placeholder is not loaded. When setting the placeholder, it is checked whether the placeholder is defined in the data pool and is of the appropriate type (frame placeholder for frame, text placeholder for text).

Parameters:

  • frame (CFrame) – The frame to set the placeholder into.

  • placeholderID (int) –

    The placeholder ID.

    • 0: Undefined empty placeholder

    • -2: Remove placeholder.

      In texts, placeholders at the beginning and end of the text area are also automatically removed completely. When removing frame placeholders, the IDs of any linked object in the frame are retained.

      If the object ID is also to be removed, the link() function with object ID 0 (or -2), 0, 0, “” must be called BEFORE set().

    • -3 : (Only for text placeholders) Delete placeholder exactly in the specified text area.

    • else : The placeholder must have a relatedToID which is allowed for the context.

  • ID (CIDType) – When this parameter is not None, the placeholder is immediately linked to this record ID.

  • position (int) –

    Start position in the text from which the placeholder should be set.

    • -1 : Change frame placeholder (not text placeholder)

    Illustrator® Ignored

  • length (int) –

    Length of the text whose placeholders are to be changed.

    • -1: Placeholder outside tables is set up to the end of the current text.

      In tables, the placeholder is set up to the end of the table cell in this case.

    Illustrator® Ignored

Returns:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

placeholder::define

Connect all placeholders of a frame (or text range inside a frame) and all its child objects with a record.

Parameters:

  • frame (CFrame) – The frame to do the placeholder links in.

  • ID (CIDType | tuple[int, int, int, str]) –

    The record ID to links placeholders to.

    The parameter type can be:

  • position (int) –

    • >=0: Process text placeholders only from this text position.

      length must be > 0 and frame must be a text frame.

    • -1: Relink all text and frame placeholders.

    • -2: Relink only the frame placeholder.

    Illustrator® Ignored

  • length (int) –

    Length of the text whose links are to be changed.

    Only evaluated when position is >= 0

    Illustrator® Ignored

  • autoLoad (bool) –

    Immediately load the placeholders after linking?

    • False: No

    • True: Yes.

      Like placeholder::load with placeholder = 0 and recordids = 0 directly after the call of placeholder::link. The only difference is that in this case all tables built via table placeholders are also correct again - which they are not when using two separate calls.

  • applyLayoutRules (bool) –

    Only evaluted when autoLoad is True

    Layout rules are not normally called for individual text placeholders. If you still want to execute the “After load” rules of the frame when applying the function to text placehoders, set the parameter to True.

  • changeStaticLinks (bool) – Overwrite static product links?

Returns:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

placeholder::link

comet.placeholder.load(frame, start=-1, length=-1, applyLayoutRules=False, placeHolders=[], recordIDs=[])

Execute the load action for all placeholders of a frame or text including its sub-objects.

Parameters:

  • frame (CFrame) – The frame to do the loading for.

  • start (int) –

    The text start index to begin loading.

    • >=0 : Process text placeholders only from this text position. The parameter length must be > 0 and the passed frame must be a text frame.

    • -1 : Reload all text and frame placeholders.

    • -2 : Reload only the frame placeholder.

    Only evaluated for text frames.

  • length (int) –

    The text length to load placeholders for.

    Default is constants.kEnd == load every placeholder until the text end.

    Only evaluated for text frames.

  • applyLayoutRules (bool) –

    Layout rules are not normally called for individual text placeholders.

    When you want to execute the “After loading” rules of the frame when applying the function to text areas anyway, set this parameter to True.

  • placeHolders (list[int]) –

    List of placeholderIDs to restrict loading to.

    • Empty list: Impose no restrictions

  • recordIDs (list[CIDType | tuple[int, int, int, str]]) –

    List of recordIDs to restrict loading to.

    • Empty list: Impose no restrictions

    The entry types can be:

Returns:

None

Raises:

  • TypeError – When parameter types are invalid.

  • ValueError –

    • When parameter start has invalid value.

    • When parameter length has invalid value.

  • CometError – On internal error.

Available:

InDesign® comet_pdf® Illustrator®

CScript:

placeholder::load

comet.placeholder.loadServer(entities={})

Execute the standard load script of a placeholder in a PublishingServer environment.

This function can only be used in the context of a placeholder load script.

For a more in-depth explanation, see here

Parameters:

entities (dict[str, str]) – Key/value pairs to override or set certain input values

Returns:

The result from executing the load script

Return type:

str

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

server::load_placeholder_str

comet.placeholder.loadDataProvider(dataProviderID, resultType, resultEntityID='', search='', replacements={})

Load data from a DataProvider.

Please note:

In most cases, you should prefer one of the following solutions instead of loadDataProvider():

  • loadServer(): In the placeholder context, this function is much simpler and safer. All values defined for the placeholder will be passed correctly, except those you explicitly override.
    loadServer() also ensures that context rules defined for the placeholder are evaluated correctly and transmitted to the server. loadDataProvider() does not support context rules, since they are defined only at the placeholder level. Therefore, neither language and country criteria nor document specific properties like the documentID can be used.

  • Outside of placeholders, calling your own Java method is more flexible, safer and easier. The procedure is described in cScript / Java Bridge.

Parameters:

  • dataProviderID (str) – Identifier of the data provider.

  • resultType (int) –

    The result type of the data provider. This must match the data provider which is called and determines the result type of this function.

    Currently the following data types can be processed:

    • 0: A single string (the first one supplied by the DataProvider) is returned as the result.

      Result type is str.

    • 1: The result is returned as a simple string list.

      Result type is list [str]

    • 2: A list of of IDs.

      Result type is list [CIDType]

    • 3: A list of products.

      Result type is list [CProduct]

  • resultEntityID (str) – Identifier of the result entities. The content replaces the <Entity.ResultId> tag of the dataProviderID statement.

  • search (str) – SearchString. The content replaces the <Record.SearchStr> tag of the dataProviderID statement.

  • replacements (dict[str, str]) –

    Any number of key/value pairs consisting of two strings each for further replacements.

    The replacement of the key/value pairs is a pure search and replace in the statement of dataProviderID: In the statement, all occurrences of <key> are replaced with ‘value’. Single quotes in Values are masked in the process.

    Of course, to replace all tags used in the statement, you need to know the statement. The original DataProvider statement is written to the logfile with the preamble # DataProvider statement received from server. The result of the substitutions can also be found in the logfile with the introduction # Preprocessed data provider statement.

    Which value is expected for which key may have to be asked where the DataProvider method was created. Values to replace the common PublishingServer specific tags can be found here.

Returns:

The result from loading the data provider. Data type depends on parameter resultType.

Raises:

  • TypeError – When parameter types are invalid.

  • ValueError –

    • When parameter resultType has invalid value.

    • When parameter replacements contains invalid value.

  • CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

server::dataprovider_load

comet.placeholder.store(frame, start=0, length=-1, placeHolders=[], recordIDs=[])

Execute the store action for all placeholders of a frame or text including its sub-objects.

Parameters:

  • frame (CFrame) – The frame to store placeholders for.

  • start (int) –

    The text start index to begin storing.

    Only evaluated for text frames.

  • length (int) –

    The text length to store placeholders for.

    Default is constants.kEnd == store every placeholder until the text end.

    Only evaluated for text frames.

  • placeHolders (list[int]) –

    List of placeholderIDs to restrict loading to.

    • Empty list: Impose no restrictions

  • recordIDs (list[CIDType | tuple[int, int, int, str]]) –

    List of recordIDs to restrict loading to.

    • Empty list: Impose no restrictions

    The entry types can be:

Returns:

None

Raises:

  • TypeError – When parameter types are invalid

  • ValueError –

    • When parameter start has invalid value

    • When parameter length has invalid value

  • CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

placeholder::store

comet.placeholder.build(frame)

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:

  • RelatedTo kMultiFrame (=6)

  • CharacterStyleID > 0

Parameters:

frame (CFrame) – The frame to execute the build action for.

Returns:

None

Raises:
Available:

InDesign® comet_pdf®

CScript:

placeholder::build

comet.placeholder.getTagValue(frame, slot, textIndex=-1)

Query placeholder information from a frame or text in a text frame.

Parameters:

  • frame (CFrame) – The frame to fetch the values from

  • slot (str) –

    The slot to get (Case insensitive).

    See Placeholder slots for a table of keys.

  • textIndex (int) –

    When frame is a text frame this parameter can be used to query text placeholder information inside the frame.

    • -1: Ignore text placeholders and query the frame itself

Returns:

The tag value and text start and length. When querying a frame placeholder, the text start and length will be 0.

Return value is in the form (value, start, length), where value is the queried slot data.

Return type:

tuple[int, int, int] | tuple[str, int, int], depending on the queried slot

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:
comet.placeholder.setTagValue(frame, slot, value, target=3, position=0, length=-1)

Change either the placeholder on frame or all contained placeholders, or both.

Depending on the type of the change attribute slot, value must be either str or int.

See Placeholder slots for a table of keys for slot and their data types for value.

Parameters:

  • frame (CFrame) – The frame to change the placeholder values in.

  • slot (str) –

    The slot to change (Case insensitive).

    See Placeholder slots for a table of keys.

  • value (str | int) – The value to set. Type depends on the slot.

  • target (int) –

    Whether to change only the frame placeholder slots, placeholder slots inside the frame or everything.

    • 1: Change only the frame placeholder

    • 2: Change the contained placeholders

    • 3: Change all placeholders

    Illustrator® Ignored

  • position (int) –

    Start of the range for changing contained placeholders.

    Only evaluated when target is 2 or 3

    Illustrator® Ignored

  • length (int) –

    Length of the range for changing contained placeholders.

    Only evaluated when target is 2 or 3

    Illustrator® Ignored

Returns:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

placeholder::change_tags

comet.placeholder.getFuncVarValue(frame, name, textIndex=-1, actionType=1)

Get the value of a placeholder function variable.

Parameters:

  • frame (CFrame) – The frame to query the function variable values from.

  • name (str) – The name of the variable to query.

  • textIndex (int) –

    Text index of the placeholder.

    • >= 0: Text index of the text placeholder.

    • < 0: Frame placeholder.

  • actionType (int) –

    Which action type to set the function variable value for.

    One of Action types.

Returns:

None

Raises:

  • TypeError – When parameter types are invalid.

  • ValueError –

    • When parameter name is empty.

    • When parameter actionType has invalid value.

  • KeyError – When function variable was not found.

  • CometError – On internal error

Available:

InDesign® comet_pdf® Illustrator®

CScript:

placeholder::get_funcvar_val

comet.placeholder.setFuncVarValue(frame, name, value, textIndex=-1, actionType=1)

Set the value of a function variable of a placeholder.

If no value exists for the given variable name, a new entry is created for this name in the placeholder (not in Illustrator!).

However, this variable can probably not be used in the script.

Changes to the values of function variables have no effect on the value of the variable in the current script (you can also use the new value here directly).

Parameters:

  • frame (CFrame) – The frame to change the function variable values in.

  • name (str) – The name of the variable to set.

  • value (str) – The value of the variable to set.

  • textIndex (int) –

    Text index of the placeholder.

    • >= 0: Text index of the text placeholder.

    • < 0: Frame placeholder.

  • actionType (int) –

    Which action type to set the function variable value for.

    One of Action types.

Returns:

None

Raises:
Available:

InDesign® comet_pdf® Illustrator®

CScript:

placeholder::set_funcvar_val