Variable Replacement

A key feature of Config Actions is the ability to perform variable substitutions within the configuration data.

Variables

Variables have the syntax: %variable_name% where “variable_name” is the alphanumeric name of the variable (with underscores or hyphens allowed)

The value of a variable is specified in the action file using the form:

"%variable_name%": value

Anywhere else in the action or included template files, a reference to %variable_name% will be replaced with the value.

String Replacements

The replace option is an array of string replacement patterns and values. The above syntax for variables actually causes an entry to be made into the string replacement array. But you can actually replace any string value. For example:

replace:
  foo: bar

will cause any text matching “foo” to be replaced with the value of “bar”.

Inherited Variables

Variables and string replacement values are passed from action to sub-action. Typically, global values for variables are set at the top of the action file, allowing any other modules that “include” the action to override the value.

For example, if ActionA.yml had the contents:

"%bundle%": article
"%name%": "Article"
source: node.type.%bundle%
value:
  name: %name%

then another action could “include” it and change the variable data that is passed:

plugin: include
file: "ActionA.yml"
"%name%": "My Article Content"

Sub-actions can also override variable values. For example:

"%name%": "Article"
source: node.type.%bundle%
actions:
  action1:
    "%bundle%": article
    value:
      name: "My article"
  action1:
    "%bundle%": page
    value:
      name: "My page"

Each sub-action sets its own value of “%bundle%” and the value of source is automatically recomputed for each action.

NOTE: When specifying variables directly within a sub-action, any other module including this action will not be able to override it. External actions will normally only override the global value of the variables in the file. To force a sub-action variable to be overridden, you can specify the exact action id (such as “action1”) you want to include rather than including the entire file.

ADVANCED Usage

The following topics are for more advanced usage and understanding.

### Option Variables

Each “option” in your action is available as a pre-defined variable. For example:

source: [ "%dest%", node.type.template.yml ]
dest: node.type.article

will automatically expand to:

source: [ node.type.article, node.type.template.yml ]
dest: node.type.article

### The special “id” variable

In addition to the pre-defined option variables, the “id” of each action is available via the %id% variable. For example:

source: "node.type.%id%"
path: [ "description" ]
actions:
  article:
    value: "This is the article description"
  page:
    value: "This is the page description"

This would execute two sub-actions, and the key value of each sub-action is used as the %id% variable, which is then replaced in the source option. Thus, the description of the “article” and “page” content types can be easily changed without needing to specify the source directly in each sub-action.

### The special “key” option

To parse the action “id” into other user-defined variables, use the key option to specify the pattern of the action id. For example, here we load different template files based on the name and type of fields being created:

source: "field.field.node.%type%.yml"
key: "%bundle%.%name%.%type%"
path: [ "description" ]
actions:
  article.my_text_field.text:
    value: "Description of my_text_field
  page.my_image_field.image:
    value: "Description of my_image_field

This would first load the “field.field.node.text.yml” template and define the variables: %bundle%: article, %name%: my_text_field, %type%: text and next it would load the “field.field.node.image.yml” template and define the variables: %bundle%: page, %name%: my_image_field, %type%: image

### Replacement Locations

You can control which options perform string replacement, and whether the patterns are replaced in just the array values within config data, or also in the keys.

The replace_in option overrides the array of options that perform string (and variable) replacements. The default of this array varies from plugin to plugin. Override it to specify only the exact options to replace. For example:

source: "foo.bar"
dest: "bar.foo"
replace:
  foo: bar
replace_in: [ 'dest' ]

will only replace “foo” in the dest option but not in the source option.