Getting Started
===============

`Config Actions <http://drupal.org/project/config_actions>`_
provides a pluggable framework for easily manipulating
configuration data via simple YAML files with the goal of creating truly
reusable software components in Drupal.

Example use cases include:

* **Templates**
    the ability to provide a configuration template file containing
    variables that can be reused and replaced to create new configuration. For
    example, a template for adding a certain field to a content type where the
    content type isn't yet known.

* **Override**
    the ability to easily "override" configuration provided
    by core or other modules. These is not a "live" overrides system but simply a
    method to import changes into the config system.

**NOTE**: This is a Developers module and requires creating custom modules
containing YAML files that contain the config actions to be performed.

Action Files
------------

Actions are listed in a ``config_actions.yml`` file located in the top-level folder
of your custom module.  When your module is enabled, the actions in this file
will be executed.

@TODO: A drush interface allows you to execute actions manually.

@TODO: When Drupal Updates are run, any new actions added to your file are executed automatically.

An *action* is a list of "option" keys and values. Various global options are
available, and additional options can be added by specific plugins.

Nested Actions
--------------

Actions can be nested within each other.  Using the ``actions`` option you can
list additional sub-actions to be executed.  All options from the main parent
action are inherited in each sub-action but can be overridden by the sub-action.

For example, the top-level action can specify the ``source`` and ``dest`` options
then each sub-action could specify different plugins, or different ``replace``
option values, or even override with different ``source`` or ``dest`` values.
This allows related actions to be grouped and reduces the amount of repeated
text between similar actions.

When nesting or naming actions, each new action within the ``actions`` list
requires a unique id key.

For example::

  actions:
    myaction1:
      option1: value1
      option2: value2
    myaction2:
      option1: value1
      option2: value2
    ...