This repository has been git subtree split into individual repositories to align more closely with Drupal best practices and will not receive further development. Development will continue in the individual modules' repositories which you are encouraged to use instead:

• drupal/ambientimpact_block

• drupal/ambientimpact_blog

• drupal/ambientimpact_core

• drupal/ambientimpact_icon

• drupal/ambientimpact_markdown

• drupal/ambientimpact_media

• drupal/ambientimpact_migrate

• drupal/ambientimpact_paragraphs

• drupal/ambientimpact_portfolio

• drupal/ambientimpact_ux

• drupal/ambientimpact_views

• drupal/ambientimpact_web

If you want to see the work leading up to the split, that can be found in the 8.x branch.

The rest of this readme is left as-is for historical purposes.

---

This respository contains Drupal modules that provide a framework for back-end and front-end development which includes many PHP, JavaScript, and Sass utilities, UX improvements and widgets, base styles, and libraries; for more information, see the component system explainer. These are used across multiple sites, including ambientimpact.com.

While not required for these modules to operate, the ambientimpact_base theme integrates heavily with these modules.

Warning: while these are generally production-ready, they're 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 9.5 or newer (Drupal 8 is end-of-life)

• PHP 8

• Composer

Front-end dependencies

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

---

Installation

Composer

This is a partly legacy codebase, and as such, Composer installation of the modules in this repository isn't supported directly. You'll have to check out the repository into your Drupal modules directory, optionally as a Git submodule. The long term plan is to refactor these as individual Composer packages, but for now, manual installation is required. That said, Composer is recommended to install the various dependencies of these modules, which you can do with the following.

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.

cweagans/composer-patches must also be added to your project and set up before attempting to install these modules as some of them provide patches for Drupal core and/or other modules they depend on. If you're unsure, check each module's composer.json to see if it defines any patches.

Then, in your root composer.json, add the following to the "repositories" section. Note that you can leave out the modules you don't plan to use.

"drupal/ambientimpact_core": {
  "type": "path",
  "url": "<web directory>/modules/ambientimpact/ambientimpact_core"
},
"drupal/ambientimpact_icon": {
  "type": "path",
  "url": "<web directory>/modules/ambientimpact/ambientimpact_icon"
},
"drupal/ambientimpact_markdown": {
  "type": "path",
  "url": "<web directory>/modules/ambientimpact/ambientimpact_markdown"
},
"drupal/ambientimpact_media": {
  "type": "path",
  "url": "<web directory>/modules/ambientimpact/ambientimpact_media"
},
"drupal/ambientimpact_ux": {
  "type": "path",
  "url": "<web directory>/modules/ambientimpact/ambientimpact_ux"
}

where <web directory> is your public Drupal directory name, web by default.

Then, in your project's root, run composer require "drupal/ambientimpact_core:7.x-dev@dev" to have Composer install the core module and its required dependencies for you. Repeat the process for any other modules you want to install dependencies for.

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>/modules/ambientimpact/*"
],

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:

"ambientimpact-drupal-modules": "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.

Optional: use nvm

If you want to be sure you're using the same Node.js version we're using, we support using Node Version Manager (nvm) (Windows port). Once nvm is installed, you can simply navigate to the project root and run nvm install to install the appropriate version contained in the .nvmrc file.

Note that if you're using the Windows port, it does not support .nvmrc files, so you'll have to provide the version contained in the .nvmrc as a parameter: nvm install <version> (without the < and >).

This step is not required, and may be dropped in the future as Node.js is fairly mature and stable at this point.

---

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 ambientimpact-drupal-modules run build

---

Major breaking changes

The following major version bumps indicate breaking changes:

• 3.x - Some modules now require Drupal 9 and 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 - Now requires Drupal core 9.4.x; this is currently due to the patches in ambientimpact_media only applying against this core version.

• 6.x - Front-end dependencies now installed via Yarn, removing all use of Asset Packagist; front-end build process ported to Webpack.

• 7.x - Now requires Drupal core 9.5.x; this is due to:

  • 9.5 added explicit string return value of \Drupal\Component\Utility\Html::escape(); \Drupal\ambientimpact_core\Utility\Html::escape() has been updated to match to prevent fatal errors.

  • The patches in ambientimpact_media have been updated to apply against this core version.