README

Lets a site editor pick one background asset, either an uploaded image or a video media entity, and exposes it to the theme layer. The choice is stored in custom_design.settings, and on every page the module adds two variables, custom_bg_type and custom_bg_url, to the page and html templates. The module renders nothing on its own: the theme decides what to do with the URL.

Requirements

Drupal 10.3+ or 11. No contrib dependencies. The module depends on three core modules, which are declared in the info file and installed automatically: File, Image and Media.

The settings form also assumes some site configuration that ships with the standard profile but is not guaranteed on a minimal site:

A video media type with a field_media_video_file field. The video autocomplete is restricted to that bundle and the submit handler reads that field.
A remote_video media type. The "upload a new video" link points at its add form.
The thumbnail image style, used for the preview of the current background image.

Media is not installed by the standard profile on Drupal 11, so on a fresh site you have to install it before this module, or let the dependency do it.

Installation

Install as usual at /admin/extend, or drush en custom_design.

If installation fails, check that the media types listed above exist. The module installs without them, but the settings form will not be usable.

Configuration

Settings form: /admin/appearance/custom-design, also linked from /admin/appearance.
Permission: edit custom banners. Grant it at /admin/people/permissions to the roles that should manage the background.
Pick "Image" and upload a png, jpg or jpeg, or pick "Video" and select an existing video media entity. Only one is active at a time.
Uploaded images are marked permanent and get a file usage record, so they are not garbage collected.

Usage in a theme

The variables are available in page.html.twig and html.html.twig:

{% if custom_bg_type == 'video' %}
  <video autoplay muted loop src="{{ custom_bg_url }}"></video>
{% elseif custom_bg_type == 'image' %}
  <div style="background-image: url({{ custom_bg_url }})"></div>
{% endif %}

Both variables are absent when nothing is configured, so guard on custom_bg_type before using the URL.

Development

The repository is a DDEV project. ddev start runs the bootstrap in .ddev/post-start.sh: it downloads Drupal core and dependencies with ddev poser, installs the site on first run, symlinks the module into web/modules/custom/custom_design, enables devel, media and custom_design, and prints a one-time login link. The account is admin with password 1.

web/ and vendor/ are generated and git ignored. Only the module files are tracked.

Checks:

ddev phpcs
ddev phpcbf
ddev phpstan --level=6 -c ../../../../phpstan.neon

Pass the config path explicitly. Plain ddev phpstan symlinks phpstan.neon into the module directory with a relative path that does not resolve, so it runs with no configuration at all: level 0, and without the "Unsafe usage of new static" exception that Drupal code needs. The relative path above is resolved from web/modules/custom/custom_design, which is where the wrapper changes to.

Add-ons in use: ddev-drupal-contrib, ddev-drupal-contrib-extras, ddev-drupal and ddev-pimp-my-shell.

Known issues

The "You can also upload a new video" link on the settings form opens the add form for the remote_video media type, but the autocomplete below it only accepts the video bundle. A video created through that link cannot be selected. One of the two needs to change, and which one depends on whether the site wants hosted files or oEmbed videos.
The preprocess hooks add the background variables without any cache metadata, so a rendered page does not carry the custom_design.settings cache tag. Changing the background may not show up on cached pages until the render cache is cleared.
The preprocess helper reads the settings with getEditable(), which skips configuration overrides. A $config['custom_design.settings'] override in settings.php has no effect on the front end.
The procedural hook functions in custom_design.module exist only for Drupal 10, which has no attribute based hooks. Once the supported floor is Drupal 11.1 they can be deleted, along with the service declaration in custom_design.services.yml that Drupal 10 needs to resolve the hook class.

faithcatholic / custom_design

Package info

Security

Statistics