Rules Module

This manual describes the use of the Rules Module™ for Adobe® InDesign® with the DesignMerge® software from Meadows Publishing Solutions. The Rules Module, a standard component of DesignMerge Pro and DesignMerge Catalog, provides features to apply powerful, conditional processing (if-then-else statements) while merging or updating content in documents.

Topics Covered in this Manual:

  • Overview and Installation
  • Terminology
  • Rule Types (Link, Box, Page)
  • Statements, Criteria, and Actions
  • Testing and Debugging Rules

OVERVIEW

About the Rules Module

The Rules Module provides features to apply powerful, conditional processing (if-then-else statements) while merging or updating variable content in InDesign documents. With an easy-to-use interface, the Rules Module provides enough power to construct even the most complicated, “nested” statements. In addition, the product supports an extensive list of “qualifiers”, including our unique “List Qualifiers” which greatly simplify constructing a statement’s criteria.

With the Rules Module, DesignMerge Pro and DesignMerge Catalog can apply rules to Variable Links, and can also apply rules to frames and pages, when merging or updating content in an InDesign document. This greatly extends your control over the manner in which data will be placed in your documents. For example, you can use a Link Rule to modify the data or paragraph/character style for a Variable Text Link on a conditional basis. A Frame Rule can delete frames and modify frame attributes, such as the color of the background or frame, for any frame in the document. A Page Rule can apply a parent page, show/hide layers, or omit a page from merged print output. Additionally, if your DesignMerge software installation includes the Scripting Module, then a rule can be set to launch external scripts, which are useful for constructing custom rule actions.

Below is an example of the Rules dialog where you can set up and test rules for your document, followed by an example of merged results for two different records in a document that is using Rules with DesignMerge Pro.

Example of Rules dialog where you can set up and test rules

Example of DesignMerge Pro merge results for two different records using rules processing

In the above examples, a Page Rule applied a parent page, a Frame Rule modified the color of the stroke for the Map picture frame, a Link Rule selected a picture for the Map picture frame, and another Link Rule added an appropriate prefix to the customer name.

For step-by-step instructions to set up and use the rules in the example above, see DesignMerge Pro Tutorial #1.

About Rules-Based Processing

“Rules-based processing” is defined as the ability to perform specific actions based upon the contents of one or more data fields. A simple example would be to add a title (Mr., Ms., etc.) based on the contents of a different data field, such one that indicates gender (M, F). Such a rule might be expressed like this:

If <<Gender>> contains "M", then add the title "Mr. "
else if <<Gender>> contains "F", then add the title "Ms. "
else if... etc.

A more complicated example would be to vary an entire page layout based upon the contents of a different data field, or to omit a document page when a certain condition is met, such as a specific page number. The Rules Module has been designed to handle all of these examples, from simple data modifications to complex page layout alterations.

Terminology

The following terminology is used throughout this manual to describe the Rules Module.

Expression
Defines a single Condition. An expression defines a single condition, such as [If <<Gender>> contains “M”], which can be evaluated to either true or false.

Criteria
A set of one or more Expressions. Criteria contain one or more Expressions. The Expressions can be inclusive (and), exclusive (or), or any combination. For instance, [If <<City>> is “Chicago” and <<ZIP Code>> is “60173”] is an example of an inclusive Criteria that contains two Expressions. Both of the Expressions must be true in order for the Criteria to be true. If either of these conditions are false, then the entire Criteria evaluates to false.

Action
One or more events to be performed. An Action is a modification that will be made to a piece of data or to a document. Actions can apply to individual Variable Links, frames, or pages within a document.

Statement
A Statement is a combination of Criteria and the associated Actions that will be triggered if the Criteria is true. If the Criteria associated with a Statement evaluates to true, then the Actions associated with that Statement are performed.

For instance, the Statement [If <<Gender>> contains “M”, then Add Prefix: “Mr. “] consists of a single-expression Criteria and a single Action. In this example, if the field identified as Gender contains an “M”, then the Statement would be true. Otherwise, it would be false. If the Statement is true, then the Action is performed. In this case, the text “Mr. “; would be added as a prefix to the data that was currently being processed.

Rule
A set of one or more Statements that are Evaluated and Executed. If the Criteria associated with a Statement is “met” (i.e., the Statement’s Criteria evaluates to true), then the associated Actions are performed (i.e., the Statement is executed). Rules are defined by the user and are specific to each Data Source Definition (DDF).

Rule Types

The Rules Module provides three types of rules: Link, Frame, and Page. Each rule type supports a specific set of Actions, as described below.

Link Rule
A Link Rule is a rule that may be “attached to” any Variable Link that is used in the document. A Link Rule is unique in that only Actions associated with Link Rules can be used to modify data as well as text attributes — they do not modify frame or page attributes (those are handled by the other rule types).

Frame Rule
A Frame Rule is a rule that is associated with a text or a picture frame. Note that a Frame Rule can be “attached” to any frame in a document, but only one rule can be attached to any given frame. A Frame Rule can be applied to any frame, not just frames that contain Variable Links. The Actions associated with Frame Rules are limited to modifying the attributes of the frame, such as background color, shade, stroke, etc. However, if your DesignMerge software installation includes the Scripting Module, you can also launch an external script to perform any other Action you wish.

Page Rule
A Page Rule is a rule that is associated with a document page. Page Rules are evaluated before any merging or other page processing begins. The Actions associated with Page Rules are limited to “Omit Page from Print” and “Apply Master Page”. However, if your DesignMerge software installation includes the Scripting Module, you can also launch an external script to perform any other Action you wish.

Rule Precedence

It is important to understand the order in which the different rule types are evaluated and processed. The basic process is described below.

A) Page Rules
At the start of a merge/updating process, assigned Page Rules are processed first. This allows the user to establish Actions that may affect the overall document layout, such as applying a parent page.

B) Frame Rules
Once the Page Rules have been evaluated, each frame in the document is processed in turn. Before a frame is processed, DesignMerge checks to see if a Frame Rule has been applied to the frame. If a Frame Rule has been assigned to the frame, that rule is evaluated before the content of the frame is processed. This allows the user to establish Actions that may affect the frame attributes, or even the frame content, such as the case where an Action causes the frame to be deleted.

C) Link Rules
Finally, the content of the frame is processed. This process is slightly different for Text or Article vs. Picture Links. Each process is described in the next section.

Link Rule Processing

The processing for Link Rules may require a bit of explanation. The descriptions below describe how Link Rules are processed for Text, Picture, and Article Variable Links.

Text Link Processing
For Text Links, DesignMerge scans through the story looking for Variable Links. When a Text Variable Link is located, DesignMerge first retrieves the data for the Link. Then, if a rule has been assigned to the Link, DesignMerge passes the data to the Rules Module (along with the name of the rule to be processed). The Rules Module evaluates the rule, and returns the modified data. The modified data is then merged into the Link, and processing continues.

Picture Link Processing
For Picture Links, the process is identical to that of Text Links. However, if a Link Rule has been assigned to a Picture Link, DesignMerge passes the data to the Rules Module where the data is evaluated and modified. The data returned from the Rules Module is assumed to be the name of a picture file to be merged. DesignMerge will scan the normal search paths to try and locate the file.

Article Link Processing
The processing for Article Links proceeds in the same fashion as Text Link Processing. The only difference is that if the Variable Link is defined as an Article Link, the modified data returned from the Rules Module is assumed to be the name of a text file to be merged. DesignMerge will scan the normal search paths to try and locate the file.

MANAGING RULES

This section describes how to create a rule and also how to view or modify an existing rule. To edit a set of rules, you must use the Rules dialog. To access this dialog, select Rules from the DesignMerge > Setup menu. This opens the Rules dialog, as shown below:

Note the Rules dialog in the picture above displays the rules that exist in the Data Source Definition (DDF) that has been set up for DesignMerge Pro Tutorial #1. You may see a different set of rules when you open the dialog. To see the same set of rules that are shown in the picture below, open the document that has been set up for Tutorial #1 before you open the Rules dialog.

About the Rules Dialog

The list on the left side of the dialog shows all of the rules that have been defined for the Current DDF (Data Source Definition). The first column of the list shows the name of the rule, and the second column lists the rule type, as shown in the example below:

To edit or view an existing rule, select it in the list. The dialog will change to show you how that rule has been defined.

The buttons towards the bottom right side of the dialog, shown in the picture below, let you manage the rules:

Each button that is available towards the bottom of the Rules dialog to manage rules is described below.

View
Opens a dialog with a larger view of all Statements for the currently selected rule. The Statements can then be copied to the clipboard for printing.

New
Creates a new rule.

Delete
Deletes the currently selected rule. You will be warned that the rule is about to be deleted.

Save As
Saves the currently selected rule under a different name. You may also use this button to change the rule type (accomplished by saving the rule with the same name, but changing its rule type).

Rename
Renames an existing Rule.

Save
Saves the changes made to the current rules. Changes are also saved if you click the OK button. However, clicking OK also closes the dialog. If you prefer the dialog stay open, select a different rule in the list or click Save.

Test
Tests the rule using live data. This is covered in a separate section of this manual.

Cancel
Discards all changes to the rules (unless the user had previously pressed the Save key), and closes the dialog.

OK
Saves any changes to the rules and closes the dialog.

Create a New Rule

To create a new rule, follow the steps outlined below.

  1. Click the New button.
  2. Enter a Name for the rule.
  3. Select a Type for the new rule.
  4. Click the OK button.

The rule will be created, and should now appear in the list of available rules.

Rules and Statements

Rules consist of one or more Statements. A Statement consists of a set of Criteria, and a set of Actions. The Criteria are evaluated, and if the result of that evaluation is true, the Actions associated with the Statement are performed.

The Statements Box

The Statements box on the Rules dialog, as shown below, includes all of the options for editing and managing the Statements associated with the currently selected Rule. Each button in the Statements box is described below:

Add
Adds a new Statement to the list.

Duplicate
Duplicates the currently selected Statement. Note that you cannot duplicate the last Statement in the list (the Default Condition Statement).

Remove
Removes the currently selected Statement (without prompting).

Criteria
Opens the Criteria dialog to edit the Criteria for the selected Statement.

Actions
Opens the Actions dialog to edit the Actions for the selected Statement.

Statement Preview Area

There is a Preview area at the top of the Rules dialog that displays the selected Statement in sentence format.

Preview All Statements

By default, the Preview area displays the currently selected Statement only. Note that there is a check box option at the top of this area called Preview all Statements. If you check this option, then the preview will show all of the Statements for the rule and will highlight only the currently selected Statement.

WORKING WITH STATEMENTS

The Default Condition Statement

When a new rule is created, it will contain a single Statement that refers to something called the Default Condition. The Default Condition is something which is always true. Note that you cannot edit the Criteria for the Default Condition (because it is always true), and the Default Condition Statement is always the last Statement in the list. However, you can edit the Actions associated with the Default Condition (more about Actions later on). Generally speaking, the Default Condition Statement is the one that the rule will “default to” if none of the other Statements in the rule evaluate to true.

When you are working with a new rule, the first thing to do is add one or more Statements to the list. To do so, click the Add button. A new Statement will be added to the top of the list. Continue to click the Add button if you wish to add more than one Statement at a time.

How Statements are Evaluated

Statements are processed and evaluated in the order in which they appear in the list. You can drag Statements around in the list to change the order in which they are evaluated.

Stop After First TRUE

The Stop After First TRUE check box option controls how the Statements are evaluated. If this box is checked, then the Statements are evaluated one at a time until one of the Statements is true. The Actions associated with that Statement are then performed, and processing stops at that point. If none of the Statements in the list evaluate to true, then processing falls through to the Default Condition Statement (which is always true). In this case, any Actions associated with the Default Condition Statement would be performed.

If you uncheck the Stop After First TRUE option, then all Statements are evaluated independently (including the Default Condition Statement). If a Statement evaluates to true, then the Actions associated with that Statement are performed, and processing continues with the next Statement in the rule.

Note that the Statements will change from If/Else to If/If depending upon the setting for the Stop After First TRUE option, as shown in the two examples below:

EDITING CRITERIA

Criteria are a way of defining whether a condition is true or false. Each Statement includes a set of Criteria, and a set of Actions. When the Criteria for the Statement evaluate to true, the Actions associated with that Criteria are performed.

To edit the Criteria for a selected Statement, follow the steps below.

  1. Select the Statement you wish to edit by clicking on it in the list.
  2. Click on the Criteria button.
  3. The Edit Criteria and Actions dialog will open.

Criteria Panel

The Criteria panel on the Edit Criteria and Actions dialog is shown below:

Expressions Section

The Expressions section is where the user defines the expressions to be evaluated. By default, a single expression selection is selected in the list.

Add Button
Clicking the Add button will insert additional expressions.

Remove Button
Clicking the Remove button will delete the currently selected expression.

Duplicate Button
Clicking the Duplicate button will make a copy of the currently selected expression.

Expression Settings

The popup menus and edit boxes at the top of the list allow you to change the selected expression. Changes to these options are automatically applied and should be visible in the list as soon as you make them.

Criteria Preview Area

The Preview area at the bottom of the dialog shows the complete Criteria in sentence formation. This makes it easier to understand how your Criteria will be evaluated. The preview updates automatically; any changes to the Criteria will be visible immediately.

Case Sensitivity

The Case Sensitive check box option determines whether the expressions will be evaluated with or without regard for letter case. This applies globally to all expressions specified for the Criteria.

Match All vs. Match Any One

As shown below, there is a set of radio buttons at the bottom of the dialog titled Match.

Selecting Match: All means that all of the specified expressions must evaluate to true in order for the Criteria itself to evaluate to true.

Selecting Match: Any One means that if any one of the specified expressions evaluate to true, so does the Criteria. An example is shown below:

Match/Specify (Expression Groupings)

Clicking the Match: Specify radio button enables the small popup menus on both sides of the expressions area at the top of the list. These popup menus can be used to construct nested expressions. Nested expressions can be helpful when it is necessary to group two or more expressions, much in the fashion as a mathematical equation might be structured. The Preview area at the bottom of the dialog reflects the groupings by using parentheses, as shown in the example below:

Evaluation of Expressions

Expressions are evaluated in a left-to-right, top-down order. Expressions that have been grouped (Match: Specify) are evaluated in the same fashion, except that expressions inside parentheses are always evaluated first. Using grouped expressions helps to clarify how an expression will be evaluated. For example, the expression [If <<A>> and <<B>> or <<C>>] might be more easily understood if expressed as [If (<<A>> and <<B>>) or <<C>>] which is how the Rules Module would evaluate the expression in either case.

Edit Expressions

To edit an expression, you use the popup menus and edit boxes at the top of the list. Each of these options is described in detail below.

If/Else Popups

The two small popup menus which appear on both sides of the edit area are collectively referred to as the If/Else popups. Note that these options will be enabled only if the Match: Specify radio button has been chosen. Otherwise, they remain dimmed, but will change to display how the currently selected expression has been defined. The first popup menu (the one on the left) allows you to define whether the expression is an If Statement or an Else Statement. Note that the first expression in the list must always be an If Statement. Subsequent Statements can be of either type. The popup menu on the right allows you to select a balancing parenthesis when expression grouping is required.

Variable Link Popup

This popup menu lists all of the Variable Links that have been defined for the Current DDF. The contents of the selected Variable Link (for the current Record Number) will be evaluated during a merge/updating session. Note that there are several predefined variables at the bottom of this list. Each is described below.

Record Number
This variable will be substituted with the data file Record Number being processed at the time the expression is evaluated.

Page Number
This variable will be substituted with the Page Number being processed at the time the expression is evaluated.

Spread Number
This variable will be substituted with the Spread Number being processed at the time the expression is evaluated.

Link Data
This variable will be substituted with data from whichever Variable Link is assigned to the Link being processed. The Link Data variable can be useful for creating generic rules that can be shared with many different Variable Links. When you use the Link Data variable, whatever data is being merged at the time is the data that will be evaluated, and as such the comparison is not limited to a specific Variable Link.

Qualifier Popup

This popup lists a series of “qualifiers” that will be used in conjunction with the Variable Link selection when the expression is evaluated. For example, the qualifier “contains” can be used in conjunction with a Variable Link to determine if the contents of the Link contains a text string (which is specified as an additional parameter to the Qualifier). Not all qualifiers require additional parameters.

Some of the qualifiers expect a Single value that is a number while others expect a text string (alpha-numeric) data. Other qualifiers will evaluate a List of values. Each qualifier type is detailed later in this manual.

Edit Box

The Edit Box is where you enter the value (a text string or a number) that the variables will be compared to using the specified qualifier. For single qualifiers (qualifiers that evaluate a single value), enter the value directly into the Edit Box, or click the Edit button to open the Edit Rules Data dialog which provides a larger editing box along with other helpful features. For list qualifiers (qualifiers that evaluate a list of values), use the Edit List button to create or edit a list of values. Each of these options are described below.

Edit Rules Data

When a single qualifier has been selected, the Edit button becomes enabled, as shown below:

Clicking the Edit button opens the Edit Rules Data dialog, shown below:

The Edit Rules Data dialog provides a large editing box where you can more easily enter and view longer values. Additionally, this dialog provides two helpful features to enter a filename or to embed one or more variable links.

Click Insert Filename to open a dialog where you can browse to select the file whose filename you wish to enter for the criteria, and then click Open to place that file’s name in the Edit Box on the Edit Rules Data dialog.

To evaluate data from a variable link, select a variable link from the Insert Variable Link popup menu. This Embedded Link feature allows you, for example, to compare the value of two different Variable Links. For example, the Rule Criteria If Field1 is equal to Field2 will compare the data read from a Variable Link named Field1, to the data read from a Variable Link named Field2 for the same data record. In addition, the Embedded Link functionality supports references to the Current, Previous and Next record being processed. This can be very useful, for example, to detect tray pull changes when printing sorted mailings.

Note you can include more than one embedded variable link, filename, or combination. You can also enter additional text or numbers before or after a filename or embedded link in the edit box.

Edit List

There are several qualifiers that expect a list of text items to compare (is any of, contains all of, starts with any of, etc.) When one of these qualifiers has been selected, the Edit List button becomes enabled, as shown below:

Clicking the Edit List button opens the List dialog, shown below:

To add an item to the list, enter the text in the Item box and click the Add button.

Click the Replace button to replace an existing item with the text in the Item box.

Click the Delete button to remove an item from the list.

The Browse button can be used to select any file. The selected file name will be pasted into the Item box so it can be added to the list. This is handy for building up a list of file names.

Use the Import button to import a list from an existing file, and use the Export button to save the list to a file.

Clicking OK will save the list. Clicking Cancel will discard the list and keep whatever had been in the list originally.

Rearrange Expressions

Expressions are evaluated in the order in which they appear in the list. To reposition an existing expression, you can click on it and drag it to a different list position.

Note that if you drag an existing expression to the top of the list (so it is the first expression in the list), it will automatically change to an If Statement, as this is a requirement for the first entry in the list.

Save the Criteria

Click the OK button to save the expressions, or click the Cancel button to discard your changes and restore the previous Criteria.

Syntax Checking for Criteria
If you select the Specify radio button, then you can “group” Criteria selections together to form more complicated Statements. Since this may involve the use of parentheses to form Criteria groups, the Rules Module will verify the syntax (e.g. check for matching open/close parentheses) and otherwise ensure that the specified Criteria can be evaluated without error. Note that you will not be allowed to save a Criteria until all syntax errors have been repaired.

Qualifier Descriptions

Following is a detailed description of each of the available Expression qualifiers.

Parameter Types

Qualifiers may require certain parameters be entered into the edit box. Each parameter type is described below. Note that (cs) denotes the comparison can be affected by the Case Sensitive check box setting for the Criteria.

[text] (cs)
A string up to 255 characters in length.

[list] (cs)
A list of [text] strings, each up to 255 characters in length.

[number]
Must contain digits and decimal point only.

Qualifier Descriptions

Following is a brief description of each qualifier, along with the type of parameter that is expected for that qualifier.

is [text] (cs)
Variable text matches exactly the specified text parameter.
Example: "apple" is "apple" [true]

contains [text] (cs)
Variable text contains the specified text parameter.
Example: "apple" contains "pl" [true]

starts with [text] (cs)
Variable text starts with the specified text parameter.
Example: "apple" starts with "ap" [true]

ends with [text] (cs)
Variable text ends with the specified text parameter.
Example: "apple" ends with "le" [true]

is empty
The data for the Variable Link is empty.
Example: "" is empty [true]

is not [text] (cs)
Variable text does not match exactly the specified text parameter.
Example: "apple" is not "john" [true]

doesn’t contain [text] (cs)
Variable text does not contain the specified text parameter.
Example: "apple" doesn’t contain "zz" [true]

doesn’t start with [text] (cs)
Variable text does not start with the specified text parameter.
Example: "apple" doesn’t start with "ex" [true]

doesn’t end with [text] (cs)
Variable text does not end with the specified text parameter.
Example: "apple" doesn’t end with "ap" [true]

is not empty
Variable text contains at least one character.
Example: "apple" is not empty [true]

is any of [list] (cs)
Variable text matches exactly any one of a list of text items.
Example: "apple" is one of ["bear","candy","apple"] [true]

contains any of [list] (cs)
Variable text contains any one of a list of text items.
Example: "apple" contains any of ["zz","pl","pp"] [true]

contains all of [list] (cs)
Variable text contains all text items in the list.
Example: "apple" contains all of ["a","p","e"] [true]

starts with any of [list] (cs)
Variable text starts with any one of a list of text items.
Example: "apple" starts with any of ["ap","z","ea"] [true]

ends with any of [list] (cs)
Variable text ends with any one of a list of text items.
Example: "apple" ends with any of ["le","ch","ey"] [true]

is not any of [list] (cs)
Variable text does not match exactly any one of a list of text items.
Example: "apple" is not any of ["bear","monkey","grape"] [true]

doesn’t contain any of [list] (cs)
Variable text does not contain any one of a list of text items.
Example: "apple" doesn’t contains any of ["zz","le","aa"] [false]

doesn’t contain all of [list] (cs)
Variable text doesn’t contain all text items in the list.
Example: "apple" doesn’t contain all of ["a","p","e"] [false]

doesn’t start with any of [list] (cs)
Variable text does not start with any one of a list of text items.
Example: "apple" doesn’t start with any of ["ap","z","ea"] [false]

doesn’t end with any of [list] (cs)
Variable text does not end with any one of a list of text items.
Example: "apple" doesn’t end with any of ["le","ch","ey"] [false]

is odd number (#) [number]
Variable text is an odd number
Example: "3" is odd number [true]

is even number (#) [number]
Variable text is an even number
Example: "10" is even number [true]

is alpha [text]
Variable text contains at least one non-digit (0-9) character.
Example: "10a9" is alpha [true]

is digit [text]
Variable text contains all digits (0-9)
Example: "999" is digit [true]

is less than (#) [number]
Variable text contains a number that is less than the specified number.
Example: "999" is less than "888" [false]

is greater than (#) [number]
Variable text contains a number that is greater than the specified number.
Example: "999" is greater than "888" [true]

is less than (string) [text] (cs)
Performs a string comparison to determine if variable text is less than the specified text item.
Example: "Five" is less than "Three" [true]

is greater than (string) [text] (cs)
Performs a string comparison to determine if variable text is greater than the specified text item.
Example: "Five" is greater than "Nine" [false]

is longer than [text]
Variable text contains more characters than the specified text item.
Example: "apple" is longer than "giraffe" [false]

is shorter than [text]
Variable text contains fewer characters than the specified text item.
Example: "apple" is shorter than "giraffe" [true]

is same length as [text]
Variable text contains the same number of characters as the specified text item.
Example: "apple" is same length as "snake" [true]

contains more than N chars [number]
Variable text contains more than the specified number of characters.
Example: "apple" contains more than N chars "3" [true]

contains less than N chars [number]
Variable text contains fewer than the specified number of characters.
Example: "apple" contains less than N chars "3" [false]

contains exactly N chars [number]
Variable text contains exactly the specified number of characters.
Example: "apple" contains exactly N chars "5" [true]

SELECTING ACTIONS

As mentioned in the “Terminology” section, a Statement consists of Criteria and associated Actions. Each Statement can have one or more Actions associated with it that are “triggered” when the Statement evaluates to true.

To edit the Actions associated with a Statement, select the Statement and then click the Actions button, as shown below:

If the Edit Criteria and Actions dialog is already open, click the Actions tab, shown circled in the picture below, to open the Actions panel:

Actions Panel

The Actions panel on the Edit Criteria and Actions dialog allows the user to specify up to 5 different Actions to be performed. Actions are performed in the order in which they are defined. By default, a single Action item is displayed, as shown below:

To add an Action, click the Add button. Or, click the Duplicate button to add an Action that is a copy of the currently selected Action.

To reduce the number of Actions defined, click the Remove button.

To specify an Action, select it using the popup menu and enter an appropriate parameter into the edit box (if required).

Click the OK button to save the Actions. Press the Cancel button to discard the Actions and restore the original.

The Preview area at the bottom of the dialog gives a representation of the Action items in sentence format.

How Actions are Performed

Actions are performed in the order in which they appear in the dialog.

Example

Assume that the <<Last Name>> field for record 6 contains the word “Smith”. A Criteria could be constructed as follows:

If <<Last Name>> is not empty,
then Add Prefix: "Dear Mr. " and Add Suffix: ","

The result would be that “Smith” would become “Dear Mr. Smith,”.

Conflicting Actions

It is possible to have Conflicting Actions, that is, where one Action negates the effects of the first Action. For example:

Add Prefix "Dear Mr."
Add Suffix ","
Set Data to: "Hello There"

In the above example, the third Action to be performed sets the incoming data to a specific text string, thus negating the effects of the previous two Actions. The Rules Module makes no attempt to identify such conditions. Note that this condition is inefficient because it causes unnecessary processing to occur; however, it is not problematic in that the merged data is completely valid.

Actions and Rule Types

The Actions available for a Rule are specific to the type of Rule that is being created. The Actions available for each rule type are listed below.

All Rules

  • No Action
  • Show Alert:
  • Launch External Script: [requires DesignMerge Scripting Module]

Link Rules

  • Set Data to:
  • Set Data to Empty
  • Get Data from Link Name:
  • Get Data from URL:
  • Add Prefix:
  • Add Suffix:
  • Apply Para Style Sheet:
  • Apply Char Style Sheet:

Frame Rules

  • Delete Frame
  • Set Frame Color to:
  • Set Frame Shade to:
  • Set Stroke Color to:
  • Set Stroke Shade to:
  • Set Stroke Width to:
  • Set PDF Page Number to Import:
  • Omit Frame from Print

Page Rules

  • Apply Parent Page:
  • Apply and Resize Parent Page:
  • Hide Layer:
  • Show Layer:
  • Hide All Layers
  • Show All Layers
  • Omit Page from Print

Action Descriptions

Each Action is described below.

No Action
Do nothing. This is the default Action. This action is available for all types of Rules (Link, Frame, and Page). Note this does not prevent the Link or Frame or Page from being merged. Instead, this indicates the Rule will not take any action. The Link or Frame or Page will be merged normally as though no Rule is assigned to it.

Show Alert: [message of the alert]
Display an alert dialog that contains the specified message. This action is available for all types of Rules (Link, Frame, and Page).

Set Data to: [string]
Set the incoming data to the specified text string.

For assistance in setting up a Set Data To string, you may prefer to click the Edit button to open the Edit Rules Data dialog. Then, to set the data to a file name, click Insert Filename. Browse to select the file whose name you wish to insert and click Open. This will place the file’s name in the edit box.

Additionally, you can embed Variable Links, if you are running an edition of the software that supports this. In this case, when a merge/updating session applies a Set Data To action, DesignMerge will merge/update any Links that are embedded in the Set Data To text string, replacing each Embedded Link in the string with data. Each Embedded Link will retrieve its data from the record that you referenced (Previous Record, Current Record, or Next Record) when you embedded that link in the Set Data To text string.

To assist in embedding Links, the Edit Rules Data dialog provides a list of the Variable Links in the Current DDF. To insert a Variable Link in the text string, choose the Link from the Insert Variable Link popup menu. You will then be prompted to select a record reference (Previous Record, Current Record, or Next Record). Once you select a record reference, the Embedded Link will be inserted into the edit box with the appropriate syntax.

If you prefer to enter an embedded link manually, enter the Link’s Name and then bracket the Link Name with either the <$ and > characters or with the [$ and ] characters (for example, to embed a Link named “ZIP5“, place <$ZIP5> or place [$ZIP5] in the string). To reference the previous record, append “- -” to the Link Name (for example, place <$ZIP5- -> or place [$ZIP5- -] in the string). To reference the next record, append “++” to the Link Name(for example, place <$ZIP5++> or place [$ZIP5++] in the string). When copying/cutting an embedded link that has been placed in a Set Data To text string, be careful to included its bracketing characters in your selection of text.

Set Data to Empty
Set the incoming data to empty.

Get Data from Link Name: [name of a Variable Link]
Get data from a different Variable Link. Type the name into the edit box, or use the popup button to select from a list of available Variable Link names. Note that the Rules Module will use the incoming record number to retrieve the data from the specified Variable Link.

Get Data from URL: [full URL]
This action retrieves the data from the specified URL and imports that data into the document. This feature requires the optional HTTP module be installed.

Add Prefix: [string]
Add the specified text as a prefix to the incoming data.

Add Suffix: [string]
Add the specified text as a suffix to the incoming data.

Apply Para Style Sheet: [name of a Paragraph Style Sheet]
Apply the specified paragraph style sheet. Type the name of the style sheet into the edit box, or use the popup button to select from a list of available paragraph style sheets.

Apply Char Style Sheet: [name of a Character Style Sheet]
Apply the specified character style sheet. Type the name of the style sheet into the edit box, or use the popup button to select from a list of the currently available character style sheets.

Delete Frame
Delete the frame that has been associated with the rule.

Set Frame Color to: [name of a Color]
Set the background color of the frame to the specified color. Type the name of the color into the edit box, or use the popup button to select from a list of the document’s Color Swatches.

Set Frame Shade to: [% shade]
Set the background shade of the frame to the specified percentage. Type the percentage shade value into the edit box, or click the popup button to select from a list of common shade values.

Set Stroke Color to: [name of a Color]
Set the color of the Stroke to the specified color. Type the name of the color into the edit box, or use the popup button to select from a list of the document’s Color Swatches.

Set Stroke Shade to: [% shade]
Set the shade of the stroke to the specified percentage. Type the percentage shade value into the edit box, or use the popup button to select from a list of common shade values.

Set Stroke Width to: [frame width]
Set the width of the stroke to the specified size. Type the width value into the edit box, or use the popup button to select from a list of common width values.

Set PDF Page Number to Import: [number]
Specify which page of a PDF file will be imported by a Picture Link. Type the number of the page into the edit box.

Omit Frame from Print
Omits frame from DesignMerge Pro Print Driver output. Please note that this action applies only to DesignMerge Pro Print Driver output. Frames will not be omitted during a Test or File merge session, or when using the InDesign Print or Export command.

Apply Parent Page: [name of parent page]
Apply a parent page. Type the name of the parent page into the edit box (omit the parent page prefix), or use the popup button to select the name of the parent page. Parent pages may contain both fixed and variable content.

Apply & Resize Parent Page: [name of parent page]
Apply a parent page and then resize the document page to match size of the applied parent page. Type the name of the parent page into the edit box (omit the parent page prefix), or use the popup button to select the name of the parent page. Parent pages may contain both fixed and variable content.

Hide Layer: [name of Layer]
Specify the name of the Layer to be hidden. Type the name of the Layer into the edit box, or use the popup button to select from the document’s available Layers. Note that you can also use the “Embedded Link” functionality (specify an embedded variable link to pull the name of the layer from the data file). See the description of the Set Data To Action for instructions to enter an Embedded Link manually in an edit box.

Show Layer: [name of Layer]
Specify the name of the Layer to be shown. Type the name of the Layer into the edit box, or use the popup button to select from the document’s available Layers. Note that you can also use the “Embedded Link” functionality (specify an embedded variable link to pull the name of the layer from the data file). See the description of the Set Data To Action for instructions to enter an Embedded Link manually in an edit box.

Hide All Layers
Hides all Layers in the document.

Show All Layers
Shows all Layers in the document.

Omit Page from Print
Omits page from DesignMerge Pro Print Driver output. Please note that this action applies only to DesignMerge Pro Print Driver output. Pages will not be omitted during a Test or File merge session, or when using the InDesign Print or Export command.

Launch External Script: [file name of a script]
Launch a compiled script. This action is available for all types of Rules (Link, Frame, and Page). Macintosh versions support AppleScripts and JavaScripts; dialogs versions support JavaScripts and Visual Basic scripts. Please note that this Action requires the use of the Scripting Module. If the Scripting Module has not been installed, this Action will not be performed. See the Scripting manual for more information about using this Action.

TESTING A RULE

Once you have defined a rule, you may wish to test the rule to see how it behaves using actual data file information. To test a rule, select the rule on the Rules dialog, click the Test button, and select a data file when prompted to do so. The Test Rule dialog will be displayed.

Test Rule dialog

Using this dialog, you can step through the specified data file to see how the rule will be evaluated by the Rules Module. Each of these options is described below.

Rule Name & Type
The name and type of the rule is displayed at the top of the dialog. This is for information purposes only. You cannot choose a different rule or change the rule type from this dialog.

Record Number
This setting indicates the record number being processed. When you click the Execute button, data will be extracted for the record number specified here, and the rule will be evaluated using that data.

[<<] and [>>]
Use these buttons to step through each record of the data file to see how the rule behaves for different data values.

Page and Spread Number
These settings are provided to simulate page and spread numbers for testing purposes. If your rule examines either of these values, change the values here for testing purposes.

Execute
This button executes the rule. That is, it submits the specified Record, Page, and Spread number to the Rules Module. The Rules Module evaluates the Criteria in each of the rule’s Statements and returns the results in the two Preview areas at the bottom of the dialog (described below).

Done
Closes the dialog.

Select Data File
Click this button to select a different data file for the test.

Rule Preview Area

When you click the Execute button, the rule is evaluated and the Rule Preview area is filled with the evaluation results for each Statement in the rule.

Show Data

This option controls how the rule is displayed in the Rule Preview area. If this box is unchecked (the default option), the names of any variables appear literally. For instance, the <<City>> Variable Link would normally be displayed like this:

If you have checked the Show Data option, then the name of each Variable Link will be replaced with the data that is being used for the evaluation. Using the above example, as you scroll through each data record, you will see the value of <<City>> change to reflect what has been read for that record. For instance, below is an example of the Rule Preview area that is displaying the data for the <<City>> Variable Link:

When a Statement’s Criteria is True

Once you have clicked the Execute button, the Criteria in each Statement is evaluated by the rules module. The results of the evaluation is displayed at the end of the statement in the Rule Preview area. There are three possible result values:

[TRUE]
This means that a Statement’s Criteria result is true, and that it will trigger one or more Actions. The Actions that would be performed appear in the Actions Preview area.

[true]
This means that a Statement’s Criteria result is true, but that none of its Actions were performed. This could be because the Stop After First TRUE option is enabled for the rule. As such, the first time a true Statement was encountered, the Actions for that Statement were performed. However, even though a subsequent Statement’s Criteria evaluated to true, there were no Actions performed for that Statement because processing stopped when the first true Statement was encountered.

[false]
This means a Statement’s Criteria result is false. None of the Statement’s Actions were performed.

Actions Preview Area

The Actions Preview area at the bottom of the dialog lists all Actions that would have been performed had the rule been evaluated during a live merge/updating session. Note that the Actions listed here are for preview only and do not affect the current document. In fact, you need not have a document open in order to test rules as long as the document’s Data Source Definition (DDF) is the Current DDF.

USING RULES IN A DOCUMENT

The method by which you assign rules to a document varies by Rule Type. The use of each Rule Type is described below.

Rules and Data Source Definitions

All Rule definitions are stored as a part of the Data Source Definition (DDF). The DDF also holds all of the other setup information, such as Variable Link Names, Field Names, Translation Table Names, etc. Every time you save a document, a copy of the DDF that is in effect for that document is saved along with it. You can also export your DDF information for archive purposes or to transfer DDF information to another workstation.

Use Link Rules

Link Rules serve to modify the data that is being merged and are therefore attached to Variable Link assignments in the document. Once you have defined a Link Rule, it can be applied to any one or more of the Variable Link assignments in the document.

Link Rules will appear under a separate popup menu on the DesignMerge panel. Rules are selected by using the popup menus or the panel’s Rules List and then clicking the Assign/Replace button to store the name of the rule with the Variable Link. You can also drag a Link Rule from the Rules List and drop it on a Variable Link selection in the document to assign the Rule.

To assign a Link Rule, follow these steps:

  1. Select the content that you wish to tag.
    Use the InDesign Type tool to select text, or use the InDesign Selection or Direct Selection tool to select a frame.
  2. On the DesignMerge panel, select a Link.
    If a Variable Link has not yet been assigned to the selected content, choose an appropriate Link.
  3. On the DesignMerge panel, select a Rule.
    Use the Rule popup menu or the Rules list to select the Link Rule you wish to assign.
  4. Confirm the Sequence or Search Key.
    When using DesignMerge Pro, confirm the number “1” is the Sequence setting. When using DesignMerge Catalog, enter the appropriate Search Key.
  5. Click the Assign/Replace button.
    Click this button to assign the Link and Rule to the selected content (or drag either the name of the Link from the Links list or the name of the Rule from the Rules list and drop it on top of the selection in the document). When a Link Rule has been assigned to variable text, two underscores will mark the text link in the document, as shown below:

For more information about sequence numbers, see DesignMerge Pro Tutorial #3.

To see a report of all Link Rules assigned in a document, run a Variable Link Report. To run this report, choose Merge from the DesignMerge menu and then on the DesignMerge dialog, choose Variable Link Report from the Action menu. The Variable Link Report dialog will detail all of the Variable Links in a document and also show the Link Rules that are associated with those Variable Links.

To preview results of a DesignMerge Pro merge session that applies Link Rules, run Data Preview (choose Data Preview from the Action menu for a merge session). To preview results of a DesignMerge Catalog update session, run Update Document (choose Update Document from the Action menu for a merge session); you can then review the results and then apply the InDesign Edit > Undo feature to revert the document to its previous state before the updating process.

For step-by-step instructions to set up and use Link Rules, see DesignMerge Pro Tutorial #1.

Use Frame Rules

Frame Rules serve to modify frame attributes. Note Frame Rules are not associated with modifying data for Variable Link assignments (regardless whether assigned to text, text frames, or picture frames in the document). Therefore, you can assign a Frame Rule to any frame in the document—not just frames that contain or are assigned to Variable Links. Additionally, you can assign a Frame Rule to any number of the frames that are in the document.

Frame and Page Rule assignments are managed via a separate panel called the Page & Frame Rules panel. To view this panel, select Rules Panel under the DesignMerge > View menu. For example, the Page & Frame Rules panel for DesignMerge Pro Tutorial #1 looks like this:

To assign a Frame Rule, follow these steps:

  1. Click on the frame you wish to tag.
    Use the InDesign Selection tool, or the Direct Selection tool, to select the frame you wish to tag with a Frame Rule.
  2. On the Page & Frame Rules panel, select a Frame Rule.
    Use the Rule popup menu or the Rules list to select the Frame Rule you wish to assign.
  3. Confirm the Sequence or Search Key.
    When using DesignMerge Pro, confirm the number “1” is the Sequence setting. When using DesignMerge Catalog, enter the appropriate Search Key.
  4. Click the Tag Frame button.
    Click this button to attach the rule to the frame (or drag the name of the Rule from the Rules list and drop it on top of the frame selection in the document). You will see a visual indicator (if Frame Edges are showing in your InDesign document) indicating that a Frame Rule has been applied, as shown below:

Note the sequence number that is assigned to a Frame Rule can be changed in a manner similar to changing the sequence number that is applied to Variable Link assignments in the document). For more information about sequence numbers, see DesignMerge Pro Tutorial #3.

To see a report of all Page & Frame Rules assignments in a document, click the Show Report button on the Page & Frame Rules panel. The Page & Frame Rule Report dialog will detail all of the Page Rule and Frame Rule assignments in a document. Click the Show button to see where a selected assignment has been placed in the document. Click the Remove button to remove a selected Rule assignment (note that the Rule definition is not deleted, just the assignment in the document). Click the OK button to dismiss the dialog.

To preview results of a DesignMerge Pro merge session that applies Rules, run Data Preview (choose Data Preview from the Action menu for a merge session). To preview results of a DesignMerge Catalog update session, run Update Document (choose Update Document from the Action menu for a merge session); you can then review the results and then apply the InDesign Edit > Undo feature to revert the document to its previous state before the updating process.

For step-by-step instructions to set up and use Frame Rules, see DesignMerge Pro Tutorial #1.

Use Page Rules

Page Rules serve to modify entire pages. You can attach a Page Rule to one or more pages in the document using the Page & Frame Rules panel. To view this panel, select Rules Panel under the DesignMerge > View menu. For example, the Page & Frame Rules panel for DesignMerge Pro Tutorial #1 looks like this:

To assign a Page Rule, follow these steps.

  1. Go to the page you wish to tag.
    Use the InDesign Go to Page feature to go to the page in the document you wish to tag.
  2. On the Page & Frame Rules panel, select a Page Rule.
    Use the Rule popup menu or the Rules list to select the Page Rule you wish to assign.
  3. Confirm the page number that is displayed on the Page & Frame Rules panel.
    The panel displays a page number in parentheses on the Tag Page button to indicate which page will be tagged with the Page Rule.
  4. Confirm the Sequence or Search Key.
    When using DesignMerge Pro, confirm the number “1” is the Sequence setting. When using DesignMerge Catalog, enter the appropriate Search Key.
  5. Click the Tag Page button.
    Click this button to attach the rule to the Page.

To see a report of all Page & Frame Rules assignments in a document, click the Show Report button on the Page & Frame Rules panel. The Page & Frame Rule Report dialog will detail all of the Page Rule and Frame Rule assignments in a document. Click the Show button to see where a selected assignment has been placed in the document. Click the Remove button to remove a selected Rule assignment (note that the Rule definition is not deleted, just the assignment in the document). Click the OK button to dismiss the dialog.

To preview results of a DesignMerge Pro merge session that applies Rules, run Data Preview (choose Data Preview from the Action menu for a merge session). To preview results of a DesignMerge Catalog update session, run Update Document (choose Update Document from the Action menu for a merge session); you can then review the results and then apply the InDesign Edit > Undo feature to revert the document to its previous state before the updating process.

For step-by-step instructions to set up and use Page Rules, see DesignMerge Pro Tutorial #1.

TROUBLESHOOTING RULE RESULTS

There is one merge session option related to the Rules Module which will assist you in the process of “debugging” your assigned Rules. Click the Options button on the DesignMerge dialog to access a merge session’s Rules option, as shown below:

Enable Rules Processing

To enable Rules Processing, choose either Standard Mode (as shown above) or Interactive Mode. This will ensure that your Rules are processed during the merge session. Interactive Mode will prompt you to preview the results of each rule as it is processed, and Standard Mode does not.

Interactive Mode

If you select Interactive Mode (instead of Standard Mode which is the default setting), a live merge session will prompt you with the same Test Rule dialog described earlier in this document. When Interactive Mode is enabled, the Test Rule dialog will appear each time a Rule is being evaluated by DesignMerge. Interactive Mode can be very useful for testing and verifying your rules.

Use Interactive Mode for Rules

Using the Interactive Mode for Rules is simple. Just select the Interactive Mode option, and start the DesignMerge merge session. In DesignMerge Pro, a Data Preview merge session is a great way to use this mode, however, Interactive Mode also works with the other DesignMerge output actions.

When a Rule is about to be evaluated, the Test Rule (Interactive Mode) dialog will be displayed. Below is an example from a merge session on the document for DesignMerge Pro Tutorial #1:

When the Test Rule (Interactive Mode) dialog is displayed, you will notice several things that are different from the normal Test Rule dialog.

The first thing you will notice is that there is now an Interactive Mode check box option that is visible on the dialog. If you uncheck this box, then Interactive Mode will be disabled for the remainder of the merge session. This is handy because you may just wish to preview the first few rules to verify that everything is being evaluated properly, and then continue the session uninterrupted.

The next thing is that the Record, Page, and Spread number being processed is shown at the top of the dialog. However, unlike the standard Test Rule dialog, you cannot change these values or scroll through data records. These values represent what is actually being processed by DesignMerge and therefore cannot be modified manually.

The Rule Preview area shows the current rule in sentence format. You may use the Show Data option to examine either the names of the Variable Links or live data.

The Actions Preview area shows the Actions that are about to be performed (if any).

Execute, Cancel, Cancel Session, or Switch to Standard Mode

The Test Rule (Interactive Mode) dialog provides three options to dismiss the dialog. Each is described below.

Execute

Clicking the Execute button will perform the Actions listed in the Actions Preview area of the dialog. The dialog is dismissed, and the Actions are performed as soon as you click this button.

Cancel

The Cancel button dismisses the dialog, but does not perform any of the Actions listed in the Actions Preview area. Note that for Link Rules, the Variable Link that is being processed will still be merged with data although the Rule applied to that Variable Link will be ignored.

Cancel Session

Clicking this button not only dismisses the dialog, but also cancels the current merge session immediately.

Switch to Standard Mode

To switch a session to Standard Mode (to exit Interactive Mode), uncheck the Interactive Mode option and click the Execute button. If you wish to enable Standard Mode for your next merge session, you must select it via the DesignMerge dialog, as described earlier.

MORE INFORMATION

For more information about DesignMerge and its modules, please see the information provided in DesignMerge Documentation, as described below:

Tutorials present various features of DesignMerge in an easy-to-follow, step-by-step format to help you quickly learn more about using DesignMerge.

Manuals for the modules in the DesignMerge software package present more detailed information about the features that a particular module provides.

Remember: Help is available! If you have any difficulty at all, we are here to help. Please feel free to open a support ticket by going to the Meadows Online Support Center:

Meadows Technical Support