This respository contains a reusable Drupal base theme.

Warning: while this is generally production-ready, it's not guaranteed to maintain a stable API and may occasionally contain bugs, being a work-in-progress. Stable releases may be provided at a later date.

---

Requirements

• Drupal 10

• PHP 8

• Composer

• Yarn 3 or 4

Drupal dependencies

Before attempting to install this, you must add the Composer repositories as described in the installation instructions for these dependencies:

• The ambientimpact_core and ambientimpact_ux modules.

Front-end dependencies

To build front-end assets for this project, Node.js and Yarn are required.

---

Installation

Composer

Set up

Ensure that you have your Drupal installation set up with the correct Composer installer types such as those provided by the drupal/recommended-project template. If you're starting from scratch, simply requiring that template and following the Drupal.org Composer documentation should get you up and running.

Repository

In your root composer.json, add the following to the "repositories" section:

"drupal/ambientimpact_base": {
  "type": "vcs",
  "url": "https://github.com/Ambient-Impact/drupal-ambientimpact-base.git"
}

Installing

Once you've completed all of the above, run composer require "drupal/ambientimpact_base:^7.0@dev" in the root of your project to have Composer install this and its required dependencies for you.

Front-end assets

To build front-end assets for this project, you'll need to install Node.js and Yarn.

This package makes use of Yarn Workspaces and references other local workspace dependencies. In the package.json in the root of your Drupal project, you'll need to add the following:

"workspaces": [
  "<web directory>/themes/custom/*"
],

where <web directory> is your public Drupal directory name, web by default. Once those are defined, add the following to the "dependencies" section of your top-level package.json:

"drupal-ambientimpact-base": "workspace:^7"

Then run yarn install and let Yarn do the rest.

Optional: install yarn.BUILD

While not required, we recommend installing yarn.BUILD to make building all of the front-end assets even easier.

---

Building front-end assets

We use Webpack and Symfony Webpack Encore to automate most of the build process. These will have been installed for you if you followed the Yarn installation instructions above.

If you have yarn.BUILD installed, you can run:

yarn build

from the root of your Drupal site. If you want to build just this package, run:

yarn workspace drupal-ambientimpact-site run build

---

Major breaking changes

The following major version bumps indicate breaking changes:

• 3.x - Now require the 3.x branch of modules, which now require Drupal 9. All development is now against that major version of Drupal.

• 4.x - Refactored to use Sass modules; all development is now against this and will no longer compile using the old @import directive.

• 5.x - Front-end package manager is now Yarn; front-end build process ported to Webpack.

• 6.x - Requires Drupal 9.5 or Drupal 10.

• 7.x:

  • Requires Drupal 10.

  • Increase required version of ambientimpact_ux from 1.x to 2.x; see tooltips rewrite below.

  • Removed .nvmrc file as Node.js is stable enough nowadays to no longer warrant this.

  • Significant rework of stylesheets:

    • They now use many more CSS custom properties to configure various values rather than Sass variables where possible.

    • A lot of partials have been converted into standalone stylesheets and libraries which are attached to the appropriate elements, render arrays, etc. This allows for more fine-grained and efficient serving of styles that are actually used and less that are not used on a page or a site.

  • Tooltips have been completely rebuilt:

    • All styles have been moved from ambientimpact_ux to this theme.

    • The new default material theme now automatically uses a dark background in light mode and a light background in dark mode.

    • This theme now automatically constructs tooltips for all elements that have a title attribute, progressive enhancement-style.

    • As a consequence of the previous point, this theme has removed all uses of the abbr component from ambientimpact_ux and the social_links.tooltips component from ambientimpact_block; their functionality is now provided by the above.