List of products. The list may be ascertained either using the current product research and its selections
or build up using the script. List of the current product research can be expanded.
Are entries with the same IDs permitted in the list?
0 - If the list already contains an entry with the ID of p, p
will not be inserted in the list.
1 - The entry will be inserted without checking the ID.
Since
Version 1.2.2 (24 Nov. 2004)
Available
priint:comet InDesign® Plug-Ins, comet_pdf
static int insert( ProductList pl, Product p, int index, int allowDoubles = 1)
Insert in front of this position. The position is 0-based. To append an object
to the list, use append or the Index -1.
allowDoubles
int
1
Are entries with the same IDs permitted in the list?
0 - If the list already contains an entry with the ID of p, p
will not be inserted in the list.
1 - The entry will be inserted without checking the ID.
Remove an object from the list. The object at the defined list position will be removed from the list.
The product itself is not automatically deleted upon removal from the list.
Move the current list pointer toe position onwards and get the next object of the list.
The call is dependent on either first or last and some prev calls.
Move the current list pointer toe position onwards and get the next object of the list.
The call is dependent on either first or last and some next calls.
static int build_list( ProductList pl, int flags = 0, char* errmess = 0, ItemRef baseFrame = 0, int removeFrame = 0, int pageNum = -1, char* layerName = "", char* defaultMasterpage = "", int gridID = 0, int pageitemID = 0, int anchor = 0, float left = 0.0, float top = 0.0, float right = 0.0, float bottom = 0.0, int purgeSequence = 0, char* sequName = "", int preScript = kNoRule)
Product build. Like document::build_products, but the first argument is a ProductList. No prescript is executed. You may prepare your products inside the script instead.
Multiple products removed from the list by default.
This statement is prefered to use in a faceless InDesign® Server environment. In all other situations use the
(faster) statement document::build_products please. The only exceptions are if you fill the productlist inside the script or if you want to make
some special changes inside the resulting list from productlist::get.
complete path to XML file
- kCSV complete path to CSV file
- kDB database or SOAP connection
- kXMLTree XMLTree
format
int
kStandardSet
Data format : Describes the expected result columns:
- kStandardSet : ID,ID2,ID3,StringID
- kExtendedSet : ID,ID2,ID3,StringID,Pageitemid
- kCustomSet self defined set. In this case, parameter values must contain a list of expected results (see product::get)
static int establish( ProductList pl, ItemRef dref = 0, int pageNum = -1, char* layer = "", int pageTemplate = 0, int pageItem = 0, int flags = 0, int preScript = 0, int singleSequences = 0, char* sequName = 0, char* errMess = 0, char* ignoreLayers = 0, int snippetMatchFlag = 0, char* snippetContext = 0, int snippetFilterFunc = 0, ...)
Product building using page templates.
Buildig products by using page templates. In the Tutorial PageBuilding you will find more information about page template based product
build-ups. Here is a flowchart of the product build-up:
Here is a flowchart of the product build:
Descriptions:
Next Item Get the next element of the input list.
The list can contain products and page templates (kProductType = 4).
Is Prrduct The product list can contain both products and page templates.
Page templates are marked by kProductType = 4 and
create a new page in the document. If the page templates has parent pages defined
the first parent page found in the document will be applied to the new page.
Fix Template
If the template of the current product has page-specific subtemplates, the subtemplate
matching the current page type is determined.
When creating continuations, the matching subtemplate of the continuations is used automatically.
Fix Page Element
Search for the next available (free) page element on the page.
In 1:N elements, it is first checked whether the element has enough space for another product.
If this is not the case, the the products built up in the element are justified horizontally and vertically
according to the settings of the element.
If a new page element has to be determined, a check is made starting behind the current (or at the first) page element of
the page template, whether already existing document frames overlap the element. The first element without frame overlaps
is used to build the product. If no free page element is found, a new page is inserted, linked to the current page template
and the first element of the new page is used.
Create New Page
Each page template in the input list automatically creates a new page. If the page template requires a
special (left or right) page, an empty page is inserted first if necessary
(e.g. if the build-up is on a left page and a page template requires a new
left page, then an additional right page is inserted).
Set PageTemplate
New created pages are linked to the current page template. If the page template contains information about parent pages,
the first parent page found in the document will be applied to the new pages.
Page Created
Was a new page created in the last action? In the vast majority of cases, only one page can be created at a time.
Only if the input list contains a page template that requires an exact page type (left, right), the necessary blank page
is additionally created in double-page documents (e.g. if the build-up is on a left page and a page template requires
a new left page, then an empty right page is additionally inserted).
Check Page Type
Check if the current document page has the page type required by the page template.
If the page template requires a left (or right) page, a blank page is inserted first if necessary
(e.g. if the build-up is on a left page and a page template requires a new left page,
then an additional blank right page is inserted).
Exec Pageitem Script
Sometimes the product template depends on the location in the document.
For example, the first product on a page should always be displayed differently from the subsequent products.
At this point of the build-up the target position of the product in the document is now clear and the template
can be calculated. Information about the script type can be found here.
Check Element Size Before
Check whether the template fits into the calculated element. The saved size information of the template is used for the check.
The actual frames of the template are not used. If the template has an expected minimum size, the minimum size is used instead
of the template size.
Only the geometric size is tested, other criteria do not play a role in the test.
To check other criteria, use the Build-Support script with the situation kCheckSizeBefore (= 1).
Build-Support
Call your Build-Support script with the given situation.
The following situations are supported:
Check Element Size After
The product template is now linked and loaded.
All its appropriate layout rules have been executed. Does the product still fit in its originally assigned location?
The bounding box of the current document frames of the product or its current continuation is used for the check.
Only the geometric size is tested, other criteria do not play a role in the check.
To check other criteria, use your Build-Support script with the situation kCheckSizeAfter (= 2).
Move Frames (to Element)
Move the frames of the product (or its continuation) to the upper left corner of the current location.
For 1:N elements, this place can also be inside the element.
Remove Frames from Grid
If the product frames were built up as part of a 1:N element, they are now also removed from the internal 'accounting'
of the element grid. (The element grid is used for the later row and column alignments of the element).
Next Page Element
Jump to the next page element. The order of the page elements is determined by the sequence number of the elements.
When the last page element is reached, a new page is automatically created and linked to the page template specified as continuation.
Prepare Oversets
Frames with overset, for which a continuation is defined,
are brought to their maximum possible height limited by the page element. If the overset is thereby resolved,
the frame is then adjusted to its content again to its content.
Frames With Overset
Is there now at least one frame with continuation that still has text overset even in its maximum height limited by the
page element?
Oversets Smaller than before
Did enlarging the frames with continuation reduce the overset?
Recursive Continue Call
The product needs a continuation.
For this purpose, the product build-up is called internally again. At the end of this call,
frames with the same key are automatically linked together in a text frames chain.
Continue Call
Is the main template of the product or a continuation inserted?
Is Textflow
Is the product built as a text flow?
Prrduct Exists ... ?
Does the product already exist in the document?
Create Textframe
There is no unique template frame available for building up the product as a text flow.
Therefore, the page element itself is used as the frame for the text.
The prerequisite is that the page template exists as a document in the data pool
(and not just its XML description).
If the corresponding page element is not a text frame, the frame is automatically converted to a text frame.
Otherwise the frame is taken over with all its text frame properties.
Any existing text in the frame is removed and replaced by the product text.
In the Template Behavior palette, you can specify whether the individual frames of the template
should be included in the text flow as inlines or whether their text content should be inserted.
You can find more information here.
Insert Template
Inserting the template into the document. Templates are always inserted at the page position (0, 0), i.e. at the top left,
and only moved later. The reason for this is that with larger templates, parts of the template can otherwise fall off
the pasteboard which may cause serious errors in InDesignInDesign®.
To avoid errors in the later determination of the text obersets, all text wraps of other frames are also temporarily
removed at this point in the product build-up.
Note: The deactivated text wraps are automatically reactivated when the product is moved to its final target position later.
At this point, the text oversets (with the now valid text wraps) are also re-determined.
In order not to make the description of the product build-up more complex, these steps are not shown in the flowchart.
Link Placeholders
Link the placeholders of all newly inserted frames and texts to the ID of the current product.
Load Placeholders
Load the contents of all placeholders of all newly inserted frames and texts.
Execute the given Layout Rules for all inserted frames.
Height changes to frames with continuations are automatically undone.
This is a Reorganisation
This branch of the product build-upo is visited only during reorganizations. The main template of the
product is moved to its newly calculated position in the document.
Continuations of the product are deleted and created again.
Not Enough Space
No page element is found that is large enough for the product (or its continuation).
Prrduct Finished
The product has been successfully inserted and built. The build process now continues with the next product (or page template).
Name
Type
Default
Description
Return
int
0 or ErrorCode.
If parameter errmess is given and allocated, it contains an error description too.
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.
int
pageItem
0
template to use for building product(s), see (kPreferDefaultPageItem for more information
int
flags
0
Customize building.
kPreferDefaultPageItem . Use pageItem for all products. Otherwise pageItem is used only for products with no pageitem given.
kSkipEmptyTemplates : Skip products with no template defined. (available since Comet 3.2 R2187)
kShowProgress show progressbar
kCheckIfNotExists : Check whether a product already exists in the document and suppress inserting if so.
kAutoDetectType : While inserting templates as text we have two possibilities : Insert a frame as inline or insert the frames (text) content.
With 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.
kSuppressAlerts Suppress alerts while building products. Some alerts like 'Object will leave the paste board' are too deep inside InDesign® and cannot suppressed!
kIgnoreErrors Ignore errors and continue. This may generate gaps in page elements. Reorganizing the document again will fill this gaps.
kPreferExistingPages If document pages are already linked against page templates, prefer this page templates instead of the the page template given in pageTemplate.
If the last page is reached, the normal page templates successor rules are used.
kPreferProductPTSince v3.3 R2731 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)!
kLoadMasterItemsSeit v3.3 R3051Override and link all parent page frames linked with placeholders after successfully building all products. In this case, we walk through all pages of the document.
The document will remember, wether the flag is set or not : If the flag is set, all subsequent reorganizations will walk through the parent pages items too.
Overriden parent items always lie above the non-overridden items
and may cover these frame. If necessary, frames that are to be in the foreground must be provided with an empty placeholder and arranged accordingly.
kSuppressLoadSince v4.1.8 R30123 Suppress loading placeholders and building repeating elements.
preScript
int
kNoRule
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.
since Comet 3.2 Any number of layer names. New products are allowed to intersect objects on this layers.
"invisibles" : All invisibles layers
"except name" : All but this
"behind name" : Alle All behind this
"background" : Background layer
0 or "" : no more layers given
otherwise : Name of layer. Ignored, if it is the active front layer of the document. If snippet parameter should be used, the list of ignoreLayers must be terminated by a '0'. Therefore, for no ignoreLayers, therefore a single '0' must be written.
snippetMatchFlags
int
kSnippetsNever
since v4.1.6 R26609 Should Comet Snippets be used? Flags can be added, e.g. kSnippetMatchesProduct + kSnippetMatchesTemplate
kSnippetsNever : No, don't use snippets kSnippetMatchesProduct : Yes, if products match kSnippetMatchesTemplate : Yes, if templates match kSnippetMatchesDocument : Yes, if documents match kSnippetMatchesLayer : Yes, if layers match kSnippetMatchesContext : Yes, if the contexts match kSnippetFallbackToTemplate : if the snippet doesn't fit the page element, use original template instead. kSnippetCreate : create non existing snippets on the fly
since v4.1.6 R26609 arbitrary string to identify a snippet's "context". This will be used for snippet search and for new snippets created during building.
snippetFilterFunc
int
0
since v4.1.6 R26609 Pointer to a function, which is executed before snippet creation to check, whether a snippet should be created for a product or not. The function must be defined in the same script (or be included from a script library) and follow this signature: int (*snippetFilterFunc)(Product p). See prefs::snippet_filter for an example
control flags.
Basically, all flags supported by productlist::establish are allowed, mainly useful in this context:
0 : ignore grid size. This also implies: ignore existing page content
kCheckGridElementSize : respect grid size
buildMessage
char *
0
buffer for build messages
Since
v4.3
Available
priint:comet InDesign® Plug-Ins, comet_pdf
static int trace_build( ItemRef docRef, int pg, char* fileName)
Add an image to the build trace. The statement is a *NOP* if the build trace is not activated. To activate the build trace, use the ProductPool flyout menu
Produktpool -> Misc -> Build Trace
Create a new list of the products built in a document and the page templates used for building these products. The result is the same list the panel
Products of document shows. if you insert new objects in this list, create them using kListOwner, see product::alloc for more information.
More information about product lists and products in lists can be found here.
Start reorganization at the Comet group of this frame.
0 : Reorganize whole document
thisPageOnly
int
0
Reorganize only this page
0 : Ignore. Reorganize complete document (starting after firstFrame if given).
Otherwise : 1-based page index. In this case firstFrame and plist are ignored.
-2 : Clean up only the page where either the first frame of the first product of plist
or (if plist is empty) the frame firstFrame is located. If both
data are empty, the first page of the document is reorganized.
This conforms to the menu "Reorganize page" or (if used with flag kFillPage) the menu "Fill and reorganize page".
flags
int
kShowProgress
Used flags
kShowProgress show progressbar
kReloadAll suppress copying contents between frames with same frame labels and same groups on template changes
kSuppressAlerts Suppress alerts while building products. Some alerts like 'Object will leave the paste board' are too deep inside InDesign® and cannot suppressed!
kIgnoreErrors Ignore errors and continue. This may generate gaps in page elements. Reorganizing the document again will fill this gaps.
kPreferExistingPages If document pages are already linked against page templates, prefer this page templates instead of the the page template given in pageTemplate.
If the last page is reached, the normal page templates successor rules are used.
kLoadMasterItemsSeit v3.3 R3051Override and link all parent page frames linked with placeholders after successfully building all products. In this case, we walk through all pages of the document.
If the last products are built using this flag, the option has no effect : Parent page items are overridden/loaded if the flag is set or not.
Overriden parent items always lie above the non-overridden items
and may cover these frame. If necessary, frames that are to be in the foreground must be provided with an empty placeholder and arranged accordingly.
kFillPagesince v3.4 R5115 and in case of thisPageOnly > 0 : Fill page before reorganizing.
kCropPagesince v3.4 R5115 and in case of thisPageOnly > 0 : Insert product-building page breaks around the reorganized page.
The function is used by the sorter to check whether two list objects are well placed in the list. At calling time a stands before b.
If you want to change the objects positions, return 1 otherwise 0.
Compare function.The function is used by the sorter to check whether
two list objects are well placed in the list. At calling time a stands before b.
If you want to change the objects positions, return 1 otherwise 0.
Do not use script global variables inside the function!
Select this popup entry (0-based with delimiter lines counted)
-1 : Do not change selection (if possible)
>= number of menu entries : Select last item
reloadProducts
int
0
Reload products?
0 : no
1 : yes
Since
v3.3 R2819, 6. Mar 2012
Available
priint:comet InDesign® Plug-Ins
static int create_snippets( ItemRef docRef = 0, int page = 0, int snippetMatchFlags = 0, char* snippetContext = 0, char* snippetLayer = 0, int snippetFilterFunc = 0)
Create Comet-Snippets from the Comet groups of a given document. Existing snippets matching the same criteria are overwritten. This means: the more specific match criteria are defined, the less snippets are affected by updates. If no matching snippet can be found, new snippet entries are created.
Comet-Snippets are only created from products without continuing frames!
0 : all pages
> 0 : only this page
-1 : Comet groups of selected frames
snippetMatchFlags
int
kSnippetsNever
since v4.1.6 R26609 Should Comet Snippets be used? Flags can be added, e.g. kSnippetMatchesProduct + kSnippetMatchesTemplate Set to -1 to show the snippet match criteria dialog.
kSnippetsNever : No, don't use snippets kSnippetMatchesProduct : Yes, if products match kSnippetMatchesTemplate : Yes, if templates match kSnippetMatchesDocument : Yes, if documents match kSnippetMatchesLayer : Yes, if layers match kSnippetMatchesContext : Yes, if the contexts match
since v4.1.6 R26609 arbitrary string to identify a snippet's "context". This will be used for snippet search and for new snippets created during building.
since v4.1.6 R26609 if provided, also snippets layer also checked against this.
snippetFilterFunc
int
0
since v4.1.6 R26609 Pointer to a function, which is executed before snippet creation to check, whether a snippet should be created for a product or not. The function must be defined in the same script (or be included from a script library) and follow this signature: int (*snippetFilterFunc)(Product p). See prefs::snippet_filter for an example.
If you think about using this function, you might be interested in further information about cscript / java interaction. Related information can be found here.
Name
Type
Default
Description
Return
char *
xml string or 0 on errors. The result string is valid until the next time a to_xml function is called and must not be changed or released.
Create a ProductList object from an xml structure.
There are two formats in which product lists can be transferred:
products.xml This format contains all the data that the products of a Product Pool know (cf. here).
The format is used in the PubServer environment and the XML description is expected as string input of this function.
items.xml.xml This format contains all the information necessary for a product buildup and reorganizations.
The format can be read only via input files.
The path is specified after a leading file: in the xml parameter of the function.
You can get valid items.xmls e.g. by using the Save button
of the panel Products of Document from a document with previously built products.
This format contains all the data that the products of a Product Pool know (cf. here).
The format is used in the PubServer environment and the XML description is expected as string input of this function.
If you think about using this function, you might be interested in further information about cscript / java interaction.
Related information can be found here.
This format contains all the information necessary for a product buildup and reorganizations.
The format can be read only via input files.
The path is specified after a leading file: in the xml parameter of the function.
You can get valid items.xmls e.g. by using the Save button
of the panel Products of Document from a document with previously built products.
"file://..."[since v4.2 R33100, not supported by Illustrator] Specification of a path to an items.xml XML file.
Please note that the syntax of an items.xml is different from a products.xml.
The following path specifications are supported:
Full paths, e.g. file:///Users/paul/Desktop/myproducts.xml
~ at the beginning of the path is replaced by the home directory ($HOME) of the current user, e.g.. file://~/Desktop/myproducts.xml
Paths starting with a defined alias, e.g. file://$DESKTOP/myproducts.xml
Incomplete paths are resolved relative to the path of the current front document (if there is such a path).
Since
4.0.5 R9650 "file://..." since v4.2 R33100, 20. Jun 2023
0 : ignore
otherwise : The variable will contain the current state (0 off, 1 on) on successful return
showNails
int*
0
Show nails and magnets in build traces?
0 : ignore
otherwise : The variable will contain the current state (0 no, 1 yes) on successful return
showUIDs
int*
0
Show frame UIDs in build traces?
0 : ignore
otherwise : The variable will contain the current state (0 no, 1 yes) on successful return
showEdges
int*
0
Show frame edges in build traces?
0 : ignore
otherwise : The variable will contain the current state (0 no, 1 yes) on successful return
resolution
float*
0
Resolution of build trace images
0 : ignore
otherwise : The variable will contain the current resolution on successful return
Since
v4.0.5 R14000, 8. Nov 2016
Available
priint:comet InDesign® Plug-Ins
static int set_build_trace( int on = -2, int showNails = -2, int showUIDs = -2, int showEdges = -2, float resolution = 0.0)
(De)activate build tracing. Build tracing is deactivated after InDesign® restarts automatically!
Build tracing may cause extremely slower building processes. Images are created in the folder $CACHE/BuildTrace.
Don't forget to trash this folder from time to time.
comet.product.get
of the panel Products of Document from a document with previously built products.