comet.product

The comet.product module provides access to product functionality

See also

CProduct

Methods

comet.product.create(ID=None)

Create a new CProduct object.

Parameters:

ID –

The initial ID to assign to the product.

The parameter type can be:

Returns:

The new product

Return type:

CProduct

Available:

InDesign® comet_pdf® Illustrator®

comet.product.get(statement)

Fetch the list of products from the product pool panel. The input statement determines which product entries to get.

Parameters:

statement (str) – Instructions on which entries to get. See here

Returns:

The products matching the query statement

Return type:

list[CProduct]

Available:

InDesign® comet_pdf® Illustrator®

CScript:

productlist::get

comet.product.establish(products, pageTemplateID, templateID, page=None, layer=None, flags=0, preScriptID=0, ignoreLayers=[])

Establish products using page templates.

Here you will find a short tutorial on product establishing using page templates.

Parameters:

  • products (list[CProduct]) – The products to establish

  • pageTemplateID (int) –

    Initial page template to use for building.

    Page breaks are achieved by inserting products with kProductType = 4 (page template) into the product list.

    Here you will find an example (CScript).

  • templateID (int) –

    Template to use for building product(s).

    See kPreferDefaultPageItem for more information

  • page (None | int | CPage) –

    The page to start establishing the products on.

    • None: The current page of the current script document

    • int: Page index of the current script document

    • CPage: A target page

    InDesign® comet_pdf® Using InDesign® Server or comet_pdf the current front page is undefined!

  • layer (None | str | CLayer) –

    The layer to build the products on.

    • None: Current front layer

    When the layer type is str, this is the name of the desired layer.

    When the layer type is CLayer, it must belong to the same document as the parameter page.

  • flags (int) –

    Build flags to customize the build process.

    • constants.kPreferDefaultPageItem:

      Use templateID for all products. Otherwise templateID is used only for products with no template given.

    • constants.kSkipEmptyTemplates:

      Skip products with no template defined.

    • constants.kShowProgress:

      Show progress bar

    • constants.kCheckIfNotExists:

      Check whether a product already exists in the document and skip inserting if so.

    • constants.kAutoDetectType:

      While inserting templates as text we have two possibilities: Insert a frame as inline or insert the frames (text) content.

      With constants.kAutoDetectType set, the following is done: Insert the text content if the frame is a text frame and inserted the frame as an inline otherwise.

    • constants.kSuppressAlerts:

      Suppress alerts while building products. Some alerts like ‘Object will leave the paste board’ are too deep inside InDesign® and cannot be suppressed!

    • constants.kIgnoreErrors:

      Ignore errors and continue. This may leave gaps in page elements. Reorganizing the document again will fill these gaps.

    • constants.kPreferExistingPages:

      If document pages are already linked against page templates, prefer these page templates instead of the the page template given in pageTemplateID.

      When the last page is reached, the normal page templates successor rules are used.

    • constants.kPreferProductPT:

      Products may contain a page template. Product page templates are shown (delimited by an @) behind the products template in the product pool.

      The page template is given by the panelstatements in the column gridID. Every page template will create a page break.

      Products without a page template will use the standard page template as given above. ATTENTION : This version of Comet does NOT support page breaks to specific page type (left, right pages)!

    • constants.kLoadMasterItems:

      Override and link all master page frames linked with place holders after successfully building all products.

      In this case, we walk through all pages of the document. The document will remember whether the flag is set or not : If the flag is set, all subsequent reorganizations will walk through the master pages items too.

  • preScriptID (int) –

    ID of the preparation script.

    The script is executed in that the list of the products to be imported is determined and can then be used to process the product list.

    For more see product::set, product::clone, productlist and on chapter Script support.

    • 0: Don’t execute a prescript

  • ignoreLayers (list[str | CLayer]) –

    List of layers to ignore.

    Newly inserted products may overlay frames of these layers.

    The entries of this list may be of the following types:

    • CLayer: A document layer. Must belong to the same document as the target layer or page

    • str: A layer name. There are some special keywords which may be provided instead of an actual name:

      • ’invisibles’ : All invisible layers

      • ’except name’ : All except layer name

      • ’behind name’ : All behind layer name

      • ’background’ : The bottommost layer

Return type:

None

Available:

InDesign® comet_pdf®

CScript:

productlist::establish

comet.product.getEstablished(start=None)

Ascertain the products built in a document and the page templates used for building these products.

Parameters:

start (None | int | CDocument | tuple[CDocument, int] | CPage | CPageItem) –

Where to start searching for built products.

The parameter type can be:

  • None

    Use the current active script document at start page index 0

  • int

    Use the current active script document with this value as the start page index

  • CDocument

    Use this document at start page index 0

  • tuple [CDocument, int]

    Use this document and the provided int as the start page index

  • CPage

    Use this page as the start page

  • CPageItem

    Start search at this item

Returns:

The found products and page templates

Return type:

list[CProduct]

Raises:
Available:

InDesign® comet_pdf®

CScript:

productlist::get_established

comet.product.reorganize(document=None, products=None, firstItem=None, page=None, flags=65536, firstEntry=None)

Reorganization of a document.

Parameters:

  • document –

    The document.

    Parameter type options:

    • None

      Use the script document (gDocument).

    • CDocument

      Use the provided document.

  • products (list[CProduct] | None) –

    List of products in the document (e.g. from getEstablished()).

    • None: Determine the products directly from the document.

  • firstItem (CPageItem | None) –

    Start reorganizing at the comet group of this frame.

    • None: Ignore the parameter and clean up the entire document.

  • page (CPage | int) –

    Clean up this page only.

    Parameter type options:

    • None

      Ignore the parameter.

    • CPage

      The page to reorganize.

    • int:

      • > 0: page index.

        In this case, the firstItem and products parameters are ignored.

        The call corresponds to the “Reorganize page” menu command.

        If the singlePages flag is also set, the call corresponds to the “Fill and reorganize page” menu command.

      • -2:

        Only tidy up the page on which either the first frame of the first product of products or (if products is empty) the frame firstItem is located.

        If both entries are empty, the first page of the document is reorganized up.

    • None

      Ignore the parameter. The entire document is cleaned up (possibly starting after firstItem).

  • flags (int) –

    Flags

    • constants.kShowProgress

      Show progress bar.

    • constants.kReloadAll

      Suppress the copying of texts and images between frames of friendly templates and the same identifiers when changing templates.

    • constants.kSuppressAlerts

      Suppress messages and warnings. Some messages such as “These values would cause an object to be displaced from the workspace” are so deeply embedded in InDesign® that they unfortunately cannot be suppressed by plugins.

    • constants.kIgnoreErrors

      Ignore errors during build. Incorrect products can create ‘holes’ in the layout. These holes can be filled by reorganizing the document.

    • constants.kPreferExistingPages

      Document pages that are already linked to a page template use this page template for structure and reorganization. Once the last page has been reached, the process continues according to the page template successor rule.

    • constants.kLoadMasterItems

      Linked master page frames are automatically released and loaded after cleanup.

      All pages of the document are processed. If the last product build was made with this flag, the option (and in particular its absence) has no meaning: In this case, the master page frames are always cleared and/or loaded.

      Released master page frames always lie over the frames that have not been released and may cover them. If necessary, frames that are to be in the foreground must be provided with an empty placeholder and arranged accordingly.

    • constants.kFillPage

      When parameter page is not None and the page index is >= 0: Fill page before reorganizing.

    • constants.kCropPage

      When parameter page is not None and the page index is >= 0: Crop page at the same time. Product structure page breaks are inserted before and after the page.

  • firstEntry (CProduct | None) –

    Reorganize from the given entry to the end of products.

    • None: Ignore parameter.

    • CProduct: Valid entry of the product list products.

      The parameters firstItem and page are ignored in this case.

Raises:

  • TypeError – When parameter types are invalid

  • CometError – On internal error. The error description contains information about which product failed and an additional error description.

Available:

InDesign® comet_pdf®

CScript:

productlist::reorganize

comet.product.setBuildTrace(enable=1, showNails=-2, showUIDs=-2, showEdges=-2, resolution=0.0)

(De)activate build tracing.

Build tracing is deactivated automatically after InDesign® restarts!

Build tracing may significantly slow down the product building process. Images are created in the folder $CACHE/BuildTrace. Don’t forget to clear this folder from time to time.

Parameters:

  • enable (int) –

    Activate build tracing?

    • -2: Leave untouched

    • -1: Toggle

    • 0: Off

    • 1: On

  • showNails (int) –

    Show nails and magnets?

    • -2: Leave untouched

    • -1: Toggle

    • 0: Off

    • 1: On

  • showUIDs (int) –

    Show frame UIDs?

    • -2: Leave untouched

    • -1: Toggle

    • 0: Off

    • 1: On

  • showEdges (int) –

    Show frame edges?

    • -2: Leave untouched

    • -1: Toggle

    • 0: Off

    • 1: On

  • resolution (float) –

    Resolution of snapshots

    • 0.0: Leave untouched

    • else: Snapshot resolution in DPI.

      Values are delimited to the range (20.0 - 600.0)

Return type:

None

Raises:
Available:

InDesign®

CScript:

productlist::set_build_trace

comet.product.getBuildTrace()

Get the current values used for build tracing

Result:

The values in the following order (see parameters of setBuildTrace()):

(enabled, showNails, showUIDs, showEdges, resolution)

Return type:

tuple[bool, bool, bool, bool, float]

Available:

InDesign®

Raises:

CometError – On internal error

CScript:

productlist::get_build_trace