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
Collect links in this document only.
None
: Script document
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
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:
When the parameter is
list
[CLayer
], all layers must belong to this document.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
- Raises
TypeError – When parameter types are invalid
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
- 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
Create TOC entries for this document.
None
: Script document
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:
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
- Raises
TypeError – When parameter types are invalid
When parameter designate has invalid value
When parameter options has invalid keys or values
CometError – On internal error
- Available
- CScript
- 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
Delete TOC entries for this document.
None
: Script document
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:
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
- Raises
TypeError – When parameter types are invalid
When parameter designate has invalid value
When parameter options has invalid keys or values
CometError – On internal error
- Available
- CScript