From 160ba2b77128cb5120e64feca21e6cbc1daf4fd0 Mon Sep 17 00:00:00 2001 From: Thomas Fini Hansen Date: Wed, 11 Sep 2024 21:46:44 +0200 Subject: [PATCH] Add documentation about configuration handling for webmaster modules --- docs/webmaster-modules.md | 107 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/webmaster-modules.md diff --git a/docs/webmaster-modules.md b/docs/webmaster-modules.md new file mode 100644 index 000000000..8672361ae --- /dev/null +++ b/docs/webmaster-modules.md @@ -0,0 +1,107 @@ +# Webmaster modules + +Administrators on webmaster libraries has the ability to upload and +enable extra modules. These can be both standard Drupal contrib +modules, or modules developed by/for the library. + +Developing bespoke modules doesn't not differ from developing modules +in general, as installing and configuring modules works as expected. + +However, it not uncommon for the developer to wish to provide some +configuration "outside" the modules own configuration, adding taxonomy +vocabularies, adding fields to nodes or even changing basic +configuration variables, which is somewhat challenging as DPL controls +the configuration. + +So to avoid every module doing it differently, this guide exists. And +if enough modules finds the need, the technique described here could +be implemented in a `dpl_webmaster` module that provide it as a +service. + +## Webmaster module configuration handling + +First off, a warning: when using this technique you take the +responsibility of the configuration added/overridden in this way. If +you for instance override the node form display configuration for a +node type, it's your responsibility to keep it up to date with changes +in DPL core. + +Adding new configuration for modules not in DPL is more safe, but you +should look out for dependencies. If a configuration depends on a +particular node type or field being available for instance. + +## Overview + +Configuration handling in webmaster modules consists of three parts: + +1. The configuration itself, in Drupals configuration export YAML + format, in a `config/sync` directory in the module. +2. An event subscriber that overlays the modules configuration when + Drupal imports the configuration. +3. A `hook_install` and possibly `hook_update_N` functions that + trigger configuration import when the module is installed and + updated. + +We'll describe the parts in detail in the following walk-through. + +## Walk-through + +### Initial configuration + +1. Start with a fresh DPL site with the code base from git, that has + up to date configuration (`task dev:cli -- drush cim` should do + nothing). +2. Make the required configuration changes in the Drupal + administration interface. +3. Run `task dev:cli -- drush cex -y` to export the configuration. +4. Now `git status` (or your preferred Git tool) tells you which files + has been changed, these are the files you need. +5. Copy the changed configuration files to `config/sync` in your + module and revert the changes to the files in the root + `config/sync` folder. + +### Event subscriber + +In order to get DPL to actually use the configuration you just saved, +we'll need to make it visible to Drupal. This can be done by +implementing an event subscriber that overlays the configuration on +`ConfigEvents::STORAGE_TRANSFORM_IMPORT`. An implementation can be +found in +[kdb_brugbyen](https://github.com/kdb/kdb_brugbyen/blob/main/src/EventSubscriber/OverlayConfigEventSubscriber.php). +You can simply copy that and fix the two references to the module (the +namespace and the configuration path). + +### Install/update hook + +The above will add in the module configuration when the configuration +is imported, but installing or updating a module does not trigger a +configuration import, so you'll need to do it yourself. + +Outside of DPL, triggering a configuration import from install/update +hooks is not recommended, but inside DPL we're in a controlled +environment where library sites should always be in sync with the +provided configuration. So triggering an import to overlay module +configuration can be considered safe. + +Importing configuration is both simple and horribly convoluted. The +`ConfigImporter` class does all the heavy lifting, but it's not a +service and requires digging out thirteen different services in order +to be instantiated. Again, you can just copy the code from +[kdb_brugbyen](https://github.com/kdb/kdb_brugbyen/blob/main/kdb_brugbyen.install). + +## Maintenance + +Keeping the module configuration up to date might pose some +challenges. + +Just changing the configuration is often simple, just do the +modifications, export and copy the changed files. + +Merging in changes from DPL could be problematic, as applying the +configuration changes from the module that's based on the previous +version of DPL might throw a `ConfigImporterException` and leave you +without any of the module changes. In this case you can either rebuild +the configuration in the administration interface and export it fresh, +or by careful inspection of diffs apply the needed changes by hand to +the YAML files. Deployment of such a change is left as an exercise for +the reader...