Information Classification: External Restricted.
See https://www.chili-publish.com/security

Getting Started with Document Actions

Owned by Bram Verniest (Unlicensed)
Apr 22, 2020
10 min read

Concept

Document Actions allow administrators to set up rules inside the CHILI document which influence its content. They are often used in combination with Variable Data, where values of the variables influence the look and feel of the document (eg: showing or hiding certain sets of Layers based on the entered data).

Document Actions are triggered from (and can be edited in) a variety of locations: Document Action Triggers

While Document Actions allow for quite a bit of additional logic in a CHILI Document (on top of functionality which can be configured in the Editor itself), they are not intended to be a full scriptin language, and they do not expose all of the object model of a document. For complete and comprehensive scripting, JavaScript (client-side) or the SOAP webservices (server-side) are available. The purpose of Document Actions is to allow common logic to be created by users with some technical experience, but without necessarily being able to develop application code.

See Action Editor for an overview of the editor.

Command Statements

Every line in an action starts with a command:

  • set: used to set properties inside the document object model or in a local variable
  • declare: used to declare local variables, for use in the rest of the action
  • execute: used to execute a function
  • if / else / else if / end if: control statements for conditional logic
  • return: returns a value (if applicable to the action)
  • comment: used to add comments to your actions

Getting and Setting properties

Most of the functionality in Document Actions is available in the form of properties. These follow the syntax:

Target > Property

Where target either points to an object directly (eg "Document" or "ViewPreferences"), or requires a selection for a list (eg "Page", "Variable", "Color").

Depending on the type of the property, you will get different options for setting the value. For "ViewPreferences > ShowBleed", for example, you'll see "true" and "false" at the top of the next pulldown. Whereas "Document > Width" will allow you to enter a measurement unit.

The following properties are available in the Document Action Editor:

Document

  • width/height:
    • units
    • read/write
    • corresponding to the dimensions of the document
  • facingPages:
    • boolean
    • read/write
    • corresponds to the "Facing Pages" checkbox in the "Document Settings" Panel
  • zoom:
    • number or fit type ("fit page", "fit width" or "fit height")
    • read/write
    • gets/sets the current zoom
  • bleed/slug left/right/top/bottom:
    • units
    • read/write
    • corresponding to the document settings
  • spineWidth, spineHinge, flapWidth, flapWrap:
    • units
    • read/write
    • correspond with the matching document settings
  • languageName
    • string
    • read/write
    • If set, this property will attempt to load the language with the specified name from the BackOffice (Environment > Languages), and apply it to the workspace
  • variablesDefaultTextDirection
    • one of: "LTR" or "RTL"
    • read/write
    • returns or sets the default text direction for variables (matches the pulldown in the "Variable List" Panel)

ViewPreferences

  • viewMode
    • one of: "edit", "preview", "bookpreview"
    • read/write
    • returns or modifies the current editing mode
  • showBleed / showSlug
    • boolean
    • read/write
    • Updates the "Show Bleed" and "Show Slug" settings of the viewpreferences
  • displayQuality
    • one of: "highest", "high", "medium", "low", "none"
    • read/write
    • Updates the document display quality for images

Page

  • name
    • string
    • read only
    • returns the display name (including section prefix) of the page
  • selected
    • boolean
    • read only
    • returns true if the page is selected
  • includeInOutput
    • boolean
    • read/write
    • corresponds to the "Include in output" checkbox in the "Page Settings" Panel
  • sectionOptions.newSection
    • boolean
    • read/write
    • if true, a new section starts on this page (matches the configuration in "Page Settings")
  • sectionOptions.pageStart
    • number
    • read/write
    • if higher than 0, indicates a new page numbering start for the started section (matches the configuration in "Page Settings")
  • sectionOptions.prefix and .suffix
    • string
    • read/write
    • Prefix and Suffix for the started section (matches the configuration in "Page Settings")
  • sectionOptions.includeInOutput
    • boolean
    • read/write
    • Matches the "Include in output" checkbox for the started section in "Page Settins"

Frame

Frames are most often referenced by their "tag", which is configured in the "Frame Location" Panel

  • tag
    • string
    • read/write
    • returns or modifies the tag of the frame (as configured in the "Frame Location" Panel)
  • selected
    • boolean
    • read only
    • returns true if the frame is selected
  • type
    • string
    • read only
    • returns the type of the frame ("text", "image", "barcode", ...)
  • x, y, width, height
    • unit
    • read/write
    • Returns or modifies the location and dimensions of the frame
  • barcodeText
    • string
    • read/write
    • Returns or sets the applied barcode text, for frames of type "barcode"

Layer

  • id
    • string
    • read only
    • returns the id of the layer
  • name
    • string
    • read only
    • returns the name of the layer
  • visible
    • boolean
    • read/write
    • Gets or sets the visibility of the layer

Variable

  • value
    • string
    • read/write
    • returns the (internal) value of the variable
  • displayValue
    • string
    • read only
    • returns the display value of the variable (including prefix/suffix)
  • selectedItemName
    • string
    • read only
    • for variables of type "list", returns the name of the selected item
  • displayName
    • string
    • read/write
    • Returns or sets the display name of the Variable (as shown to the end user in the Variable Input Form)
  • info
    • string
    • read/write
    • Returns or sets the info / help field of the variable (as shown in the Input Form as inline help or as a tooltip, depending on the settings of the Variable)
  • prefix  / suffix
    • string
    • read/write
    • Returns or sets the Variable's prefix or suffix (concatenated with the "value" to become the display value, which is inserted into text frames)
  • visible
    • boolean
    • read/write
    • Matches the "visible" checkbox in the "Variable Settings" panel, and controls visibility of the Variable in the Input Form
  • imagePulldownDirectory
    • string
    • read/write
    • For variables of type "image", this property allows the input directory for the images to be controlled
  • imagePath
    • string
    • read/write
    • Returns the path of the selected image, or loads a new image if the path is set. The path is relative within CHILI's DAM (eg: "Dir1\Dir2\MyImage.jpg")
  • textDirection
    • one of "RTL", "LTR" or "INHERIT"
    • read/write
    • controls the text direction for the variable

Font

  • id
    • string
    • read only
    • Returns id of the font
  • name
    • string
    • read only
    • returns the full name of the font
  • family
    • string
    • read only
    • returns the font's family
  • style
    • string
    • read only
    • returns the font style

Color

  • id
    • string
    • read only
    • returns the id of the color (and is used to assign a color, for example to the applyFromColor property)
  • name
    • string
    • read only
    • returns the name of the color
  • applyFromColor
    • color ID
    • write only
    • when set to the ID of another color, all properties (type, values, ...) are duplicated from the original color to the current color
  • colorValue
    • color value: "cmyk:C-M-Y-K" or "rgb:R-G-B", where C/M/Y/K are numbers between 0 and 100 (inclusive) and R/G/B between 0 and 255 (inclusive)
    • write only
    • Modifies the color to cmyk or rgb, and applies a color value

When working with colors, two options exist to modify values. setting the "colorValue" property is used for simple modifications, using an inline editor in the Document Actions to apply either cmyk or rgb values. This can be called as:

set color MY_COLOR colorValue = colorValue XXXX

For more complex color configurations, you can create a series of document colors (in the "Colors" Panel) which are applied to a central set of colors. You might for example have the following colors:

  • MAIN
  • OPTION_BLUE
  • OPTION_RED

And a matching action which applies the blue/red options depending on a variable:

if variable MY_BLUE_CHECKBOX value is "true"

    set color MAIN applyFromColor = color OPTION_BLUE id

else

    set color MAIN applyFromColor = color OPTION_RED id

end if

see ?Common Document Actions for a more complete sample

ParagraphStyle

  • id
    • string
    • read only
    • returns the id of the style (and is used to assign a style in the applyFromStyle property)
  • name
    • string
    • read only
    • returns the name of the paragraph style
  • applyFromStyle
    • paragraphStyle ID
    • write only
    • when set to the ID of another paragraph style, all properties of the original style are duplicated to the current one

color

    • color ID
    • write only
    • Applies a new character color when set to the "id" property of a color (eg: set paragraphStyle MY_STYLE color = color MY_COLOR id)
  • font
    • font id
    • write only
    • Applies a new font when set to the "id" property of a font
  • fontSize
    • number
    • read/write
    • Sets or gets the font size for the paragraph style

CharacterStyle

  • id
    • string
    • read only
    • returns the id of the style (and is used to assign a style in the applyFromStyle property)
  • name
    • string
    • read only
    • returns the name of the character style
  • applyFromStyle
    • characterStyle ID
    • write only
    • when set to the ID of another character style, all properties of the original style are duplicated to the current one

color

    • color ID
    • write only
    • Applies a new character color when set to the "id" property of a color (eg: set characterStyle MY_STYLE color = color MY_COLOR id)
  • font
    • font id
    • write only
    • Applies a new font when set to the "id" property of a font
  • fontSize
    • number
    • read/write
    • Sets or gets the font size for the character style

AlternateLayout

  • name
    • string
    • read only
    • returns the name of the Alternate Layout
  • selected
    • boolean
    • read/write
    • Returns true if the layout is selected, or selects the layout if set to true

Url

  • full
    • string
    • read only
    • returns the full URL of the current editor.aspx page
  • host
    • string
    • read only
    • returns the host of the current editor.aspx page
  • queryString
    • string
    • read only
    • returns the querystring ("?arg=xx&arg2=yy", without the preceding "?") of the current editor.aspx page

Executing Functions

Next to setting and getting properties of objects inside the CHILI document, it is also possible to execute functions. Some functions are again executed on a target (eg: "execute document save" or "execute page 1 select"), and some are executed from special function targets (eg "set variable MY_VAR value = StringFunctions subString ...).

When selecting a function to execute, often you will need to provide arguments for the function. The "StringFunctions subString" function, for example, takes 3 arguments: an input string, a startIndex and a length.

Some functions simply execute something (eg "Interaction Alert" or "Page Select"). Others return a value (eg "StringFunctions subString"). In the latter case, the function can be used to set a property (eg: "set variable MY_VAR value = StringFunctions subString ...).

Document

  • save
    • Saves the document
    • returns: nothing
    • arguments: none
  • loadLanguage
    • Loads a new language for the current WorkSpace
    • returns: nothing
    • Arguments:
      • languageName
        • string
        • The name of the language as it is defined in the BackOffice (Environment > Languages)
      • applyToVariables
        • boolean
        • If true, any variable which has a value in the loaded language file is overwritten with that translated value

Page

  • select
    • Selects the page, and jumps to it in the Editor
    • returns: nothing
    • arguments: none
  • addFrame
    • Creates a new frame on the page, with the specified tag which can be used to reference the frame afterwards
    • returns: nothing
    • arguments:
      • tag
        • string
        • The tag (as configured in the "Frame Location" Panel) for the new frame
      • x
      • y
      • width
      • height
        • units
        • The position and dimensions of the new frame
      • layerID
        • id of a layer object
        • The layer on which to place the new frame

Frame

  • select
    • Selects the frame (and jumps to it in the Editor)
    • returns: nothing
    • arguments: none
  • delete
    • Deletes the frame
    • returns: nothing
    • arguments: none

Alternate Layout

  • select
    • Selects the Alternate Layout
    • returns: nothing
    • arguments: none

StringFunctions

  • getTranslatedString
    • Allows the use of strings from the loaded language file in Document Actions. Section, subSection and stringName can be found in the language management screen in the BackOffice (Environment > Languages), and can include the "Custom" section for your own strings
    • returns: string
    • arguments:
      • section
        • string
        • Name of the section
      • subSection
        • string
        • Name of the subsection
      • stringName
        • string
        • Name of the string to load
      • defaultValue
        • string
        • If the string is not found (or not translated), this value is used instead
  • toLowerCase
    • Returns a lowercase version of the input string
    • returns: string
    • arguments:
      • string
        • string
        • input which will be converted to lower case
  • toUpperCase
    • Returns an uppercase version of the input string
    • returns: string
    • arguments:
      • string
        • string
        • input which will be converted to upper case
  • subString
    • Returns a portion of the input string
    • returns: string
    • arguments:
      • string
        • string
        • input for the function
      • startIndex
        • number
        • 0-based index to start
      • length
        • number
        • Length of the substring to return
  • replace
    • Replaces a search string in the input string
    • returns: string
    • arguments:
      • string
        • string
        • Input for the function
      • find
        • string
        • Term to search for
      • replace
        • string
        • Term to replace the result with
      • caseSensitive
        • boolean
        • If true, the find string will be looked for including case
  • replaceRegExp
    • Replaces a regular expression in the input string
    • returns: string
    • arguments:
      • string
        • string
        • Input for the function
      • regexp
        • string
        • Regular Expression to search for
      • replace
        • string
        • Term to replace the result with
  • contains
    • Returns true if a term is found in the input string
    • returns: boolean
    • arguments:
      • string
        • string
        • The input for the function
      • find
        • string
        • Term to search for in the input string
      • caseSensitive
        • boolean
        • If true, the search will be case sensitive
  • indexOf
    • Returns the index (0-based) of a search term in the input string (or -1 if the term is not found)
    • returns: number
    • arguments:
      • string
        • string
        • The input for the function
      • find
        • string
        • Term to search for in the input string
      • caseSensitive
        • boolean
        • If true, the search will be case sensitive
  • lastIndexOf
    • Identical to indexOf, but the search starts at the end of the input string
  • length
    • Returns the length of the input string
    • returns: number
    • arguments:
      • string
        • string
        • The input for the function
  • trimStart and trimEnd
    • Removes the specified string from the start or end of the input string
    • returns: string
    • arguments:
      • string
        • string
        • The input for the function
      • find
        • string
        • Term to search for in the input string
      • caseSensitive
        • boolean
        • If true, the search will be case sensitive
  • padLeft and padRight
    • Ads characters to the left or right of the input string
    • returns: string
    • arguments:
      • string
        • string
        • The input for the function
      • padChar
        • string
        • Character to add to the new string
      • newLength
        • number
        • The total new length of the returned string. If the input string is longer than this length, it won't be truncated
  • matchesRegExp
    • Checks whether or not the input string matches the provided Regular Expression
    • returns: boolean
    • arguments:
      • string
        • string
        • The input for the function
      • regexp
        • string
        • Regular Expression to use to match (eg: /FIND/gi)
  • split
    • Returns an item in the string split by input characters (eg: "this-is-a-string" as input, with splitChars = "-" and itemIndex = 2 would return "a")
    • returns: string
    • arguments:
      • string
        • string
        • The input for the function
      • splitChars
        • string
        • The combination of characters to use to split the string. Each character will count, so ".," will split on all instances of "." and ",", rather than on the exact string ".,"
      • itemIndex
        • number
        • 0-based index of the part of the split string which should be returned

NumberFunctions

  • toString
    • Converts a number to a string, with provided formatting
    • returns: string
    • arguments:
      • number
        • number
        • The input for the function
      • thousandsSeparator
        • string
        • optional separator character for thousands
      • decimalSeparator
        • string
        • separator for decimals
      • rounding
        • rounding type
        • Method used for rounding the input string
      • precision
        • number
        • Decimals used as precision for rounding
  • isNumber
    • Checks if the input is numeric
    • returns: boolean
    • arguments:
      • inputString
      • string
      • The input to check
  • toInteger
    • Converts the number to the nearest integer
    • returns: number
    • arguments:
      • number
        • number
        • The input for the function
  • absolute
    • Converts the number to its absolute value
    • returns: number
    • arguments:
      • number
        • number
        • The input for the function
  • round
    • Rounds the input number
    • returns: number
    • arguments:
      • number
        • number
        • The input for the function
      • precision
        • number
        • The amount of decimals to maintain
  • roundUp / roundDown
    • Rounds the input number up or down to the nearest integer
    • returns: number
    • arguments:
      • number
        • number
        • The input for the function
  • inRange
    • Returns true if the input number falls within the specified range (inclusive)
    • returns: boolean
    • arguments:
      • number
        • number
        • The input for the function
      • minimum
        • number
        • minimum for the range (inclusive)
      • maximum
        • number
        • maximum for the range (inclusive)
  • random
    • Returns a random integer between 0 and the provided maximum (inclusive)
    • returns: number
    • arguments:
      • maximum
        • number
        • The upper bound (inclusive) for the random integer

JavaScript

  • eval
    • Executes a JavaScript in the context of the parent window of the editor.aspx page
    • returns: string, as returned by the evaluated script
    • arguments:
      • script
        • string
        • The script to execute (typically only to call a more complete function in the containing web page)

Url

  • getQueryStringValue
    • Returns the value of a query string argument ("?arg1=XXX&arg2=YYY") of the editor.aspx page
    • returns: string
    • arguments:
      • keyName
        • string
        • Name of the querystring argument to fetch
      • defaultValue
        • string
        • Value to return if the QueryString argument is not provided (or empty)

Interaction

  • alert
    • Shows a popup message to the user
    • returns: nothing
    • arguments:
      • title
        • string
        • Title for the popup window
      • message
        • string
        • Content of the popup window

Conditional statements

Within an action, you can use control statements to make execution of certain lines optional:

  • if
  • else
  • else if
  • end if

Each if / else if statement consists of:

  • A first condition (see lower)
  • An operator, which (depending on the type of the first condition) can contain:
    • is
    • is not
    • contains
    • starts with
    • ends with
    • <
    • <=
    • >
    • >=
  • A second condition

Each condition in its turn can consist of multiple parts as well:

  • A first property or function. This is required. For example
    • document width
    • local MY_LOCAL
    • variable MY_VARIABLE value
    • variable MY_VARIABLE selectedItemName (for list variables)
  • An optional operator to apply on the first result, such as:
    • & (concatenate strings)
    • +
    • -
    • /
    • *
  • A second property or function, which works on the first one using the supplied operator
  • More operators as needed

Working with local variables

When calculations start getting more complex (or if the result of a calculation is used multiple times throughout the script), it can make sense to declare a local variable. To start, you need to:

declare TYPE MY_VAR

Where MY_VAR is the name of your local variable (which you'll be able to reference later on), and TYPE is on of the available types for local variables:

  • boolean
  • string
  • number
  • unit
  • frame

Once declared, you can set the value of the variable as follows (assuming it is a unit):

set local MY_VAR = document width

set local MY_VAR = local MY_VAR + unit 10 mm

set document width = local MY_VAR

Returning a value

Certain actions may require a value to be returned. The "Visibility" action of a variable, or example, will hide the variable unless the action returns "true". Similarly, the "Validation" action of a variable will consider the variable to be valid unless a string is returned (in which case that string is used as the warning to the end user). For example:

if StringFunctions length ( variable MY_VARIABLE value ) is not 5

    return string "THIS VARIABLE SHOULD CONTAIN 5 CHARACTERS"

end if

All information on this page must be treated as External Restricted, or more strict. https://www.chili-publish.com/security