README

[TOC]

Helpful documentation

Guidelines

Follow the Drupal Guidelines: https://www.drupal.org/docs/develop/theming-drupal
Use Components (SDC) for all reusable tempalte snippets
With Bootstrap as a framework, we have to deal with two different conventions when it comes to CSS class naming. Drupal prefers BEM (https://getbem.com/naming), while Bootstrap uses some kind of OOCSS. We use this to our advantage, and use BEM for our custom page structure and components, so that we can better differentiate them. If it makes sense to use BEM classes next to Bootstrap classes, just do it. Example: 'page__navar navbar' are fine.

Extend Bootstrap

Components

Grid

gy-equal-x: Adds vertical gutter equal to the horizontal gutter

Buttons

btn-width-full: Stretches a button to 100% width (like the old btn-block class)

Icons

DROWL Base brings a set of basic icons which are available as SASS and PHP variables. In sass the icons are named $ico-theme-X (see drowl-sass-base variables). In PHP the icons are available by the global drowl_theme_icons array.

To override SASS variables, see $basics-frontend-iconfont-family and the single $ico-theme-X variables.

To override single PHP variables: $variables['drowl_theme_icons']['info'] = 'ico-info-circle'; or override all:

$variables['drowl_theme_icons'] = [
  'info' => 'ico-info',
  'warning' => 'ico-warning',
  ...
];

Utilities

Whenever possible, use the BS Utilities API to extend the BS Utilities: https://getbootstrap.com/docs/5.3/utilities/api/#api-explained However utility classes are added, the naming should follow the existing BS logic. So for all class and variable names, start with meaningful prefixes, like: bg-x, bg-gradient-x, ...

Gradients

Bootstrap has its own logic for simple gradients: https://getbootstrap.com/docs/5.3/utilities/background/#background-gradient This is fine for very simple gradients, but doesn't work well for complex ones.

So when adding more complex gradients, use:

$gradient-x-y: linear-gradient(
  var(--degree, 90deg),
  #{$color-x} 0%,
  #{$color-y} 100%
);
.bg-gradient-x-y{
  background-image: $gradient-x;
}

To control the gradient degree add further utitlity classes like:

.gradient-degree-60 {
  --degree: 60deg;
}
.gradient-degree-60-inverse{
  --degree: -60deg;
}

Helpers

Body classes

current-breakpoint-is-x: Current active breakpoint determined by JS.
current-breakpoint-is-smaller-x: If the current breakpoint is smaller brekpoint x.
current-breakpoint-is-larger-x: If the current breakpoint is larger brekpoint x.
current-vw-is-smaller-container-max: Set if the current viewport width is smaller as the BS .container (max. page width)

Drupal Specific

Fields (with Fences)

field__label--colon: Set on the field label wrapper to add colons after the label

Utilities

Text / Typography

text-muted: Deprecated since BS 5.3 and replaced by a meaningless class. So we reinvented it.
text-columns--x (2-4): Split text into columns. The column count decrease automatically using media queries.

List Styles

Base class: styled-list. With the required formatter classes:

styled-list--comma: Inline list devided by comma
styled-list--square: Vertical list with square "dots"
styled-list--checklist: Vertical list with checkmarks
styled-list--arrow: Vertical list with arrows
styled-list--data-grid: Creates a label | data grid, with equal wide labels

Javascript

Debounce / Throttle

Drupal.drowl_base.functions.debounce(function,delay);

// Example usage:
new ResizeObserver(Drupal.drowl_base.functions.debounce(function(){
  // Do stuff!
}, 600));

Get current Breakpoint

// Returns: Breakpoint Name (string), example: "lg"
Drupal.drowl_base.functions.getCurrentBreakpoint();

Get Scrollbar width

// Returns: Pixel value (decimal), example: 15
Drupal.drowl_base.functions.getScrollbarWidth();

Events

Listen to viewport size changes

document.addEventListener(
  "drowl_base:resize",
  (e) => {
    /* … */
  },
  false,
);

SDC Single Directory Components

Component Usage

Basically you have two ways to add a component:

Include

Include a component, and drop some parameters, but dont change its contents.

{% include 'drowl_base:block' with {
  html_tag: 'section',
  block_utility_classes: [
    'my-3',
    'block--local-tasks',
  ],
}%}

Embed

Include a component and change its contents using block overrides.

{% embed 'drowl_base:metaheader' with {
  color: 'light',
  navbar_utility_classes: ['bg-light'],
} %}
  {% block left %}
    Replacement
  {% endblock %}

  {% block right %}
    Replacement
  {% endblock %}
{% endembed %}

Create new Components

Prefer to use drush genrate: drush generate theme:sdc:component

or see: https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components/creating-a-single-directory-component

Override existing Components

Only themes can override components (modules cannot override). For a theme to override a component, use the replaces key within the mytheme.component.yml file.

Check SDC Docs for details

Override DROWL Base Stylesheets

All stylesheets are written with CSS variables (where possible). So in most cases, you might only need to modify your SASS variables (so your drowl_child.variables.css file is updated).

If you need to modify or remove DROWL Base styles, you could simply remove or override the according Drupal library.

Libraries

Slick

DROWL Base has its own Slick Carousel theme, with various tweaks using CSS Variables.

Configuration variables

  --grid-gutter: var(--bs-grid-gutter);
  --direction-nav-top: calc(50% - (var(--dot-nav-reserved-outer-space) * 0.5));
  --direction-nav-item-width: var(--icon-size-lg);
  --direction-nav-item-height: var(--icon-size-lg);
  --direction-nav-icon-size: var(--icon-size-md);
  --direction-nav-item-bg: var(--bs-light-glass);
  --direction-nav-item-color: var(--bs-dark-glass);
  --direction-nav-item-bg-hover: var(--bs-light);
  --direction-nav-item-color-hover: var(--bs-dark);
  --dot-nav-item-width: var(--icon-size-xs);
  --dot-nav-item-height: var(--icon-size-xs);
  --dot-nav-item-radius: 50%;
  --dot-nav-grid-gutter: .35rem;
  --dot-nav-item-color: var(--bs-light-glass);
  --dot-nav-item-color-hover: var(--bs-primary);
  --dot-nav-item-color-active: var(--bs-white);
  // Dot nav alignment, available options: start, center, end.
  --dot-nav-alignment: center;

Check libraries/slick.scss for more details.

Controls outside

To show direction + dot nav outside the contents, use the class slick-controls-outside on any wrapper, or .slick, slick--controlsoutside right on the .slick wrapper (prefered).

If slick__nav becomes > viewport width, it switches to the style defined by the CSS variable --direction-nav-outside-fallback-behavoir (could be: 'overlay','inset' or 'hide').

Controls inset

To show direction + dot nav outside the contents, while not moving the direction nav outside the container, use the class slick-controls-inset on any wrapper, or .slick, slick--controlsinset right on the .slick wrapper (prefered).

See libraries/slick.scss for details.

Allow Overflow

For slideshows which needs visible overflow (eg: because you have elements with box-shadow inside), you can set slick-allow-overflow on any wrapper. Its very important to set slick-allow-overflow-parent on the section wrapper, to prevent the horizonal overflow. Otherwise the document will become horizontally scrollable.

webksde / drowl_base

Maintainers

Details

README

Helpful documentation

Guidelines

Extend Bootstrap

Components

Grid

Buttons

Icons

Utilities

Gradients

Helpers

Body classes

Drupal Specific

Fields (with Fences)

Utilities

Text / Typography

List Styles

Javascript

Debounce / Throttle

Get current Breakpoint

Get Scrollbar width

Events

Listen to viewport size changes

SDC Single Directory Components

Component Usage

Include

Embed

Create new Components

Override existing Components

Override DROWL Base Stylesheets

Libraries

Slick

Configuration variables

Controls outside

Controls inset

Allow Overflow