comet.link

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

See also

Class CLink

CLink object instances provide functionality for querying link information

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.

    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

CScript

linklist::collect

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.

    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

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 comet.kDesignateDocument == Entire document.

  Allowed values are:

  • comet.kDesignateDocument

  • comet.kDesignateVisibleLayers

  • comet.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

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 comet.kDesignateDocument == Entire document.

  Allowed values are:

  • comet.kDesignateDocument

  • comet.kDesignateVisibleLayers

  • comet.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

CScript

linklist::delete_toc_entry