Methods to deal with the objects of the panel Product Pool.

Version :
16.10.2024, 11:40 Uhr

Methods to deal with the objects of the panel Product Pool. The modules product and productlistMethods to deal with objects of the panel Product Pool. The modules product and productlist serve in particular the placement of products in the InDesign® document including page breaks, extra spaces and advertising banners.

Building products is supported by the the following functions :

In the functions to support product building and only in this, some global variables are defined :
Name Definition range Type Description
gScriptType product building int Step of building. One of the follows :

1 kPreScript
2 kPreRule
3 kPostRule
4 kExtraPlacement
5 kTextflowPreScript
6 kTextflowPreRule
7 kTextflowPostRule

gPage int* Current destination page to place products (1-based). If the script creates new pages, change its content! To create new pages, use a call to page::create.
gMasterpage, gMasterpageL char* (read only) Parent page name. Use this value if you are creating new pages.
gMasterpageR char* (read only) Parent page name for right pages in single sided documents.
gProducts ProductList Complete list of products to build. In the pre script (kPreScript) you can manipulate this list. Use kListOwner as to be the memory location for objects of this list. More information about product lists and products in lists can be found here.
gProduct Product Current product to place in the document, only defined inside the steps kPreRule and kPostRule. If you release this this pointer, InDesign® crashes!
gIndexOffset int* Deprecated Currently used grid place (0-based). Grid places are sorted ascending by ist IDs. To jump over grid places, changes its value. If the end of the grid is reached, a new page will created by the plug-ins automatically.
gErrMess char* In case of some errors, place your description here. The description must not be longer than 1023 characters.
gPageTemplate Pre/PostRule int* Input is the ID of the current page template. Changes to the value lead to a page change. The variable is only used if gScriptType = kPreRule or kPostRule.
gPageTemplateSeq int* Input is the 1-based sequence number of the current page element. By changing the values, page elements can be skipped. The variable is only used if gScriptType = kPreRule or kPostRule.

[actions, ClassID 14]

Use this script if you want to change the list of products to be build. So you can, for instance, insert new "products" before every new product group. To manipulate this list use the functions of the modules productlist and product. Use lListOwner as to be the memory locator for objects of this list. More information about product lists and products in lists can be found here.

Inserting products with ID 0 is allowed. This products are used as to be control members, their pre and post rules are executed, but the products itself are not inserted in the document. But be aware, changes made by virtual products are lost at the first document cleaning. To get stable changes, move them to real objects (with an ID > 0).

The ID of the pre script is given in the parameter preScript of productlist::build. If no preparation is to be done, preScript is set to kNoRule.

If the pre script returns an error code, the product building will be canceled.

The following call to productlist::build call the pre script 301.

productlist::build
  (
    "watched [id3 = 1 or id3=6]",
    kUseDefaultGrid+kShowErrors,
    errMess,
    gFrame, 0,       // do not delete the anchor frame
    -1, "",          // dest page and layer
    "C-Doppelseite", // masterpage
    2, 3,            // grid and template
    1,               // anchor type
    0.0, 0.0, 0.0, 0.0,
    0,               // no single sequences 
    "%d. Produkt",   // progress
    301              // Prescript
 );

ab v3.3 R2630 You may link a so called "build support" script to every template. If a template is used to build a product in the pagetemplate based build process, this script is called in several circumstances.

Use build support script to enhance size checking of product frames (for instance to check whether a table shows at least three lines or so.). The scripts are also a good place, to insert additional frames to a product (and remove them in case of re-buildings).

Add the attribute buildSupportScript of type int and the default value 0 to the table/file pageitems. In the case of XML-Offline and SOAP/PubServer, the element must be created in all pageitems.pageitem XML nodes of pageitems.xml. After reconnecting to the data pool the feature is activated.

Scripts are implemented in table/file actions with Class-ID 48. The scripts are shown in the templates meta data dialog in the popup Build support.

    

Do not remove the current product from the list.

Changes on the current list position and adding or removing objects before the current product will lead to unexpected results.
Name Type Description
gSituation int Current calling situation. (Constants are defined in "internal/types.h")
  • kCheckSizeBefore (1) : Checking the size of the template against the page element size was successful. Commit?
    • return 0 : Yes
    • return 1 : No. The build process will jump to the next matching page element.
    gFrames and gPreviousFrames are empty in this situation.

  • kProductPlaced (5) : [Since v3.3 R4100] The product or a continuation of a product is fully loaded, built and placed now. You may implement some fine tunings here. But please take care: If the template is enlarged here, it can protrude beyond the page elements or the page margins.
    gFrames contains the inserted frames of the current template (but not the frames of already continued templates of the same product!). gPreviousFrames is empty of course.
    The return value of the function is ignored.

  • kCheckSizeAfter (2) : Checking the size of the imported and loaded product frames against the page element was successful. Commit?
    • return 0 : Yes
    • return 1 : No. The build process will jump to the next matching page element.
    gFrames contains the inserted frame. gPreviousFrames is empty.

  • kProductPlacedAndFitted (8) : [Since v4.3 R34500] The product is inserted, loaded and placed in the correct position in the document. The next step is to check whether text oversets require further continuations. But perhaps you want shorten the text by yourself, e.g. by \URL[merging equal table cells}{table.2.html#merge_equal_fr}.
    gFrames contains the inserted frames. The return value is ignored.

  • kBeforeCreateContinue (3) : Start creating a continuation. gFrames contains the inserted frame. gPreviousFrames is empty.

  • kAfterCreateContinue (4) : Successfully created a continuation. gFrames contains the inserted frame. gPreviousFrames contains the frames of the continuing template.

  • kAfterBuild (120) : The product is now fully loaded and positioned. gFrames contains all frames including all continuations of the product. The return value of the function is ignored.
    Additional frames that are created in this step are automatically assigned by an internal marker and are automatically deleted before reorganizations.
    Attention : Enlarging the products geometry is not catched by the build-up process. If you enlarge the product here, it may exceed beyond the page size.

  • kUnsolvableOversets (6) : ab v3.4 R5700 The product building process looks for unsolvable oversets since v3.4 R5700. If the overset doesn't get smaller after creating two new pages of 'continuing frames', the process gives up. To give you the possibility to mark or registers this chains, we call the build support script in that case at the very end of the building the product. The list gFrames contains the first frames of the unsolvable text chains.

  • kProductFinished (21) : since v4.0.5 R20012 After completing building and loading the product, now all text wraps and Comet notes are updated and the product frames are combined to a new Comet group. gFrames contains all inserted frames.
    You might add frames here, which should not be part of the comet group. Be careful: they will not be handled automatically in reorganization.
    The return value of the call is unused.
gPageNum int 1-based page number
gTemplateID, gTemplateName int, char* Used template.
gPageTemplateID, gPageTemplateName int, char* Used page template. Use page::templates::~ functions to get information about the page template.
gElement, gElementName int, char* 1-based page element. Use page::templates::~ functions to get information about the page element.
gGridPosX, gGridPosY float, float Since v4.0.5 R18348 Current position relative to the 1:N element
gElementLeft, gElementTop, gElementRight, gElementBottom float, float, float, float Since v4.0.5 R18348 Page relative co-ordinates of current page element in points
gFrames ItemList Currently inserted frames, see in line gSituation above.
gPreviousFrames ItemList Parent frames (on kAfterCreateContinue only).
gProducts ProductList Complete list of products to establish/reorganize.

Warnings!
  • Do not change the list nor its entries!
  • The list may contain page template entries too. Check entries using product::get (..., kProductType).
  • The list may contain entries set 'to delete' by the data pool. Check entries using product::get (..., kProductDoDelete).
gProductsDirect ProductList Since v4.0.5 R18348 Complete list of products to establish/reorganize, see gProducts one line above.

In contrast to gProducts changes made on this list, will lead to changes of the building process. To insert or delete products, use the memory allocator kListOwner for the products. More information about product lists and products in lists can be found here.

Warnings!
  • Do not remove the current product from the list.}.
  • Changes on the current list position or adding or removing objects before the current product will lead to unexpected results!
  • Additional frames will be added at every reorganization too. To avoid this, you should mark the frames (f.i. using frame::set_script_tag) and delete or re-use them, if they already exist. As an alternative you may check, whether you can use product trailers here.
gProduct Product Currently handled product. Do not change or delete! Change the products content is allowed except for the following properties: kDefined, kLevel, kLevel, kProductDocPosition, kProductTextmodel, kProductStart, kProductEnd, kProductLayer and kProductOriginals. Please note, that changes may have no effect on the building process, because they have already been read.
gProductCounter int 1-based product counter. The counter ignores page templates in gProducts. Use productlist::get_pos (gProducts, gProduct) to get the position of gProduct in gProducts.
gImporter int* Since v4.0.5 R18348 Executing product builder. The variable is defined only in situation kCheckSizeBefore, otherwise it is set to 0. Use this for product trailers value in calls to itemlist::convert_to_trailer.
gPage int* Seit v4.2 R30852 The variable supports creating additional pages while building up the products and is evaluated only in the situation kProductPlaced. If your build support script has created additional pages created, the content specifies the (1-based) page number on which the build should continue.
gNewFrames ItemList Seit v4.2 R30852 The list supports creating additional pages while building up the products and is evaluated only in the situation kProductPlaced. All frames that were created when adding new pages must be entered in the list.

May be its not surprising: The Comet group of the product is not created completelly while buiding the product of course! So functions like frame::get_cometgroup_member will not work foreseeable.

The following video shows the building of a product in all individual steps. Right before the Build support script is called, a colored frame with the name of the situation appears briefly. You may pretty well recognize when and with what situation the script is called. In the lower section of the video, each image is briefly described.

The images of the video were made with the help of the Build Trace (menu Product Pool -> Miscellaneous -> Buld trace ).

The additional images for build support situations were generated using productlist::trace_build in the build support script itself.. 

#include "internal/types.h"

int snapshot (char * name, int r, int g, int b)
{
   ItemRef 	f = item::alloc ();
   char 		tt [5000];

   strcpy (tt, "%!TT<cTypeface:37 Thin Condensed>");
   strcat (tt, "<cSize:24.000000>");
   strcat (tt, "<cFont:Helvetica Neue LT Std>");
   strcat (tt, name);

   frame::create (f, kRectangle, 36.0, 36.0, 200.0, 370.0, gPageNum);
   frame::color_rgb (f, r, g, b);
   frame::insert (f, tt);

   productlist::trace_build (0, gPageNum, name);

   frame::remove (f);
   item::release (f);

   return 0;
}

int main ()
{
   if (gSituation == kCheckSizeBefore) snapshot ("kCheckSizeBefore", 255, 0, 0);
   if (gSituation == kProductPlaced) snapshot ("kProductPlaced", 255, 128, 0);
   if (gSituation == kCheckSizeAfter) snapshot ("kCheckSizeAfter", 0, 255, 0);
   if (gSituation == kBeforeCreateContinue) snapshot ("kBeforeCreateContinue", 128, 255, 0);
   if (gSituation == kAfterCreateContinue) snapshot ("kAfterCreateContinue", 0, 0, 255);
   if (gSituation == kAfterBuild) snapshot ("kAfterBuild", 0, 128, 255);
   if (gSituation == kUnsolvableOversets) snapshot ("kUnsolvableOversets", 255, 255, 0);
   if (gSituation == kProductFinished) snapshot ("kProductFinished", 0, 255, 255);

   return 0;
}

A nice application of the buildsupport script are the so-called product trailers, which are to separate built up products according to certain criteria. Here you will find a detailed description.

Do not use the second page element. 

#include "internal/types.h"

int main ()
{	
   int		result = 0;

   if (gSituation == kCheckSizeBefore && gElement == 2) result = 1;
   return result;
}

Insert a frame with "See page .. for continuation." to every sub template with a continuation. 

#include "internal/types.h"

int main ()
{
   ItemRef	frame 		= item::alloc ();
   ItemRef	fr 			= item::alloc ();
   ItemRef	fr2 		= item::alloc ();
   ItemList	inserted 	= 0;
   float	l, t, r, b;
   char		txt [5000];
   int		result 		= 0;

   if (!gFrames) return 0;
   if (!itemlist::length (gFrames)) return 0;
   if (!itemlist::get (gFrames, frame, 0)) return 0;
   if (!frame::is_valid (frame))	 return 0;

   // CheckSizeBefore
   // 	Delete frames created on kBeforeCreateContinue
   while (1)
   {
      if (gSituation != kCheckSizeBefore) break;
			
      frame::get_cometgroup_member (frame, "Z", fr);
      if (!frame::is_valid (fr)) break;
	
      frame::remove (fr);
	
      break;
   }

   // CheckSizeAfter
   while (1)
   {
      if (gSituation != kCheckSizeAfter) break;
	
      break;
   }

   // BeforeCreateContinue
   while (1)
   {
      // Create the text frame.
      if (gSituation != kBeforeCreateContinue)	break;

      frame::get_cometgroup_member (frame, "E", fr);
      if (!frame::is_valid (fr)) break;

      if (!textmodel::overset (fr)) break;

      // Template 472 contains exactly one text frame with Comet label "Z" and two layout rules
      // to justify the frame at frame "E"
      frame::bbox (fr, &l, &t, &r, &b);
      inserted = document::place_items (0, "", "", 472, l, t, page::get (fr));
      if (inserted) itemlist::release (inserted);

      break;
   }

   // AfterCreateContinue
   while (1)
   {
      if (gSituation != kAfterCreateContinue) break;

      sprintf (txt, "See page %d for continuation", page::get (frame));

      if (!itemlist::length (gPreviousFrames))	break;
      if (!itemlist::get (gPreviousFrames, fr,0)) break;
      if (!frame::is_valid (fr)) break;
      frame::get_cometgroup_member (fr, "Z", fr);
      if (!frame::is_valid (fr)) break;

      frame::replace (fr, txt);

      break;
   }

   return result;
}

The example shows how additional pages can be append to a product. Please note that creating additional pages is supported only in the kProductPlaced situation. Additionally created frames are not part of the Comet Group of the product.

A page template must be defined for newly created pages!

The script creates three additional pages behind the product, each with a new frame. 

#include "internal/types.h"

int main ()
{
   ItemRef   fr    = item::alloc ();
   int       i;
   char      txt [255];

   while (1)
   {
      if (gSituation == kProductPlaced)
      {
         if (!gFrames)      break;

         page::create (3, gPageNum+1); // Create 3 pages
         for (i = 1; i < 4; i++)
         {
            page::set_info (0, gPageNum+i, "id", gPageTemplateID); // Define the page template

            sprintf (txt, "Pg. %d", gPageNum+i);
            frame::create (fr, kRectangle, 0.0, 0.0, 200.0, 200.0, gPageNum+i);
            frame::replace (fr, txt);
            frame::color_rgb (fr, 255, 128, 0);
            itemlist::append (gNewFrames, fr); // Register new created frame
         }
         *gPage    = *gPage + 3; // Set the new page number
      }

      break;
   }

   return 0;
}

since v3.3 R2630 Before inserting a product into the document the build process can calculate an alternative template ID. Imagine, you want to use a different template for every first product of a page. In this case you can use a script to change the used template ID on the fly.

In the page templates dialog you can set the script to calculate the substition using the popup "Substitution". The script is used for all templates of a template group (left, right, continues).

If you use alternative templates, please do not forget to do inverse calculations in the substition too : If template A uses the subsition B and falls into an A-place after reorganization, B must be replaced by A.

Set all new values to 0 by default. The features will be turned on after re-logging.

The scripts itself are defined in table/xml file actions with class ID 15. All actions of this class ID are shown in the popup "Substitution" of the templates dialog.

Name Type Description
gPageitemID int* Current template ID. Change this to use a substitution.
gPositionX_out, gPositionY_out float* If a Repeating Element is inserted, the variables contain the current XY position in points at which the element will be inserted. Changes to the values must be confirmed with *gPosition_changed = 1; in the script.
gPosition_changed int* If a Repeating Element is to be placed at a different position, change the values of of gPositionX_out and gPosition_out accordingly and confirm the changes with *gPosition_changed = 1;.
gPageitemName char* seit v3.3 R2630 Name of template

"" on calls out side the build process (drag and drop, ...)
gPage int 1-based page number to insert the template
gLayer char* Name of layer to insert the template
gPositionX, gPositionY float, float Position in points

Attention If we are inside a 1:N page element, this position is not the final landing position in most cases! (In fact, this position depends on the template!)
gGridPosX, gGridPosY float, float seit v3.3 R2630 Position relative to the page element

Attention If we are inside a 1:N page element, this position is not the final landing position in most cases! (In fact, this position depends on the template!)

0.0, 0.0 : on calls out side the build process (drag and drop, ...)
gElementLeft, gElementTop, gElementRight, gElementBottom float, float, float, float seit v3.3 R2630 Current page element coordinates
gElement, gElementName int, char* seit v3.3 R2630 Current page element. Check gGridPosX and gGridPosX in case of 1:N elements!
gPageTemplateID, gPageTemplateName int, char* seit v3.3 R2630 Current page template

0, "" : on calls out side the build process (drag and drop, ...)
gProducts, gProduct, gProductCounter Product, ProductList, int seit v3.3.1 R3226 Current product information in case of building or reorganizing pages. Otherwise empty.

Versions prior 3.3 calling this script only once - even before the template in placed into the document. gPositionX and gPositionY are set to 0.0 always. And a lot of other variables are not defined gElement, ...). For backward compatibility please check the comet version : 

    if (fval (system::comet_version ()) > 3.2)

Use an alternative template for every first product of a page. (If you use layout layers, you have to remove all frames from pl too!) 

    ItemList pl = itemlist::pageframes (gPage);
    :
    if (itemlist::length (pl) == 0)
    :

Use an alternative template for every first product of a page. The script also contains the inverse calculations. 

int main ()
{	
    if (datapool::get_main_template (*gPageitemID) == 468)
    {
        if (gElement == 1 && gGridPosX == 0.0 && gGridPosY == 0.0)
        {
            *gPageitemID = 399;
        }
    }
    else if (datapool::get_main_template (*gPageitemID) == 399)
    {
        if (gElement > 1 || gGridPosX != 0.0 || gGridPosY != 0.0)
        {
            *gPageitemID = 468;
        }
    }

    return 0;
}

Change the first and the last template of every chapter of products. 

#include "internal/products.h"

int 	stFirst	= 210;
int		stInner	= 206;
int		stLast	= 214;

int main ()
{
    int			pos	= -1;
    Product		p;
	
    *gPageitemID = stInner;
	
    while (1)
    {
        // First product of chapter?
        pos = productlist::get_pos (gProducts, gProduct, 1);
        if (pos < 0)	break;

        p = productlist::prev (gProducts);
        if (!p || product::get (p, kProductType) == 4)
        {
            *gPageitemID = stFirst;
            break;
        }

        // Last product of chapter?
        pos = productlist::get_pos (gProducts, gProduct, 1);
        if (pos < 0)	break;

        p = productlist::next (gProducts);
        if (!p || product::get (p, kProductType) == 4)
        {
            *gPageitemID = stLast;
            break;
        }

        break;
    }

    return 0;
}

since v3.3 R2690 Products can be placed into product defined page elements. If the product has an element defined, the build process uses the given page element instead of the next free element. If the products element is used already or too small, a new page is created automatically.

1:N elements are not suitable as product defined page elements. The conflict between element and product controlled placements has no unique solution.

You can use smaller sequence numbers for "backward" placings.

Contininuing templates using the next element, not the element given in the product (Otherwise every continuation would create a new page.)

No further installations needed.

Elements are always defined by their (1-based) sequence number. There are three ways to set an element:

Set next to last column of the panel- or findstatement to the desired value. See here for more info about the output columns of the product loading statements.

Use product::set with selector kElementid to define the sequence number.

A nagative element id is interpreted as an action ID. The action calculates (or not) the element id.

Use -20045 as element id to execute action 20045.

The following global variables are defined in the scripts :
Variable Typ Description
gPageNum int current page number (1-based)

Using InDesign® Server or comet_pdf the current front page is undefined!
gTemplateID int current template
gTemplateName char*
gPageTemplateID int current page template
gPageTemplateName char*
gElement int current page element
gElementName char*
gSeq int* Change this to use a different page element.

Jump over the second element. 

int main ()
{	
    if (*gSeq == 2) *gSeq = 3;

    return 0;
}

see here.

static Product alloc(int mem_loc = kScriptOwner)

Create a new empty object of type Product. All fields of the new object are initialized with 0 or "".

Product lists containing kScriptOwner entries, must by cleared or released using delete_items set == 0.

More information about product lists and products in lists can be found here.

Name Type Default Description
Return Product   new created and product
mem_loc int kScriptStack Intention to use, see here

kListOwner - in product list
kScriptOwner - directly in script
#include "internal/types.h"

Version 1.2.2 (24. Nov. 2004)

priint:comet InDesign® Plug-Ins, comet_pdf

release
productlist::clear
productlist::insert
productlist::append
clone

static Product clone(Product org, int mem_loc = kScriptOwner)

Create a copy of an existing product.

Product lists containing kScriptOwner entries, must by cleared or released using delete_items set == 0.

More information about product lists and products in lists can be found here.

Name Type Default Description
Return Product   new created product
org Product - orginal Product to copy from
mem_loc int kScriptStack Intention to use, see here

kListOwner - in product list
kScriptOwner - directly in script
#include "internal/types.h"

Version 1.2.2 (24. Nov. 2004)

priint:comet InDesign® Plug-Ins, comet_pdf

release
productlist::clear
productlist::insert
productlist::append
clone

static void release(Product p, int mem_loc = kScriptStack)

Release a product. If you release a product of a list, don't forget to remove it from this list before!

Take care to use the same memory hint mem_loc for allocation and release! More information about product lists and products in lists can be found here.

Name Type Default Description
mem_loc int kScriptStack Type of allocation, see here

kListOwner - in product list
kScriptOwner - directly in script
#include "internal/types.h"

Version 1.2.2 (24. Nov. 2004)

priint:comet InDesign® Plug-Ins, comet_pdf

productlist::clear
productlist::remove

static void set(
  Product p,
  int selector,
  int v)

Change a product value. You need the include

#include "internal/products.h"

Name Type Default Description
p Product - valid product
selector int - Value to change

kID (int)
kID2 (int)
kID3 (int)
kStringID (String or char*)
kPageitemid (int)
kDocid (int)
kMasterpage (String or char*) Used in Page Template objects only
Deprecated kGrid (String or char*)
Deprecated kGridid (int)
Deprecated kElement (String or char*)
Deprecated kElementid (int)
Deprecated kNeedsrequest (int)
Deprecated kDefined (int)
kLevel (int) - Tree view level in panel Product Pool. In Scripts for loading the Product Pool the value is used to define the products icons in the panel.
kSubstatement (int) - Panlestatement to load sub entries
kClassid (int)
kRow1 (String or char*)- First row shown in panel Product Pool
kRow2 ( (String or char*) - Second row shown in panel Product Pool
kPreRuleid (int)
    kNoRule
    Deprecated kNewPage
    Deprecated kNewLeftPage
    \Deprecated span[keyword]{kNewRightPage}
    otherwise : ID of script to execute
Deprecated kPreRuleparams (String or char*)
kPostRuleid (int)
    kNoRule
    otherwise : ID of script to execute
Deprecated kPostRuleparams (String or char*)
Deprecated kAdparams (String or char*) -Additional infos for banners
kProductDocPosition (int) since v3.3, R3144, 4. Sept. 2012
kProductToDelete (int) since v3.3, R3144, 4. Sept. 2012

kProductKeepWithNext (int) ab v4.2 R31672, 26. Sep. 2022 Keep product together with next product in the list. The setting is supported only if the template used has no defined continuation. Only two products can be held together at a time!

kProductInfos1, kProductInfos2 (String or char*) ab v4.1.6 R26627 Content for Infos1 resp. Infos2 for the placeholders of the product template. Values are set before the placeholders are loaded.

kProductApplyInfos1 (int) ab v4.1.6 R26627 In which placeholders should Infos1 resp. Infos2 be set?
  • 0 : Nothing
  • 1 : Text
  • 2 : Frame
  • 3 : All
since Comet 3.2, R 2110, 7. Sept. 2010 Use the following selectors for calls to productlist::reorganization
kSnippetAttr (String or char*)
kProductTextmodel (ItemRef)
kProductStart (int)
kProductEnd (int)
kProductType (int)
  • 0 : Normal
  • 1 : New product
  • 2 : Moved
  • 3 : Removed
  • 4 : Page Template. The ID of the page template is set with kID.
  • 5 : Snippet. The ID of the page template is set with kID and the config file snippets.xml must exist.

kProductLayer (ItemRef)
kProductTagID1 (int)
kProductTagID2 (int)
kProductPageType (int)
    0 : left page
    1 : any (new) page
    2 : right page
kProductOriginals (ItemList)

since Comet 3.1, R 1724, 5. Feb. 2009 Use the following selectors to define the entries of gProducts used in scripts for the preview panel kID (int)
kID2 (int)
kID3 (int)
kStringID (String or char*)
kPreviewName (String or char*)
kPreviewPath (String or char*)
kPreviewFormat (String or char*)
kPreviewWidth (String or char*)
kPreviewHeight (int)
kPreviewResolution (String or char*)
kPreviewBitDepth (int)
kPreviewTextName (String or char*)
kPreviewInfo1 (String or char*)
kPreviewInfo2 (String or char*)
kPreviewText (String or char*)
kPreviewClassID (int)
kPreviewToDelete (int)
kPreviewSnippetTable (String or char*)
kPreviewSnippetAttribute (String or char*)
kPreviewButtonState (int), since v3.2.2
kPreviewLinkScript (int), since v3.2.2
v int/char* - new value to set. The data type depends on the selector, see below. Non matching data types may cause serious errors.  
#include "internal/products.h"

Page template entries in gProducts will create page breaks. The examples shows, how to create a page template entry: 

Product  p = product::alloc (kScriptStack);
 
:

product::set (p, kProductType, 4);
product::set (p, kID, your_pagetemplate_id);
 
// ... and if you want a left page ... 
product::set (p, kProductPageType, 0);

Place every currently selected product a its own left page. 

#include "internal/types.h"
#include "internal/products.h"

int main()
{
    ProductList	pl = productlist::get ("selected");
    Product		p;
    Product		p2;
    int 		i;

    for (i=0; i < productlist::length(pl); i++)
    {
        p2 = product::alloc (kScriptStack);
        product::set (p2, kProductType, 4);
        product::set (p2, kID, your_page_template-id);
        product::set (p2, kProductPageType, 0);
        productlist::insert (pl, p2, i, 1);
        i = i + 1;
    }

    productlist::establish(pl, 0, 0, "", 1, 0, kShowProgress, 0, 0, "", 0, 0);

    productlist::release(pl);
    return 0;
}

Version 1.2.2 (24. Nov. 2004)

priint:comet InDesign® Plug-Ins, comet_pdf

get
gets

static int get(Product p, int selector)

Get an int value out of a product. You need the include

#include "internal/products.h"

Name Type Default Description
Return int   current value of selector. Its a read only, DO NOT CHANGE. Subsequent calls to the function will override this value!
p Product - valid product
selector int - kID
kID2
kID3
kPageitemid
kDocid
Deprecated kGridid
Deprecated kElementid
Deprecated kNeedsrequest
Deprecated kDefined
kLevel (int) - tree view level in panel Product Pool
kSubstatement
kClassid
kPreRuleid
kPostRuleid
kProductDocPosition (int) since v3.3, R3144, 4. Sept. 2012
kProductToDelete (int) since v3.3, R3144, 4. Sept. 2012

kProductKeepWithNext (int) ab v4.2 R31672, 26. Sep. 2022 Keep product together with next product in the list. The setting is supported only if the template used has no defined continuation. Only two products can be held together at a time!

kProductApplyInfos1, kProductApplyInfos2 ab v4.1.6 R26627 In which placeholders should Infos1 resp. Infos2 be set? The values are only used when inserting templates and are not read from the document.
  • 0 : Nothing
  • 1 : Text
  • 2 : Frame
  • 3 : All
since Comet 3.2, R 2110, 7. Sept. 2010 Use the following selectors for calls to productlist::reorganization
kProductStart (int)
kProductEnd (int)
kProductType (int)
  • 0 : Normal
  • 1 : New product
  • 2 : Moved
  • 3 : Removed
  • 4 : Page Template. The ID of the page template is set with kID.
  • 5 : Snippet. The ID of the page template is set with kID and the config file snippets.xml must exist.

kProductTagID1 (int)
kProductTagID2 (int)
kProductPageType (int)

since Comet 3.1, R 1724, 5. Feb. 2009 Use the following selectors to retrieve values from objects of gProducts used in scripts for the preview panel kID (int)
kID2 (int)
kID3 (int)
kPreviewHeight (int)
kPreviewBitDepth (int)
kPreviewClassID (int)
kPreviewToDelete (int)
kPreviewButtonState (int), since v3.2.2
kPreviewLinkScript (int), since v3.2.2
#include "internal/products.h"

Version 1.2.2 (24. Nov. 2004)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

gets
set
comet.CProduct.getAttribute
comet.CProduct.getID
comet.CProduct.getName

static char* gets(Product p, int selector)

Get an string value out of a product. You need the include

#include "internal/products.h"

Name Type Default Description
Return char*   current value of selector

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to learn more about functions returning r/o char* values.

On errors, an empty string is return.
p Product - valid product
selector int - What value of the object should be determined?

kStringID
kMasterpage Used in PageTemplate objects only
Deprecated kGrid
Deprecated kElement
kRow1 (char*)- First row shown in panel Product Pool
kRow2 ( (char*) - Second row shown in panel Product Pool
kPreRuleparams
kPostRuleparams
kAdparams
kSnippetAttr (char*)

kProductInfos1, kProductInfos2 (String oder char*) ab v4.1.6 R26627 Content for Infos1 resp. Infos2 for the placeholders in the product template. The values are only used when inserting templates and are not read from the document.

since Comet 3.1, R 1724, 5. Feb. 2009 Use the following selectors to retrieve values from objects of gProducts used in scripts for the preview panel kStringID (char*)
kPreviewName (char*)
kPreviewPath (char*)
kPreviewFormat (char*)
kPreviewWidth (char*)
kPreviewResolution (char*)
kPreviewTextName (char*)
kPreviewInfo1 (char*)
kPreviewInfo2 (char*)
kPreviewText (char*)
kPreviewSnippetTable (char*)
kPreviewSnippetAttribute (char*)
#include "internal/products.h"

Version 1.2.2 (24. Nov. 2004)

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get
set
comet.CProduct.getAttribute
comet.CProduct.getID
comet.CProduct.getName

static int get_itemref(
  Product p,
  int selector,
  ItemRef result = 0)

Get an string value out of a product. You need the include

#include "internal/products.h"

Name Type Default Description
Return int   0 or ErrorCode
p Product - Valid product
selector int - Slot to change

kProductTextmodel
kProductLayer
result ItemRef 0 allocated ItemRef for the result (or 0)
#include "internal/products.h"

Version 3.2 R2110, 7. Sept. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

get
set

static int get_itemlist(
  Product p,
  int selector,
  ItemList result = 0)

Get an ItemList value out of a product. You need the include

#include "internal/products.h"

Name Type Default Description
Return int   0 or ErrorCode
p Product - Valid product
selector int - Slot to change

kProductOriginals
result ItemList 0 allocated ItemList for the result list (or 0)
#include "internal/products.h"

Version 3.2 R2110, 7. Sept. 2010

priint:comet InDesign® Plug-Ins, comet_pdf

get
set

static int get_parent(Product parent, Product p)

Get the parent object of a given product. In a first step the visible entries of the panel Product Pool are inspected. If the given object is not visible sub products must be loaded recursively. This process may take a while!

To find parent objects, at least the first level products of the Product Pool must be loaded. If this list is empty, the function will return itemEmpty error (1116).

Different entries of the Product Pool may return differnt parents! If the Product Pool contains non unique IDs, the first product is used.

Name Type Default Description
Return int   0 or Fehlercode

1116 : No parent found. make sure that the Product Pool is visible and loaded.
parent Product - allocted Product for the result
⇨ defined by a product
p Product - product to get the parent from
⇨ defined by id
id int - ID1
id2 int - ID2
id3 int - ID3
sid String or char* - StringID
#include "internal/products.h"
#include "internal/products.h"

int w_product (Product p, char * trailer)
{
    wlog ("", "%s[%d, %d, %d, '%s']\n",
     		trailer,
     		product::get (p, kID),
     		product::get (p, kID2),
     		product::get (p, kID3),
     		product::gets (p, kStringID));

    return 0;
}

int main ()
{
    int			id			= 1;
    int			id2			= 0;
    int			id3			= 0;
    char	*	sid			= "100014";

    Product		parent		= product::alloc ();
    Product		p;
    ProductList	children	= productlist::alloc ();

    product::get_parent (parent, id, id2, id3, sid);
    product::get_children (children, id, id2, id3, sid);

    w_product (parent, "  ");
    wlog ("", "    [%d, %d, %d, '%s']\n", id, id2, id3, sid);
    for (p = productlist::first (children); p; p = productlist::next (children)) w_product (p, "      ");

    return 0;
}

Version 3.2.3 R2485, 1. Jun. 2011

priint:comet InDesign® Plug-Ins

static int get_children(ProductList children, Product p)

Get the children of a given product. In a first step the visible entries of the panel Product Pool are inspected. If the given object is not visible sub products must be loaded recursively. This process may take a while!

To find children, at least the first level products of the Product Pool must be loaded. If this list is empty, the function will return itemEmpty error (1116).

Different entries of the Product Pool may return differnt children! If the Product pool contains non unique IDs, the first product is used.

Name Type Default Description
Return int   0 or Fehlercode

1116 : No parent found. make sure that the Product pool is visible and loaded.
children ProductList - allocted list for the result. Old list members are deleted.
⇨ defined by a product
p Product - product to get the parent from
⇨ defined by id
id int - ID1
id2 int - ID2
id3 int - ID3
sid String or char* - StringID
#include "internal/products.h"
#include "internal/products.h"

int w_product (Product p, char * trailer)
{
    wlog ("", "%s[%d, %d, %d, '%s']\n",
     		trailer,
     		product::get (p, kID),
     		product::get (p, kID2),
     		product::get (p, kID3),
     		product::gets (p, kStringID));

    return 0;
}

int main ()
{
    int			id		= 1;
    int			id2		= 0;
    int			id3		= 0;
    char		*	sid		= "100014";

    Product		parent	= product::alloc ();
    Product		p;
    ProductList	children	= productlist::alloc ();

    product::get_parent (parent, id, id2, id3, sid);
    product::get_children (children, id, id2, id3, sid);

    w_product (parent, "  ");
    wlog ("", "    [%d, %d, %d, '%s']\n", id, id2, id3, sid);
    for (p = productlist::first (children); p; p = productlist::next (children)) w_product (p, "      ");

    return 0;
}

Version 3.2.3 R2485, 1. Jun. 2011

priint:comet InDesign® Plug-Ins

static char* to_xml(Product object, char* rootElementName = "product")

Generate a XML structure of a Product object.

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.
product Product - object  
rootElementName String or char* product name of the root element

4.0.5 R9650
comet.publication.toXMLProduct

static Product from_xml(char* xml)

Create a Product object from a xml structure.

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 Product   object of type Product. This object must be released using product::release.
xml String or char* - xml structure

4.0.5 R9650
comet.publication.fromXMLProduct

static int copy(Product destination, Product source)

Copy all values from object source to object destination.

Name Type Default Description
Return int   0 or error code
destination Product - source object
destination Product - destination object

4.0.5 R9700

static int relink(
  Product product,
  int mappingFunction,
  int reloadPlaceholders = 0)

Find all placeholders of a product and relink them to a new ID

This function searches all placeholders of a product and relinks the placeholders to a mapped ID using the function provided as parameter.

The mapping function must match the following signature: 

int myMappingFunction(IDType in, IDType out);
The following rules apply

Name Type Default Description
Return int   0 or error code
product Product - product to relink
mappingFunction int - callback function for ID mapping
reloadPlaceholders int 0 reload placeholders after relinking (1) or not (0)

Change the ID1 of all placeholders of a product, if not equals 1: 

int normalizeId1(IDType in, IDType out)
{
    if (idtype::id(in) != 1)
    {
        idtype::set_id(out, 1);
        return 1;
    }
    return 0;

}

int main() 
{
    ProductList 	products	= productlist::get_established();
    int 			i 			= 0;
    int 			c 			= productlist::length(products);
    Product 		p 			= 0;

    for (; i < c; ++i)
    {
        p = productlist::get_nth (products, i);
        product::relink(p, normalizeId1);
    }

    productlist::release(products);

    return 0;
}

4.1.7 R26615
itemlist::relink

static int get_pageitem_type(Product product)

Get the page type of the template used to build this product.

Name Type Default Description
Return int   kUndefPage, kLeftPage, kUnisexPage or kRightPage (all defined in "internal/types.h")
product Product - product to check

4.1.6 R26615

Preconditions
#include "internal/types.h"
#include "internal/products.h"

Author
Paul Seidel
Version
16.10.2024, 11:40 Uhr
Since
Version 1.2.2 (24. Nov. 2004)
See Also
productlist
document::build_products

Alphabetic index HTML hierarchy of classes or Java