comet.link¶

The comet.link module provides functionality for gathering comet.CLink objects

Methods¶

comet.link.collect(source, layers=[], placeholderIDs=[], sort=0, calcCoords=True, unlinked=True)¶

Search for placeholders which are set inside a document.

The function provides several parameters for filtering the results. The search results can be sorted by row or column.

By default, the XY coordinates of text placeholders are calculated. Calculation can be disabled using the parameter calcCoords. These values are always in points relative to the upper left corner of the frame. Please note that in this case, placeholders that are completely or partially overset will not be found.

If you also want to collect placeholders of the overset, the optional list of placeholders must be terminated with .0,0, see the optional parameters in the last line of the parameter table.

Parameters:

source (None | list[int] | CDocument | tuple[CDocument, list[int]] | list[CPage] | list[CFrame]]) –
Where to search for links.
- None
  All frames in the script document.
- list [int]
  All frames on these page indices of the script document.
  
  -1: Current page.
  
  InDesign® comet_pdf® For InDesign Server and comet_pdf the current page is not defined
- CDocument
  All frames in this document.
- tuple [CDocument, list [int]]
  All frames in a document on the specified page indices.
- list [CPage]
  Search in all frames on these pages. All entries must belong to the same document.
- list [CFrame]
  Search in these frames. All entries must belong to the same document.
layers (list[str | CLayer]) –
List of layers to restrict collecting to.

The entry types can be:
- str
  Layer name.
- CLayer
  Layer.
All entries of type CLayer layers must belong to the provided document of source.

Empty list : Do not impose restrictions
placeholderIDs (list[int]) –
List of placeholderIDs to restrict collecting to.
- Empty list: Impose no restrictions
sort (int) –
How to sort the result list.

One of Link sorting
calcCoords (bool) –
Calculate text placeholder coordinates?

Please note that placeholders that are completely or partially in the text overset do not have (complete) XY coordinates. Placeholders that are entirely or partially in the text overset are therefore not included in the results list if coordinate calculation is activated.
unlinked (bool) – Include unlinked placeholders aswell?

Returns:

Found links

Return type:

list[CLink]

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter pages has entries out of bounds
- When parameter layers has invalid entry
- When parameter placeholderIDs has invalid entry
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

linklist::collect

Examples:

Fetch information about all links in a document and output them to the logfile.

#!py
#pragma plain

import comet

def main():

    doc = comet.document.getFront()

    try:
        links = comet.link.collect(doc)

        comet.wlog("comet.link.collect results:")
        for link in links:
            linkMessage = '--------------------------------------------------\n'

            linkMessage += f'PlaceHolder ID: {link.getPlaceHolderID()}\n'
            linkMessage += f'RecordID ID: {link.getRecordID()}\n'

            linkType = link.getType()
            if linkType is comet.CLink.kTypeText:
                linkMessage += 'Type: Text\n'
                linkMessage += f'Position: {link.getPosition()}\n'
                linkMessage += f'Length: {link.getLength()}\n'
            elif linkType is comet.CLink.kTypeFrame:
                linkMessage += 'Type: Frame\n'


            linkMessage += f'Layer: {link.getLayer().getName()}\n'

            funcVarsLoad = link.getFuncVars(comet.constants.kActionTypeLoad)
            linkMessage += 'FuncVars load:\n'
            for funcVar in funcVarsLoad:
                linkMessage += f'\tKey: {funcVar[0]} | Value: {funcVar[1]}\n'

            funcVarsStore = link.getFuncVars(comet.constants.kActionTypeStore)
            linkMessage += 'FuncVars store:\n'
            for funcVar in funcVarsStore:
                linkMessage += f'\tKey: {funcVar[0]} | Value: {funcVar[1]}\n'

            funcVarsSync = link.getFuncVars(comet.constants.kActionTypeSync)
            linkMessage += 'FuncVars sync:\n'
            for funcVar in funcVarsSync:
                linkMessage += f'\tKey: {funcVar[0]} | Value: {funcVar[1]}\n'

            funcVarsBuild = link.getFuncVars(comet.constants.kActionTypeBuild)
            linkMessage += 'FuncVars build:\n'
            for funcVar in funcVarsBuild:
                linkMessage += f'\tKey: {funcVar[0]} | Value: {funcVar[1]}\n'

            comet.wlog(linkMessage)

        comet.wlog('--------------------------------------------------')
        comet.wlog("comet.link.collect results end")

    except Exception as e:
        comet.showMessage(str(e))

    return 0

comet.link.getAtEdge(source, edge=0, layer=None, placeholderIDs=None, unlinked=True)¶

Get a link which is at a specific edge of a a list of frames or on a page.

The function can be used to find the placeholder closest to a specified page corner.

The distance to a page corner is calculated to the the corresponding frame corner:

Left upper side page corner ⬌ top left of the frame.
Right upper side corner ⬌ top right of the frame.
etc..

If two frames have the same distance, the higher (or lower) frame is used.

In the picture the red frame with this distance definition is closest to the upper left side corner. If it is not included in source or filtered out, the green frame wins (Green and blue have the same distance to the corner, but green is higher).

Parameters:

source (None | int | CPage | tuple[CDocument, int] | list[CFrame]) –
Where to get the link from.

The parameter type can be:
- None
  All frames on the current page.
  
  InDesign® comet_pdf® For InDesign Server and comet_pdf the current page is not defined
- int
  All frames on this page index of the script document.
- CPage
  All frames on a page.
- tuple [CDocument, int]
  All frames in a document on a specified page index.
- list [CFrame]
  Search in these frames. All entries must belong to the same document.
edge (int) –
The edge to get the closest placeholder for.

One of Link first selectors.
layer (None | str | CLayer) –
Restrict the input to this layer.

The parameter type can be:
- None
  Ignore the parameter.
- str
  A layer name.
- CLayer
  A layer. Must belong to the same document as parameter source.
placeholderIDs (list[int]) –
List of placeholder IDs to restrict source to.

None or empty list: Impose no restrictions
unlinked (bool) – Can the result be an unlinked placeholder?

Returns:

The found link or None when none was found.

Return type:

CLink

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter layers has invalid entry
- When parameter which has invalid value
- When parameter placeholderIDs has invalid entry
CometError – On internal error

Available:

InDesign® comet_pdf®

See also:

collect()

CScript:

linklist::collect

comet.link.insertTocEntry(document=None, filter=[], designate=3, options={})¶

Create table of content entries.

The function collects the document data necessary for a table of contents.

Placeholders to take into account are determined by the parameter placeHolderIDs.

If you are currently connected to a PublishingServer, the data is transferred to the server.

To retrieve these entries, the Java server plugin CometTableOfContents provides special DataQuery methods.

These can be used in DataProviders and accessed via text placeholders of the Table Of Contents entity in the document.

Previously created directory entries of the same placeholders and the same area in the PubServer are deleted when this function is called.

The function does not create a table of contents in the document. It only collects the data necessary for a table of contents.

Parameters:

document (None | CDocument) –
Create TOC entries for this document.
- None: Script document
filter (list[int]) –
List of placeholder IDs which are taken into consideration when creating the entries.

Empty list: All placeholders
designate (int) –
The scope to create entries for.

Default is constants.kDesignateDocument == Entire document.

Allowed values are:
- constants.kDesignateDocument
- constants.kDesignateVisibleLayers
- constants.kDesignateActiveLayer
options (dict) –
Additional options.

Keys must be str.

The following options are available:
’kPublication’:
- Value type: str
- Default: Value of the XML-attribute <publication> of the document Root element.
Name / ID of the publication. Only used for output.
’kDocumentID’:
- Value type: str
- Default: Value of the XML-attribute <documentId> of the document Root element.
ID of the document. Only used for output.
’kXMLPath’:
- Value type: str
- Default: “”
Save data to an XML file. Already existing XML files are overwritten. Only used for output.
With active Pubserver connection:
- ”” : Don’t write an additional XML file
- else : Complete path to output file.
Without PubServer connection:
- ”” : Put XML next to the InDesign® document. When the document is not yet saved, the file is written to the documents folder.
- else : Complete path to the output file.
’kFlags’:
- Value type: int
- Default: 0
Additional output options.

Sum of the following values:
- 1 : Add inlines to the results aswell
- 2 : Sort results by page, XY position, text position

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter designate has invalid value
- When parameter options has invalid keys or values
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

linklist::insert_toc_entry

comet.link.deleteTocEntry(document=None, filter=[], designate=3)¶

Delete previously created table of content entries.

The function deletes previously created table of content entries of certain or all placeholders of a certain scope.

Parameters:

document (None | CDocument) –
Delete TOC entries for this document.
- None: Script document
filter (list[int]) –
List of placeholder IDs which are taken into consideration when deleting the entries.

Empty list: All placeholders
designate (int) –
The scope to delete entries for.

Default is constants.kDesignateDocument == Entire document.

Allowed values are:
- constants.kDesignateDocument
- constants.kDesignateVisibleLayers
- constants.kDesignateActiveLayer
options (dict) –
Additional options.

Keys must be str.

The following options are available:
’kPublication’:
- Value type: str
- Default: Value of the XML-attribute <publication> of the document Root element.
Name / ID of the publication. Only used for output.
’kDocumentID’:
- Value type: str
- Default: Value of the XML-attribute <documentId> of the document Root element.
ID of the document. Only used for output.

Return type:

None

Raises:

TypeError – When parameter types are invalid
ValueError –
- When parameter designate has invalid value
- When parameter options has invalid keys or values
CometError – On internal error

Available:

InDesign® comet_pdf®

CScript:

linklist::delete_toc_entry

comet.link¶

Methods¶

Table of Contents

Previous topic

Next topic

This Page