Skip to main content
Version: v1

Module scaffold

The module scaffold, ys_base, is a working custom module to build your project's own code on. It comes with a deploy file and a test scaffold already in place.

This page is for developers adding custom code to a project built from Vortex. It describes the custom modules the template ships, so you can decide what to build on, what to learn from and what to remove. For the contributed modules, see Contributed modules.

The following installer questions decide which custom modules ship:

  • Custom modules selects the base, search and demo modules. All 3 are selected by default.
  • Services drops the search module when you leave Solr out. Solr is selected by default.
  • Use a second database for migrations? decides ys_migrate. It defaults to No.

Use ys_base for general-purpose code that doesn't belong in a dedicated, feature-specific module.

The ys prefix abbreviates your project's machine name, your_site here. Use the same prefix for all your custom modules, and the site machine name for the theme, so each module and theme name identifies its project. The installer suggests both names:

  • The Custom modules prefix question offers up to 4 characters from the machine name. A name with underscores gives the initials of its words, such as ys for your_site or sw for star_wars. A name without underscores gives its first 4 characters.
  • The Custom theme machine name question offers the machine name itself.

The your_site and ys names, and the other tokens like them, are placeholders. The installer replaces them with your project's own names when you install Vortex. The 1 exception is ys_migrate, which keeps its name.

Deploy file​

The ys_base.deploy.php file is a Drush deploy file: during site provisioning, Drush runs each of its ys_base_deploy_*() functions once and records which ones have run. Its single hook, ys_base_deploy_install_active_theme(), installs the core Olivero theme and sets it as the default. When the project has a custom theme, the hook also installs that theme and makes it the default in place of Olivero.

Demo module​

The ys_demo module demonstrates the integration patterns for 3 contributed modules:

  • Drupal helpers - utility facades for deploy hooks
  • Generated Content - plugin-based content generation
  • Testmode - content filtering during Behat tests (declared as a dependency, so it installs together with ys_demo)

The demo module ships a pages view at /pages and a generated content plugin that populates it. Its deploy hooks place a counter block, add the Pages menu link and register the view with Testmode.

The counter block, with its CSS, JavaScript and Twig template, also exercises the test tooling. It has the following tests:

  • Unit, Kernel and FunctionalJavascript PHPUnit tests
  • A Jest test
  • The counter.feature Behat feature

To confirm the demo module works on a provisioned site, check the following:

  • /pages lists 20 nodes whose titles start with Demo page, 10 per page.
  • A Counter Block shows in the content region of the default theme.
  • The main menu has a Pages link.

ahoy test-bdd -- --tags=@counter runs the demo module's Behat feature. ahoy test-js runs its Jest test together with those of the other custom modules.

Leaving the demo module out of the Custom modules question removes the following:

  • The ys_demo module directory
  • The drush pm:install ys_demo line in scripts/provision-00-enable-demo-modules.sh, the only block the template marks with CUSTOM_MODULE_DEMO
  • The Behat features tagged @demo, which are counter.feature and pages.feature

Without the search module too, the installer also removes the recipes/page content model and the provisioning step that applies it. Drupal helpers stays a Composer requirement, but nothing installs it. Generated Content and Testmode follow their own entries in the Modules question, so scripts/provision-10-enable-dev-modules.sh still installs them.

Other shipped modules​

2 more custom modules ship alongside the scaffold and demo modules:

  • ys_search configures the Search API index, the Solr server and the search view for the Solr service, and brings in the workflows and content_moderation core modules. On install, it uninstalls core's search module. Its deploy hook attaches an editorial workflow to the page content type. It ships only with the Solr service.
  • ys_migrate is a demo migration module that migrates the categories table of the second database into tags terms. It ships only with the migration feature (see Migrations).

Tests scaffold​

The ys_base module's tests directory holds a working example test and a base class for each PHPUnit test type: Unit, Kernel, Functional and FunctionalJavascript. A new test then starts from a copy of a passing test. The directory ships when PHPUnit is selected during installation.

To start a kernel test, copy tests/src/Kernel/ExampleTest.php and rename the file and the class. The copy extends YsBaseKernelTestBase, which the installer renames after your prefix.

For a test in another module, put the copy in that module's tests/src/Kernel directory, set its namespace to Drupal\Tests\<module>\Kernel and import the base class from Drupal\Tests\ys_base\Kernel. ahoy test-kernel runs the test, because the kernel suite in phpunit.xml collects every web/modules/custom/**/tests/src/Kernel directory.

The ys_base tests also include a Traits directory with 5 helper traits:

  • ArrayTrait
  • AssertTrait
  • BrowserHtmlDebugTrait
  • MockTrait
  • ReflectionTrait

Remove the ones you don't need.