Skip to main content

Concepts

Overview​

Product List by Rule builds the product list of a document from XML rules instead of a custom CScript build script. You describe how products are collected, filtered, sorted, and which page templates they use in one XML configuration. The plugin reads that configuration and returns the finished product list for rendering.

Why build the product list from rules​

Project data often represents deeply nested trees. A chapter holds product groups, a group holds products, and a product holds accessories. Planning every one of these records by hand is slow, and it repeats the same decisions in every document.

With Product List by Rule the user plans their documents at the level they care about, often the chapter. The rules then traverse the children below that level and build the rest of the list. One planned record can produce many products in the returned list. Along the way the rules assign chapter overviews, product templates, and optional accessory templates, based on the data of each record rather than on a manual choice.

What you can configure​

In one XML configuration you control how the product list is built:

  • Choose identifier of the product from your planning the templates will be linked to: buckets or planning records.
  • Filter the products: by entity identifier, by label with a regular expression, by media asset, or by the template or metadata of the root planning record.
  • Add products to the list: the current bucket, a child bucket, or a dummy bucket for example for a table of contents.
  • Assign page templates and document template pages, and add page breaks.
  • Write the input and output product list to a log file for easy debugging.

The sections below explain how these pieces fit together.

How the build works​

A standard CScript build script is the starting point. After starting this script from priint:planner or priint: Web2Publish the priint:comet plugins will check out the document. The script runs through the following steps:

  1. Read the document parameters, especially the selected preset from the XML config.
  2. Collects the planned products of the document.
  3. Reads the default page template for the rule set. If none is found, rendering stops.
  4. Sends the product list and the parameters to the plugin. The plugin applies the rules and returns the transformed product list.
  5. Writes a log file when logging is enabled.
  6. Renders the returned list into the document and loads the parent page items.

The _renderingruleset parameter connects the document to a rule set. Its value must match the configId of a rule set in the XML configuration.

The documentId parameter is filled by the priint:comet plugins and is used to identify the current document where the script runs.

The other parameters represent the context criteria (_language, _country, _assortment, and _well) will pass the document context to the plugin. Find out more about localization support in this article.

Configuration structure​

The XML configuration allows configuration from the general rule set down to single template assignments to individual products:

  • Rule set: the top level, identified by configId. It sets the mode and the logging options.
  • Rules: the ordered list of rules inside the rule set. The rule set also holds the default page template and the exclusive option.
  • Conditions: filter which root buckets or planning records a rule applies to.
  • Actions: add the matched products to the result list. An action can add the current bucket, a child bucket, or a dummy bucket.
  • Page items: assign templates to the added products and can add page breaks.

To find more information and an in-depth explanation for all of these elements, check the XML Reference documentation

Modes​

When working with priint:suite we are assigning content to documents, which will creating a new planning entity, it represents a specific assignment to the document that links to the original bucket. When working in the project, we need to decide which identifier will be linked to the product when running establish.

  • The ID of the planning looks like this 51daa53b-9aeb-40a3-8656-ec3ba5e929f1 and is generated by the system once the product is dropped into the document. See position 1 in the attached reference image.
  • The ID of the content is determined by the connector you are using. You can see an example in the attached image position 2.

identifier.png

When evaluating which identifier should be used for building the templates, three modes are supported:

  • planning: works whether the products are buckets or planning records.
  • bucket: works only when the products are buckets.
  • dummy: renders templates from dummy buckets when no products are planned. Useful when building a table of contents or index template.

Planning records run in planning mode as they are, or convert to buckets in bucket mode. Bucket records run in bucket mode. Bucket records in planning mode return an error.

Dummy Mode​

Some templates don't have a dependency on a specific product, in those cases the logic inside the placeholder will determine where the data is retrieved from. This could for example be a placeholder like Index or Directory that will evaluate the whole publication or a template like a chapter overview, where placeholders will evaluate the document parameters or static content.

You can add dummy products into your product list that are assigning these special templates statically. When the priint: comet plugins are establishing these products and their templates they will be linked to an identifier that is not specific to any product, but instead will only ensure that the priint:comet plugins will evaluate all the placeholders in the template.

How rules build the list​

The plugin runs each input bucket or planning record through the rules of the rule set, in order of their sort value. A rule's conditions decide whether it applies to that input. A condition list combines its conditions with or (match at least one) or and (match all). A rule with no conditions applies to every input.

The exclusive option decides how many rules can act on the same input:

  • true: Rules are evaluated in ascending sort order. For each input, the plugin stops at the first rule that matches and returns products. Those products are added to the result list, all remaining rules are skipped for that input, and the plugin continues with the next input. As a result, each product can be added to the result list only once.
  • false: Rules are also evaluated in ascending sort order, but the plugin does not stop after the first match. Instead, every rule is evaluated for the same input. Each matching rule can add its products to the result list, so the same product can be added multiple times.

When a rule applies, its actions add the matched bucket, a child bucket, or a dummy bucket to the list. Child actions can target a tree level, where the root is level 0. A child action adds every matching child, so the returned list can hold more products than the input list. This is how one planned chapter turns into all the products below it.

Each added product needs a template. Inside an action you list template rules, and the plugin tries them top to bottom, using the first one that resolves to a real template. To prefer the template already planned on the record, list PLANNED_TEMPLATE first and a fixed template after it as a fallback. When an action lists no template rule, the plugin uses the planned template.

Further Reading​