Skip to content

Latest commit

 

History

History
124 lines (70 loc) · 5.57 KB

README.md

File metadata and controls

124 lines (70 loc) · 5.57 KB
Raw

OCHA Common Design sub-theme for Drupal 9+

A starterkit to use the OCHA Common Design base-theme in a way that allows for "upstream" changes such as security updates, new features, and so forth. The sub-theme is ready to help you implement the following types of customizations:

  • Customise your site colors
  • Add your own icons to the SVG sprite
  • Override/extend base-theme templates
  • Adding/overriding/extending frontend components

Refer to Drupal 9+ Theming documentation for more information.

Getting started

  1. Copy the common_design_subtheme directory from the base-theme into /themes/custom/ of the Drupal site.
  2. Rename the common_design_subtheme.info.yml.example to common_design_subtheme.info.yml
  3. In the Drupal Admin, go to Appearance, find OCHA Common Design sub theme and select Enable and set default.
  4. Customize the name/description fields of the sub-theme's info file if you wish.
  5. Rebuild the cache.
  6. Edit the sub-theme's css/brand.css to pick your site's palette. No other modifications are necessary. The header/footer plus all components will adopt your new colors.

Customise the logo

The theme uses two logos: by default the UN emblem, and on wider screens the OCHA lockup (emblem plus "OCHA"). To configure both follow these steps:

  1. Desktop: Add your file to img/logos and set the desktop logo in the common_design_subtheme.info.yml file
logo: 'img/logos/your-desktop-logo.svg'

Adjust --brand-logo-desktop-width to match your logo's dimensions

  1. Mobile: Check your mobile logo into version control and adjust css/brand.css to match the file's dimensions:
  • --brand-logo-mobile-width

You must also update the url() within libraries/cd/cd-header/cd-logo.css

Customise the favicon and homescreen icons

Replace the favicon in the theme's root, and the homescreen icons in img/ with branded versions

Customise colours

Change the CSS Vars in css/brand.css and save the file. Sass is no longer available in CD v8 and newer.

Customise icons

  • Copy SVG icons from the Humanitarian icon set into the sub-theme img/icons directory and follow the instructions in the common_design README to generate a sprite with those new icons.
  • Edit the sub-theme's templates/cd/cd-icons/cd-icons.html.twig to include the generated sprite file.

Creating Drupal libraries

Add new components by defining Drupal libraries in common_design_subtheme.libraries.yml and attaching them to relevant templates. Or use existing components from common_design.libraries.yml base-theme by overriding Twig templates in the sub-theme and attaching the libraries like so:

{# Use a CD base-theme component #}
{{ attach_library('common_design/cd-teaser') }}

{# Attach a custom sub-theme library #}
{{ attach_library('common_design_subtheme/my-article-teaser') }}

Overriding Drupal libraries

Occasionally you might want to totally replace a given library that is output by core or CD base-theme. In that case, use libraries-override to replace the library of your choice with the customized version. No additional work should be necessary to attach libraries inside Twig templates.

Extending Drupal libraries

Core and CD base-theme libraries can be extended with small customizations by using the libraries-extend directive in common_design_subtheme.info.yml. By extending a library, your customizations automatically apply when any core or base-theme library would normally be output. Use this feature to override colors inside components, for example.

Extending the theme

Override theme preprocess functions by copying from common_design.theme and editing as needed. hen copying, the function name will always need to be modified from common_design_ to common_design_subtheme_.

Refer to common_design README for general details about base-theme and instructions for compilation. There should be no need to use Sass in the sub-theme anymore.

Tests

To run E2E tests in the sub theme, adjust the Base URLs in the common_design_subtheme/_tests/_env/index.js file.

# Install dependencies for your host machine.
npm i

# Run all E2E tests in headless mode. The console will output the results.
npm run e2e

# See the tests run in a visible browser window with --debug
npm run e2e -- --debug

# If you want to run a limited number of tests, specify a string with the -t
# argument. It will parse all of the describe() blocks and only run tests when
# it matches the string you supply.

# All tests that include 'OCHAServices'.
npm run e2e -- -t 'OCHAServices'