Scenarios

What does this module do?

This module provides an API that uses a single hook: hook_scenario_import. This hook allows any module or installation profile to be used as a "scenario" (e.g. demo/example/default) with content and configuration packaged. The Scenarios API can be used to enable, disable and reset a scenario.

Scenario modules use Drush commands for enablement, reset and removal.

Install and import migrations for a scenario module.
drush enable-scenario my_module

Reset a scenario rolling back content and re-importing.
drush reset-scenario my_module

Roll back migrations and uninstall a scenario module.
drush uninstall-scenario my_module

Scenarios can also be used by installation profiles in a seamless fashion.

Apply the core patch from this issue #2924549: Invoke hook after a site install is complete

Install your own installation profile that declares itself a scenario using the standard install commands.
drush si dfs_dev

What is a Scenario?

A scenario is a module or profile that enables configuration AND content on a Drupal website. Scenarios work like Features but they also define migrations for content. Scenarios are used extensively by the Demo Framework distribution to provide a number of various Drupal demos. Scenarios can be used by anyone looking to ship their project with default content and configuration that can easily be reset or removed later on.

How does a module or profile declare itself a scenario?

Its pretty simple. Add a mymodule.scenarios.inc to your project directory. If your project is an install profile, then myprofile.scenarios.inc in the profile directory.

In that file, declare the hook_scenarios_info hook. In this example, dfs_dev is the Scenario profile but this can also be a module name.

/**
 * Implements hook_scenarios_info().
 */
function dfs_dev_scenarios_info() {
  return [
    'dfs_dev' => [
      'label' => t('DFS DEV'),
      'description' => t('Demo Framework Scenario for Development Testing.'),
      'migrations' => _dfs_dev_migrations(),
    ],
  ];
}

Under the migrations key, you can use a helper function or list your own array of migrations you want to run. For example, in our myprofile.profile file we can declare the helper function that returns the migrations array.

/**
 * Helper function to return a list of migrations.
 *
 * @return array
 *   An array of migrations for dfs_dev.
 */
function _dfs_dev_migrations() {
  return [
    'import_block_basic',
    'import_term_tags',
    'import_node_page',
  ];
}

That's it!

Once you install your profile (recommended path for a scenario), subsequent migrations will run and any code you put inside hook_scenarios_post_enable
will also be run.

Contrib modules can support scenarios by thinking about the usecase of what they might want to happen after an installation profile with content is installed. For example, the Material Admin Support module declares its own *.scenarios.inc file and re-installs itself after a scenario is enabled.

function material_admin_support_scenarios_post_enable($scenario) {
  // After a scenario has been enabled, load the .install file and run
  // the installation again to overwrite any changes that might have occurred.
  module_load_include('install', 'material_admin_support');
  material_admin_support_install();
}

If one declares a scenario inside a module, it is recommended to enable that scenario using the drush commands after a site is installed. E.g. drush si standard && drush es my_scenario