Layout Rules are actions that can be linked together with frames and text placeholders and executed in specific situations like after loading a placeholder automatically by the priint:comet plug-ins. Using Conditions the execution of the rules can be controlled specifically. Frames and text placeholders can have any number of Layout Rules and for each rule and condition you can defined up to four additional parameters.

A built-in set of rules and conditions supports the most common requirements. With own actions the functionality of the rules and conditions can be extended as desired.

Layout rules can be run in various situations.

Text layout rules are only executed when placeholders are loaded (). Activation in other contexts is ignored.

Type		Description
After creation		The rule is always executed when a frame is created from a template and done loading. If a frame was inserted by a script, e.g. wit document::place_items, the rule is also applied if the parameter autoload is 0, meaning not loaded yet. If the rule should run again after load, the script should use the command itemlist::apply_layout_rules. Warning : The rules are applied after the <- rules. The rules are not executed after copy/paste, drag/Alt-drop of frames! During normal frame creation, the rules cannot be applied, because newly created frames have no rules associated with them.
After Load		After the frame's placeholders are loaded. The frame itself does not need placehoders. InDesign® groups, status objects and push buttons do not execute this rule. It is, however, applied to subframes of such objects.
During reorganisation		The rule is applied when a frame is changed during page reorganization.
Geomtry Changes		The rule is executed whenever a frame changes size or position in the document. You should use this type of rule sparingly. Interactive script commands like showmessage, file::select_file etc. must not be used in these rules! During template insertion and during loading and construction of frames, editing is disabled.
After build		The rules are executed after a product is loaded and built. The gFrames list contains all frames of the product to which gFrame belongs. Geometry changes of the frame are no longer registered by the product build-up and can lead to overflows of the page elements! Attention: The rules are executed only by the product build-up process. When inserting individual products, e.g. with drag and drop, they are not executed.

During creation and editing of templates, all rules are disabled.

When you insert a template directly from the Template panel, all rules are disabled, too. You can execute the defined rules anyway by holding the command key.

[From Comet 3.2.3 onward] The order, in which frames are procesed, is determined by the frame identifiers. When comparing identifiers, the UTF8 representation is used.

Frame identifiers are set in the Template Behaviour panel.

Versions prior to 3.2.3 use the frame UIDs to determine frame order.

[From v3.2.3 R2410 onward] The execution of layout rules can be made to be depend on some conditions. In addition to a number of standard condtions, you can also define custom condtions. The tests use one condition each. Conditions may have an ELSE branch, and can be nested to an arbitrary depth. Conditions cannot be negated or combined with 'and' or 'or' operators. Equivalent constructs can be easily formulated, however:

A rule R should apply, if a condition A is false.

Run the rule in the else branch:

if A
else
    R
end

A rule R should apply, if the conditions A and B both are true.

Set the second condition as a sub condition into the first:

if A
    if B
        R
    end
end

The rule R should apply, if either of the conditions A and B is true (or both are).

The obvious solution, to use two if statements in sequence has the unwanted side effect that R runs twice if both conditions are true. The following construct is better:

if A
    R
else
    if B
        R
    end
end

The state of the execution of Condition is automatically calculated from the state fields of the underlying rules. If at least one of the rules could be executed, the corresponding state is activated. The execution states of conditions cannot be set manually.

Some rules are built in. Here a list of all standard rules for frames:

More standard rules may be added in the future.

This table describes all built in conditions.

More standard conditions may be added in the future.

[Since v3.3.1 R3355] Like frames, text placeholders can be assigned layout rules. A set of standard rules is built into you plugins. The following table gives an overview of the available rules for text placeholders.

Text layout rules are applied only during placeholder loading (<-). Activations in other contexts are ignored. Please note that the text layout rules can only be set in texts that are linked to a placeholder!

More standard rules may be added in the future.

[since v3.3.1 R3355] The following table showcases the built-in conditions for text rules.

More standard conditions may be added in the future.

You can define up to 200 own frame rules and up to 200 text placeholder rules. The rules are defined in actions.xml or the actions table with the following ClassIDs:

    ClassID 36 : Frame rules
    ClassID 51 : Text placeholder rules

The rules defined in this way are appended to the list of the standard rules in the order of their sequence numbers. A detailed description of the actions attributes for layout rules can be found here.

The scripts of layout rules can use all script functions. However, please note the following:

• Calls like document::close can lead to errors.
• Layout rules that react to geometry changes must not contain dialogs. By waiting for a response, these diaogs will interrupt the geometry change itself ,

The script should start with the following includes:

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

In all calls to layout rules, the current frame is defined in gFrame. Rules called after build can also access the list gFrames (ItemList), which contains all frames in the build.

In addition to the generally available global variables, such as gFrame, gDocument, ... a number of specific global variables are also defined:

gOrgFrameLeft

float

gOrgFrameTop

gOrgFrameRight

gOrgFrameBottom

float

gParam1
gParam2
gParam3
gParam4

char*

gFrames

ItemList

gWhen

int

gSender

ItemRef

gKey

char*

gSenderData1

char*

gSenderData2

gIsInBuild

int

int

For text placeholder rules, all of the above variables, except gParam1-4, are defined.

Unlike all other global variables, the contents of gParam1-4 may be modified in the script. The string may not exceed 5000 characters. Modifications to the parameters only apply within the rule application. With the function

    frame::change_rule_param

parameter values can be permanently modified. The function can only change parameters of the currently running rule or condition.

This function represents a relatively powerful tool for storing dynamic information in a document.

Each time the rule runs, parameter 2 is incremented by 1. Parameter 2 has to be initialized with a number.

int main ()
{
	frame::change_rule_param (2, itoa (val (gParam2)+1));

	return 0;
}

The table describes how to configure layout rules. The actual rule implementation can be done either via Ison (PubServer) or by ALT-clicking the rule directly in InDesign®.

name = Name
     | Submenu^Name
     | Submenu^Submenu^Name
     ...
     | Name,,Shortcut
     | Submenu^Name,,Shortcut
     | Submenu^Submenu^Name,,Shortcut
     ...

The name of the layout rule is specified in the name attribute of actions. With a ^ separated path before the name, the rule can be placed in submenus of the panel's fly-out menu. Remember, however, that excessively long paths tend to reduce user-friendliness.

The following path specifications can be used to insert frame rules into the submenus of the standard frame rules:

• kLayoutRulesFrames^ : Sub menu Frames
• kLayoutRulesImages^ : Sub menu Images
• kLayoutRulesTexts^ : Sub menu Texts
• kLayoutRulesTables^ : Sub menu Tables
• kLayoutRulesMessages^ : Sub menu Messages

The name and all path parts are automatically translated into the language of the InDesign® used using the currently available translations.

With a shortcut definition separated by ,, (comma comma) you can assign a command key combination to the menu item. For information on defining keyboard shortcuts, click here.

Here is the definition of a rule kRemoveFrame, which should be shown in the flyout menu Frame -> A -> B. With Shift+Ctrl+Y the rule can be added to the currently selected frame. For the key kRemoveFrame a translation should be defined.

kLayoutRulesFrames^A^B^kRemoveFrame,,Shift+Ctrl+Y

The type of a rule is defined by the ClassID of the action:

• 36 : Frame rule
• 51 : Text placeholder rule
• 45 : Condition for frame rule
• 52 : Condition for text placeholder rules

Custom rules are always appended after the default rules in the flyout of the panel. With the attribute sequencenr of the action you can then define the further sequence. In case of missing or equal sequence numbers, the order is random.

Behavior   = Default##AllowedFor##Tooltip

Default    = 0 - 47
AllowedFor = 0 - 47

Activation and description of the rule are specified in the inputdocumentation attribute of the action. The information is given in a three-part ##-separated text.

The following values are assigned to the situations for executing a rule : 

Icon	Value	Situation
	2	Loading (the frame does not need a placeholder)
	1	After Create (through a template)
	32	Product Buildup
	4	Upon Reorganization
	8	After Geometry Changes

In the first part you define the situations that should be activated automatically when the rule is created. The specification is a sum of the situations gto be activated. Thus, 2 means that the rule will be activated only for Loading, with 3 the rule will be activated for Creation and Loading, and so on. With 0 or empty all situations remain deactivated.

In the second part you specify which situations can be activated. The number is a sum of the allowed situations. With 0 you allow nothing, with 39 (= 32 + 1 + 2 + 4) you allow everything except Geometry Changes, with 47 also geometry changes are allowed. If the entry is missing or empty, all situations are allowed.

Defaults that are not included in the allowed situations are automatically allowed. The specification 1##0##Help automatically activates Creation when the rule is added. However, if this situation has been disabled on the rule (e.g. for test purposes), it can also be enabled again - but all other situations cannot.

The rule should be activeted for Creation when adding and may additionally be activated for Loading.

1##2##My_Help

Missing or empty entries create an empty text field with the label Unused. Independently of this, these fields can also be provided with content and evaluated. However, in the interest of good user guidance, you should avoid these situations.

Param = Label
      | Label////Tooltip

In the simplest form, you simply specify the parameter name. An empty text field with the specified name will be created. However, please note that the label does not become too long!

Optionally and separated by ////, a help text describing the parameter can follow after the label. Please note that help texts are only displayed up to 255 characters. Help texts must not contain line separators! If line separators are required, they must be masked with <br> or <br/>.

Label and Tooltip are automatically translated into the language of the InDesign® used using the currently available translations.

The second parameter expects the specification of an RGB color

##Color////RGB values of the color each in the range 0-255, e.g. 255 128 0####

Param = Label^^Default
      | Label^^Default////Tooltip

The parameter is displayed as a named text field with the name Label and is filled with the value Default when newly created.

Optionally and separated by ////, a help text describing the parameter can follow after the label. Please note that help texts are only displayed up to 255 characters. Help texts must not contain line separators! If line separators are required, they must be masked with <br> or <br/>.

Label and Tooltip are automatically translated into the language of the InDesign® used using the currently available translations.

The second parameter expects the specification of an RGB color, default is Black.

##Color^^0 0 0////RGB values of the color each in the range 0-255, e.g. 255 128 0####

Param = Label
           Entry
           Entry
           ...
      | Label////Tooltip
           Entry
           Entry
           ...

Entry = [!]Label
      | [!]Key//Label

Parameters often have a defined list of supported values. For these cases, the values can be represented as named dropdowns. As with named text fields, the definition starts with the name Label of the dropdown.

Optionally and separated by ////, a help text describing the parameter can follow after the label. Please note that help texts are only displayed up to 255 characters. Help texts must not contain line separators! If line separators are required, they must be masked with <br> or <br/>.

Label and Tooltip are automatically translated into the language of the InDesign® used using the currently available translations.

Label and Tooltip are followed by a line-separated list of any length of the entries to be shown in the dropdown. The following characters are allowed as line separators:

\n
\n\r
\r
&#xA;
&#xD;

Unfortunately, line separators cannot be entered in the input fields of the Workbench or are automatically removed again when saving. You can therefore also use the character string :I: (colon, capital i, colon) as a separator for the individual values of popup menus.

Submenus in dropdowns are unfortunately not supported by InDesign® - so you can only create flat dropdowns here.

In the simple notation, enter the text to be shown in the entry only. Only the whitespaces at the beginning and end will be removed. The text will not be translated and will be included in the document as it appears in the dropdown. Specifications in this notation are useful in the following cases:

• Units of measurement like pt, pica, mm, ...
• Generally valid abbreviations like x, y, international brands, ...
• Names (z.B. paragraph styles, companies, files, ...)

If the list entry contains a language-dependent value, we recommend the slightly longer but much more helpful notation Key//Label!

For language dependent list entries you should use the slightly longer notation Key//Label. Whitespaces at the beginning and end are removed before use.

In the dropdown, the translation of Label into the current InDesign® language is entered (provided, of course, that you have defined this translation, which you can easily do with the panel Plug-Ins -> Comet Admin -> Translations). However, if the entry is selected in the dropdown, not Label but Key will be transferred to the document. So your layout rule has to evaluate only this key, regardless of the InDesign® language used. This way you have a user-friendly representation and be still independent of the InDesign® language.

Note: It is allowed and makes sense to use the same term for Key and Label. But even then of course : Key is the value that is taken (unchanged) into the document and that is used in the layout rule script. And Label is sent through the translation and used in the display of the palette.

Delimiters in the dropdown are created with a - (minus). Delimiters cannot be selected, so they will never be used as parameter values.

The default entry of the dropdown with which the parameter is assigned when the rule is added is marked with a ! (exclamation mark) at the beginning of the entry definition. If no default is defined, the first entry of the list is used as default. If several entries are marked with a !, the last entry found will be used.

A layout rule to adjust frame sizes might have parameters such as the following: 

1. A Key//Label-List, which dimension is to be changed.
2. A named textfeld for the amount.
3. A Value list without translations for the unit.
4. A Key//Label-List, whether (if possible) the frame proportions should be preserved.

Bei den allfälligen Übersetzungen können Sie zum Teil auf Standard-Übersetzungen zurückgreifen (im Text blau markiert), siehe hier. Für die rot hervorgehobenen Schlüssel müssen noch Übersetzungen angelegt werden. Dazu können Sie z.B. die Palette Zusatzmodule -> Comet Admin -> Übersetzungen verwenden.

For the translations you can partly use standard translations (highlighted in blue in the text), see here. For the keys highlighted in red, translations still have to be created. For this you can use e.g. the panel Plug-Ins -> Comet Admin -> Translations.

<outputdocumentation>k_DIRECTION////My_Rule1_Help
    h//k_WIDTH
    w//k_HEIGHT
    b//My_Both
  ##My_Value////My_Value_Help##My_Unit////My_Unit_Help
    mm
    !pt
    %
  ##k_PROPORTIONAL////My_Prop_Help
    y//k_YES
    n//k_NO
</outputdocumentation>

The entries in the popup menu can also be loaded dynamically when the corresponding document frame is displayed in the panel Layout Rules. The entries of the popup menues can be loaded with standard functions (e.g. all available object styles). If no standard function meets your needs, you can write your own script and fill the popup with that.

To do so, use the keyword @LOADLIST in place of the value list, followed by the function or ID of the action you defined:

     @LOADLIST Standard function | ActionID [Defaultentry]

The popup always contains the default value "Empty". A separator is always inserted between it and the dynamic values. You can only specify one @LOADLIST entry per parameter.

The second parameter of a layout rule can have an existing object style for its value. If no value was selected yet, Objectformat 1 is selected by default.

<outputdocumentation>Variable Values
    left
    !middle
    right
  ##Style
    @LOADLIST objstyles "Object format 1"
  ##[unbenutzt]
  ...

The table describes how to configure the rules. The actual implementation of the rule you do either via Ison (PubServer) or with ALT-click of the rule directly in the InDesign®.

In this rule, all parameters are loaded dynamically:

<outputdocumentation>Font
    @LOADLIST fonts "Courier New"
  ##Paragraph Styles
    @LOADLIST parastyles 2
  ##Character Styles
    @LOADLIST charstyles
  ##Table Styles
    @LOADLIST tablestyles 3
<outputdocumentation>

In addition to the default lists above, you can implement custom lists for parameters. These scripts must have the ClassID 44. They are executed every time a frame is selected in the layout rules panel. In the script, the global variable StringList gValues has to be filled each time. The following global variables are defined in addition to the usual global variables and gFrame:

In this rule, the values for the first parameter are loaded with Action 20014:

<outputdocumentation>ValueList
    @LOADLIST 20014
  ##Unused##Unused##Unused
<outputdocumentation>

This is a valid script for loading a dynamic value list:

int main ()
{
	stringlist::append (gValues, "aaa");	// index 2
	stringlist::append (gValues, "bbb");	// index 3
	stringlist::append (gValues, "ccc");	// index 4
	stringlist::append (gValues, "-");
	stringlist::append (gValues, "111");
	stringlist::append (gValues, "222");
	stringlist::append (gValues, "333");

	*gDefaultEntry = 4;

	return 0;
}

Similar to custom rules, you can also implement custom conditions. The conditions are also defined in the file actions.xml or the table actions with the following ClassIDs :

    ClassID 45 : Conditions for Frame Rules
    ClassID 52 : Conditions for Text Placeholder Rules

Whether a condition is met is determined by the return value of the main function of its script :

Text placeholder conditions that do not contain the variable gNewValue are ignored when called from the ToDo List Panel and considered a rejection (FALSE). You can find out more about how to correctly use gNewValue here, so that the ToDo List Panel can evaluate your placeholders properly.

The condition is met, when Parameter 1 of the IF statement is unequal 0. If Parameter 1 equals 0 (or a string), the condition is not met.

int main ()
{
	return val (gParam1);
}

Conditions rely on the same variables as rules, see here.

The configuration, including the parameter list for condition parameters and their descriptions, is analogous to rule configuration see here. The specifications for condition execution in inputdocumentation have to be made, even though are ignored.

Layout rules are stored in the respective frame or text placeholder. This happens automatically when editing the rule with the Layout Rules panel. Using the commands placeholder::sget_value and placeholder::change_tags you can also change the rules from cScript. Use the slot names "LayoutRules".

Rules and conditions use the same format:

int₁ int₂ 'param₁'\t'param₂'\t'param₃'\t'param₄'

Individual rules/conditions are separated by spaces. The following table describes the format of a rule or condition:

Here the string representing the rules shown above. Please note that because the default rules useKey//Label pairs for the entries of the value lists, the document saves the keys - although you see the (translated) labels. Line deimiters are inserted for better readabilty only.

-2 10 'ja' 'nein' '' ''
-3 10 'links' 'oben' '' ''
-3 -14 'Datei' '' '' ''
-18 10 'Image okay' '' '' ''
-4 6 '' '' 'nein' ''
0 -2147483647 '' '' '' ''

You can actually run layout rules of other frames from within cScript with frame::apply_layout_rules and itemlist::apply_layout_rules since v3.1 R1550 (Sept. 2009). This has two drawbacks: first, you can only run all rules of the target frames - frame selections are not possible. Second, you have to write the rules yourself.

With so-called Events, you can run rules of specific frames of the same Comet Group. Two steps are involved in this process:

1. The frame has to trigger the rule "Send Event"
2. In the target frame, a "Handle Event" Condition has to be defined, containing the desired rule.

The sender specifies which frame in the comet group (selected by its identifier) is meant and sends a key (an arbitrary text). The receiver checks the key and then runs all rules under the condition. It is allowed to trigger another event (even with the same key and to the sending frame) - you have to make sure there is a break condition defined (e.g. a check for text overset).

To allow the receiver to apply a rule, the rules on the sender and receiver have to be allowed in the same execution context sein.

The frames with identifiers A and B are in the same comet group:

A fires a "Send Event" after each repositioning with the key key 1 to the frame B:

In B checks in "Handle Event" if the key is correct and then applies the rule "Fit Frame".

If A is now moved by one pixel, the size of B B is adjusted.