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(document=None, pages=[], frames=[], layers=[], placeholderIDs=[], edge=8, sort=0, calcCoords=False, unlinked=True)

Search for placeholders on a page or page level. Placeholders are defined by their placeholderID and must be linked.

If a frame list is passed, unlinked objects are also collected.

If unlinked placeholders should also be included in the result list, please use the collect_any function. The search results can be sorted by row or column.

The function can be used to find the placeholder furthest in a specified page corner. In this case, the result list contains a maximum of one result. The distance to a corner is the sum of the X and Y value of the corresponding frame corner : Left upper side corner - top left of the frame, right upper side corner - top right of the frame. 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 removed (or contains a placeholder that should not be used), the green frame wins. (Green and blue have the same distance to the corner, but green is higher). The orange frame is not found. It is the highest, but unfortunately it is also far to the right (and that’s never good anyway).

By default, the XY coordinates of text placeholders are also calculated. 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

• document (None | CDocument) –

  Collect links in this document only.

  • None: Script document

• pages (list[int]) –

  List of 0-based page indices to restrict collecting to.

  • Empty list: Impose no restrictions

  • [-1]: Current page

  Warning

  For InDesign Server and comet_pdf the current page is not defined

• frames (list[CFrame]) –

  List of frames to restrict collecting to.

  • Empty list: Impose no restrictions

• layers –

  List of layers to restrict collecting to.

  The parameter type can be:

  • list [ str ]

    Layer names

  • list [ CLayer ]

    Layers

  • Empty list : Do not impose restrictions

  When the parameter is list [ CLayer ], all layers must belong to this document.

• placeholderIDs (list[int]) –

  List of placeholderIDs to restrict collecting to.

  • Empty list: Impose no restrictions

• edge (int) –

  Find all placeholders or placeholder of a specified corner.

  One of Link first selectors

• sort (int) –

  How to sort the result list.

  One of Link sorting

• calcCoords (bool) – Calculate text placeholder coordinates?

• 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 edge has invalid value

  • When parameter placeholderIDs has invalid entry

• CometError – On internal error

Available

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