Layout rules are scripts that are associated with frames and can be executed in the following situations:

Frames can have any number of layout rules. Each rule can be provided with additional parameters.

In addition, layout rules can be provided with conditions which can be nested in arbitrary fashion.

This way complex decision trees can be created.

Type Description
After loading After loading the placeholders of a frame. The frame itself does not have to have a placeholder.
After resize or reposition The rule is executed whenever a frame changes size or position in the document. You should use this type of rule sparingly.

This feature is currently in an experimental state!

The execution of layout rules can be made dependent on conditions. In addition to a series of standard conditions, you can also create your own conditions. Conditions can have an ELSE branch and can be nested as deep as you like. Conditions cannot be negated or linked with 'And' or 'Or'. However, the corresponding constructions can easily be reformulated:

A rule R is to be executed if the condition A not is fulfilled.

In this case, execute the rule in the else branch:

if A
else
    R
at the end

The rule R should be executed if the conditions A and B are fulfilled.

Set the second condition as a subcondition in the first:

if A
    if B
        R
   end
end

The rule R is to be executed if either the condition A or the condition B (or both) are fulfilled.

The obvious solution to make two if statements in a row, once for A and once for B, has a small flaw : If both A and B are fulfilled, R is executed twice. In this case, it is better to use the following construction:

if A
    R
else
    if B
        R
   end
end

The execution status of conditions is automatically calculated from the status fields of the underlying rules. You cannot set the execution status of conditions manually.

Some rules are available built-in. Here is a list of all standard rules for text frames and pictures:

Name ID Description
Fit frame -22

Adjust the frame size to the content. Multi-line text frames are adjusted in height.

Set frame size -28

Set the width and height of the frame.

Set frame size proportionally -200

Sets the size of a frame proportionally. For this, the desired size of one side (horizontal / vertical) and optionally a maximum size of the other side are specified.

Hidden/Visible -10 Make the frame invisible/visible. Invisible frames can be made visible again with frame::show or in the layer palette.
Move to layer -4

Move the frame to the specified layer. If the layer does not yet exist, it is created behind the layer specified in the second parameter. If the first layer name is missing, a new layer with an automatic name is generated. If the second name is missing, new layers are created as the first layer.

In addition, you can specify whether layer locking should be ignored or not. Attention: If frames are moved to locked layers, the document selection may change!

Scale text -8 Scale text such that the frame is filled and there's no overset. If the first parameter is set to true, text without overset is unaffected.
Position frame -13 Move the frame relative to the position of another frame in the same comet group. The frame has to have a greater identifier than the reference frame.
• Miscellaneous
Beep -16 Produces a tone when the rule is executed.
Show message -17 Shows a dialog with a message.
Write log message -18 Writes a message to the logfile.

Further standard rules may be added.

You can define any number of custom rules for frames and text placeholders. The rules are defined in actions.xml or in the table actions with the following ClassIDs:

   ClassID 36 : Frame rules

The name given in actions is shown in the Rules popup. If you want to insert separators, use a minus (-) as the name. You can use the sequence number to define the order in the menu.

The plugin development tools provided by Adobe do not provide popup menus with submenus. Unfortunately, you cannot sort your layout rules into submenus.

The scripts of layout rules can use all script functions. Note however that calls like document::close can lead to errors.

- ->

The scripts should start with the following includes :

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

In all calls of layout rules the current frame is defined as usual with gFrame.

In addition to the generally valid global variables such as gFrame, gDocument, ... a number of other global variables are defined:

Name Type Description
gFrameLeftBefore gFrameTopBefore gFrameRightBefore gFrameBottomBefore
float
Current frame coordinates before applying the rule.
gParam1
gParam2
gParam...
char*

Each script has additional parameters whose values can be defined in the palette : The values are stored at the frame per rule and condition. About the configuration of the parameters see here. If the parameters contain numbers, these numbers must be converted from the string with val or fval.

The parameter values may be changed in the script. A maximum length of 5000 characters is allowed.

gWhen
int

In which situation was the rule called? One of the values 1, 2, 4, 8 or 16, see here.

The fields inputdocumentation and outputdocumentation are used for the script description and parameters displayed in the panek. The following syntax is expected:

Field Contents Description
inputdocumentation Standard_Situations##Allowed_Situations##Description The first two values are one number each. They indicate when the script should be executed by default (first value) and in which situations it is allowed (second value). below is an example. The following values are defined (and can be added in each case) :

   2   
   1   
  32   
   4   
   8   

The third field contains a short description of the rule. It is shown in the palette in the tooltips of the popup menu and the list entries.

outputdocumentation ParamLabel1##ParamLabel2##ParamLabel3##ParamLabel3

ParamLabelN = Label[^^Defaultvalue][////Description]
Popup value1
Popup value2
...

The strings are used to label the parameters that each rule can have. The specifications should be short!

At the end of the name (after a possible default value separated by ^^, but before possible parameter lists) a description of the parameter can be added. The description is shown as a tooltip at the parameter. The description begins with the introduction

////

and must not contain line separators to distinguish them from any Parameter lists. Line separators within the description can be specified with the specification

<br>

Other HTML tags not defined. Please note:

  • Texts in tooltips cannot be formatted
  • Illustrator limits the text length of tooltips to 255 characters.

Here is an example for the description of a rule.

inputdocumentation a layout rule that should be executed after loading, but should be allowed for all other situations except after building. If a user changes this setting, he can activate all fields except the building blocks.

.

2###15##Your documentation

2 is "Load"

Rules often have a fixed list of values for a parameter to be displayed in a popup. You can give the parameter name a list of values separated by line separators (\n, \n\r, \r, &#xA;, &#xD;)*. These values are then displayed in a popup after the parameter name. The selected value of the popup menu is then always stored in the document. Parament name and values are trimmed (all whitespaces before and after are removed). The text selected in the popup is passed on as the parameter value.

On ! at the beginning of an entry marks the entry as default entry. A minus (-) creates a separator in the popup.

* In the input fields of the Workbench unfortunately no line separators can be entered, respectively these line separators are automatically removed again. You can therefore also use the character string :I: (colon, large i, colon) as separator for the individual values of popup menus.

To assign a default value to parameters without value lists, write this value, separated by ^^ (and before a possible description of the parameter separated by ////), after the name of the parameter.

Layout rule with the two parameters X and Y . X can have the values left/middle/top. X can have the values top/middle/bottom. Both values can be set via popup menus. The parameter distance is to be preset with the value 14.1.

<outputdocumentation>X
   left
   !middle
   right
  ##Y:I:above:I:!middle:I:down
   ##distance^^14,1##[unused]
</outputdocumentation>

The popup menu entries can also be loaded dynamically if the respective document frame is shown in the panel layout rules. The popup menu entries can be loaded using standard functions (e.g. all available paragraph styles). If none of the standard functions meets your requirements, you can also write a script yourself and fill the popup with it.

In the value list of the parameter, enter the keyword @LOADLIST followed by the function or the ID of your defined action instead of single values:

     @LOADLIST Standard function | ActionID [default entry]

The popup always contains the value "Empty" by default. A separator is inserted between this entry and the dynamic values. Only one @LOADLIST entry per parameter can be specified.

The second parameter of a layout rule can get an existing paragraph style as value. If no value has been selected yet, Parastyle 1 is selected as default.

<outputdocumentation>Variable values
   left
   !middle
   right
  ##Style
    @LOADLIST parastyles "Parastyle 1"
  ##[unused]
  ...

The following standard lists are defined. They are simply addressed by their name (case sensitive). The function name can be followed by a number or a string to define the default entry.

Function Default selection Description
parastyles

String or Index

If the specification is missing, the "blank" entry of the menu is selected.

If the String contains spaces, it must be enclosed in quotation marks.

You can also set the selection via Index. Note that the first two entries ("Empty" and the separator) are counted and that the count is 0-based. Your actual first entry therefore has the index 2.

.
All paragraph styles defined in the current document (see palette P paragraph formats)
charstyles All character styles defined in the current document (see palette character formats)

In this rule all parameters are dynamically loaded:

<outputdocumentation>Font
    @LOADLIST parastyles 2
  ###character style
    @LOADLIST charstyles
<outputdocumentation>

In addition to the above standard lists, you can also implement your own lists for parameters. These scripts must have ClassID 44. They are executed each time a frame is selected in the Layout Rules panel. In the script the global StringList gValues defined here must be filled. The following global variables are defined in addition to the general global variables and gFrame :

Name Type Description
gValues

StringList

These values should be displayed in the popup. If the values are to be localized, you must do this with the help of the translate function in the script.
gDefaultEntry int*

Index for the default entry of the list.

Note that the first two entries ("Empty" and the separator) are counted and that the count is 0-based. Your actual first entry has the index 2.

.
gRuleID int ID of the calling rule
gRuleName char* Name of the calling rule

In this rule, the values for the first parameter are loaded using the action 20014:

<outputdocumentation>Value list
    @LOADLIST 20014
  ##Unused#Unused#Unused#Unused
<outputdocumentation>

This is a valid script to load 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;
}

Like custom rules,own conditions can be also implemented. The conditions are also defined in actions.xml or in the table actions with the following ClassIDs:

   ClassID 45 : Conditions for frame rules

If a condition is fulfilled or not, the return value of the main function of the script is used :

return Description
return 0; Condition not fulfilled
else Condition fulfilled

The condition is fulfilled if the parameter 1 of the IF statement contains a number not equal to 0. If the parameter 1 equals 0 (or a string), the condition is not fulfilled.

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

Conditions have the same environment variables as the rules, see here.

The configuration including the parameter lists for condition parameters and their description is done the same way as in the rules, see here. The specifications for the execution of the condition in inputdocumentation must be specified, but are ignored.