Introducing the YAML Content Module

I always look forward to DrupalCon each year for a number of reasons. One of the reasons chief among them is the refreshing excitement of being immersed in the community. I always enjoy the encouragement and guidance our community offers. A number of the conversations I had during DrupalCon offered this same encouragement and guidance to push forward with a public release of a module I've been working on and maintaining privately. Following up on this advice, I'd like to proudly introduce my new module: YAML Content.

What does it do?

The YAML Content module provides a solution for outlining content to be imported into a site using an easy to write and understand structure in YAML. Since the content is written in YAML, it's easy to visualize the content hierarchy through the indentation, and the content can always be updated by adding more to it later and re-importing. This makes it easy for demo content to evolve over the course of a site build as new site architecture is defined and needs to be demonstrated for review and testing.

What makes it different?

There are a number of different modules that tackle content import and migration, but one point of difficulty I came across with each of them was the interrelation of content. For example, how do you define an entity relationship in your content files if you're not sure what the entity ID is already? YAML Content aims to address this by providing support for dynamic processing of the content at the time of import. Through the use of processing callbacks that may be defined throughout the content, data may be filled in and altered during the import process to do various tasks dynamically including:

Query and reference existing entities
Import and reference managed data files
Import and assign image files

Since the content structure parallels the entity and field architecture and relies on general interfaces applicable to all entity types, the same content structure may be used to create nearly any entity type defined in the system. This allows for a great deal of flexibility across various use cases for the module, but some content I have already seen it used for include:

Nodes
Block content
Taxonomy terms
Menu links
Media entities
File entities

How do I use it?

If you're still reading I'm sure this all sounds great, but the important question is, "How do I use it?" There is no UI for the module, but by enabling it and creating content files for import, Drush may be used to import the content into the database. YAML Content offers a number of convenient Drush commands to use for importing content from various locations. To see the full list of them, run the following command:

drush --filter=yaml_content

Basic Usage

For basic usage, anyone may follow the steps below. For more complex usage interacting with the service directly see the next section.

Enable the module
Create YAML content files in a custom module or profile
Use Drush to import the files
- drush yaml-content-import-module <module_name>
- Example: drush yaml-content-import-module yaml_content

Developer Usage

If you're aiming to interact with the import services more closely, see the code snippets below. For additional reference the drush commands in yaml_content.drush.inc might be helpful as well.

// Prepare the import configuration and service.
$my_content_module = 'my_module';
$path = drupal_get_path('module', $my_module);
$loader = \Drupal::service('yaml_content.content_loader');
$loader->setContentPath($path);

// Prepare a list of content files to import.
$content_files = [
  'file_a.content.yml',
  'file_b.content.yml',
];

// Generate the demo content and output a helpful message when complete.
$loaded_entities = [];
foreach ($content_files as $file_name) {
  $loaded = $loader->loadContent($file_name, $update);
  $loaded_entities = array_merge($loaded_entities, $loaded);
}

Assumed file structure

Wherever you choose to place your content, whether in a module, a profile or an arbitrary subdirectory, there is a certain directory structure assumed to find the content data and associated files for import.

Module/Profile directory
- /content
  - All *.content.yml files containing content for import into the system should be located here.
- /images
  - Any images being referenced for import using an image callback for loading should be located here.
- /data_files
  - Any file assets being referenced for import using a file callback for loading should be located here.

There is much more potential to explore with the module, and I'll be providing more in-depth guidance for both basic content creation and more advanced features of the module in a later post. Until then, feel free to post any issues, feature requests, or even patches in the issue queue. For more detailed examples of content and other documentation see the documentation section on Drupal.org as well. Otherwise, feel free to let me know what you think in the comments!

Additional Resources

YAML Content module | External
Module documentation | External
Reference Card | External
Wikipedia: YAML | External