Information for: DEVELOPERS   PARTNERS   SUPPORT

Integrating JS components with Acquia CMS

Drupal Component module

With the Component module, you can easily add your components and applications to Drupal CMS. This module simplifies the process of adding JS components through YAML configuration files.

With this module, you can create a *.component.yml file that can be added to a module or theme. After the file is created, the component becomes available as a Drupal block, and you can place it using the Block layout page.

You can also add a configuration form by using the *.component.yml file so that site builders or editors can configure the block as needed. For example:

  • A text field to store data such as names or text identifiers
  • A select list to provide data options
  • Radio buttons to provide the ability to select data
  • A Checkbox widget to provide the ability to select multiple values
  • Other widgets such as Color selection and Date

Drupal Component module operations

  • An auto-discovery mechanism finds the *.component.yml file for an enabled module or theme. The components are placed in the “component” subfolder shipped with the module or theme.
  • A component is a block plugin called ‘ComponentBlock’. It is an extension of the Block entity in Drupal that helps to interact with a component such as a Drupal Block.
  • You can also create a “library” component that registers your JS code as a Drupal library without a block. This is useful for creating shared dependencies across block components.
  • From the *.component.yml file, Drupal identifies what this component is called, where the assets are located, and how the block can be configured. The module creates a library definition for each component, loads any other library dependencies, and renders the default html to the page.
  • On the page load, the HTML and JS load normally as they load in Drupal.
  • For the integration, JS developers do not need to know Drupal or PHP programming. Each component is available in Drupal as a library and that is how the code is shared by listing as a dependency.

Acquia CMS Component module

Acquia created a custom module ‘acquia_cms_component’ that showcases how to create JS components using the Component module.

Directory structure of the Acquia CMS Component module

The following is the directory structure of the Acquia CMS Component module:

directory-structure-new

Directory Description
components Contains files related to a JS component.
block

Contains the react_component_block subfolder, which stores files related to the react component block. It is the main location where the react components are built. The subfolder contains:

  • react_component_block.component.yml: The configuration file responsible for building the react component block. You need this file for creating the JS component. This file contains the code in the key:value format and is responsible for building a Drupal block for the JS component.
  • react_node_block.css: The file that contains the code for styling the component.
  • react_node_block.js: The file where the JS code for the component is written.
  • react-node-component.html: The file that contains the outer structure of the react component.
libraries

Contains the following subfolders:

  • api_library: Contains the api_library.components.yml file for including the Drupal API JS file which is the Drupal library for building JS components using JSON-API.
  • react_library: Contains the component yml file for including the react JS libraries.

All other files such as composer.json, LICENSE.txt, README.md, and CONTRIBUTING.md are the standard Drupal module files.

Component YAML file structure

The components directory of a module or theme contains the YAML file. To create the *.components.yml file, you don’t need to know Drupal or PHP coding. However, you must be familiar with Symfony YAML coding.

The following is the file structure of the react_component_block.component.yml file:

yaml-structure

Field Description
name The label of the component.
description The description of the component.
type The type of the component. For example, block, library, or plugin.
css The relative location of CSS file(s).
js The relative location of JS files(s).
template The relative location of markup.
dependencies Any other components or libraries that should also be loaded.
form_configuration The user input form to collect and pass data to the component.

Using the Acquia CMS Component module

To use the Acquia CMS Component module, you must first install it by using one of the following methods:

  • Mention the module in the composer.json file.
  • Run the composer require drupal/acquia_cms_component:^1.0 command to fetch the module.

To use the module:

  1. Log in to the Acquia CMS user interface.

  2. Click Structure > Block layout.

    The system displays the Block layout page.

  3. Search for the JS component block. For example:

    place-block

    The system displays the block available to be placed.

  4. Click Place block.

    The system displays the Configure block dialog box:

    configure-block

  5. Complete the form configuration for the JS component.

  6. Click Save block.

  7. Go to the page as a site visitor and verify that the JS component is appearing on the Drupal website.

You can add your own JS components and libraries to the codebase, and allow site builders to configure and place those components like any other block in the system.