Barrio

by Gisle Hannemyr

This chapter describes how to work with the Drupal Barrio theme module for Bootstrap 5.

Table of contents

Drupal projects discussed in this chapter: Barrio, Barrio SASS SK.

Introduction

Note: These notes were created as part of me evaluating Barrio in 2021. They are not complete and may contain errors. Use with caution.

Barrio is the most used Bootstrap 5 theme for Drupal.

It provides an extensive GUI for configuring in the theme settings including the Bootstrap components, layout, colours and fonts. This GUI-based approach may not suit developers who want to have total the look and feel of a site through the CLI, working directly with SCSS files and twig templates.

It comes with a custom subtheme starter kit that uses a CDN to load Bootstrap. This means that the variables used for the Bootstrap colour utility classes cannot be changed. To change these, you need to load Bootstrap locally, and recompile Bootstrap css from scss. For this, there exists a companion project (Barrio SASS Starter Kit) to have the scss locally and scripting rebuilds with gulp.

Theming in Boostrap 5 is accomplished by Sass variables, Sass maps, and custom CSS. Source: Get started with Bootstrap.

Barrio Bootstrap 4/5

Installing

To download, run the following via command line inside your siteroot:

$ composer require 'drupal/bootstrap_barrio:^5.5'

This downloads the Barrio theme project and places it in the themes/contrib folder It contains two themes: The main theme, named Bootstrap Barrio and the basic structure of a subtheme, named Bootstrap Barrio Subtheme. You will see both if you navigate to Appearance » List.

Create a subtheme

The main theme is not intended to be used on its own. For instance it does not contains any css so it will appear unthemed. To be able to use it, always create a custom subtheme.

Two alternative ways of creating a subtheme is provided:

Both are described in the following sections.

CDN subtheme

The theme comes with a script to create a custom subtheme.

noteIf you are not running Apple macOS, the supplied script to create a subtheme will produce the error message: “sed: can't read : No such file or directory”. To fix this, edit the script and change the text:
“sed -i '' -e ” → “sed -i -e”. Source: SO.
Also make sure that the subtheme does not already exist.

Run the script:

$ pwd
…/web/themes/contrib/bootstrap_barrio
$ chmod a+x scripts/create_subtheme.sh
$ ./scripts/create_subtheme.sh

+------------------------------------------------------------------------+
| With this script you could quickly create barrio sub-theme             |
| In order to use this:                                                  |
| - bootstrap_barrio theme (this folder) should be in the contrib folder |
+------------------------------------------------------------------------+

The machine name of your custom theme? [e.g. mycustom_barrio]
my_barrio
Your theme name ? [e.g. My custom barrio]
My Barrio
# Check the themes/custom folder for your new sub-theme.
gisle@karde:/var/www/guided.roztr.org/web/themes/contrib/bootstrap_barrio$ 
$ cd ../../custom/my_barrio/

Some finishing touches for the CDN subtheme:

The URLs for the CDNs are defined in my_barrio.libraries.yml as follows:

bootstrap_cdn:
  js:
    /libraries/popper.js/dist/umd/popper.min.js: { weight: -19 }
    /libraries/bootstrap/dist/js/bootstrap.min.js: { weight: -20 }
  css:
    component:
      //cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css: {}

The use of bootstrap_cdn is specified in my_barrio.info.yml as follows:

libraries:
  - my_barrio/bootstrap_cdn
  - my_barrio/global-styling

This screendump shows how the newly created custom subtheme initally looks like:

barriotest.png
Newly created Barrio subtheme.

The theme does not look ready to use. Contrast is too low, and the branding in the navbar and the footer has an awkward placement of the elements.

To test the responsiveness of the subtheme and how it looks on a small screen, in Firefox press Ctrl+Shift+M. After some contrent has been created, this should produce something like the screenshot below:

barrio_responsive.png
The responsive version of the subtheme.

The subtheme's regions are in my_barrio.info.yml. They are just copied from barrio.info.yml:

regions:
  top_header: 'Top header'
  top_header_form: 'Top header form'
  header: 'Header'
  header_form: 'Header form'
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  page_top: 'Page top'
  page_bottom: 'Page bottom'
  highlighted: Highlighted
  featured_top: 'Featured top'
  breadcrumb: 'Breadcrumb'
  content: 'Content'
  sidebar_first: 'Sidebar first'
  sidebar_second: 'Sidebar second'
  featured_bottom_first: 'Featured bottom first'
  featured_bottom_second: 'Featured bottom second'
  featured_bottom_third: 'Featured bottom third'
  footer_first: 'Footer first'
  footer_second: 'Footer second'
  footer_third: 'Footer third'
  footer_fourth: 'Footer fourth'
  footer_fifth: 'Footer fifth'

You may view their placement by navigating to Manage » Structure » Block layout and click “Demonstrate block regions (My Barrio)”.

barrio_regions.png
Demonstrate block regions (My Barrio)

Note that two of the regions that are defined (“Page top” and “Page bottom”) are missing from the page template.

A prototype for the page template is in the subtheme's templates directory, named “_page.html.twig”. To experiment with it, copy to “page.html.twig” and rebuild the cache.

A lot of settings can be set in the theme's GUI by navigating to Appearance » List » My Barrio » Settings. The vertical tab has the following elements:

Additional settings are:

See alsoThe video WebWash: Getting Started with Bootstrap 4 using Barrio in Drupal 8 (2018-10-16 21:37) on YouTube still provides a good introduction, but some parts are already outdated.

SASS subtheme

There are several methods available to work with Bootstrap locally. The one described below makes use of the Barrio SASS Starter Kit to create subtheme with SASS sources.

First download the project using composer:

$ composer require 'drupal/bootstrap_sass:^5.0'

This places it in the themes/contrib folder.

Then Bootstrap SASS starter kit contains a bash script that createa a subtheme in the themes/custom folder:

$ cd web/themes/contrib/bootststrap_sass
$ bash ./scripts/create_subtheme.sh

+------------------------------------------------------------------------+
| With this script you could quickly create bootstrap_sass sub-theme     |
| In order to use this:                                                  |
| - bootstrap_sass theme (this folder) should be in the contrib folder   |
+------------------------------------------------------------------------+

The machine name of your custom theme? [e.g. mycustom_bootstrap_sass]
my_bootstrap
Your theme name ? [e.g. My custom bootstrap_sass]
My Bootstrap
# Check the themes/custom folder for your new sub-theme.

Some finishing touches for the SASS subtheme:

You should now be able to install and set as default the subtheme named My Bootstrap.

See alsoThere are descriptions about how to to this manually in articles from OpenSenseLabs.com: How to create Barrio sub-theme in Drupal 8 using SaSS Barrio Starterkit and Axelerant.com: Setting up A Custom Bootstrap Theme With Drupal 8. The latter also provides an example about customizing colours.

Navigate to Appearance » List, locate “My bootstrap” and click “Install and set as default”.

When you return to the front page, site will appear unthemed. This is because the theme is not built yet.

To build the theme, go to the root directory of the subtheme and do the following:

$ pwd
…/themes/custom/my_bootstrap
$ npm install
…
found 0 vulnerabilities

This will install the dependencies in the local folder.

To re-create .css after changing the .scss, use gulp. This will process the tasks specfied gulpfile.js.

If you are able to use BrowserSync, edit the sample gulpfile.js supplied to make the proxy point to your domain.

If you are in a headless environment you shall not be able to use BrowserSync, and you wil get the following error:

[Browsersync] Couldn't open browser (if you are using BrowserSync in a headless
environment, you might want to set the open option to false)

You do this by editing the sample gulpfile.js. Add the line “open: false,” as follows:

// Static Server + watching scss/html files
function serve () {
  browserSync.init({
    proxy: 'http://yourdomain.com',
    open: false,
  })

  gulp.watch([paths.scss.watch, paths.scss.bootstrap], styles).on('change', browserSync.reload)
}

Source: [#3162844]@Drupal.org.

Gulp is supposed to be run in the backround. It will monitor any changes you make to the SASS source files and regenerate the CSS. To see the changes, rebuild the cache after you see the “Finished 'styles'” message.

$ gulp &
[14:36:52] Using gulpfile …/themes/custom/my_bootstrap/gulpfile.js
[14:36:52] Starting 'default'...
[14:36:52] Starting 'styles'...
[14:36:57] Finished 'styles' after 4.75 s
[14:36:57] Starting 'js'...
[14:36:57] Finished 'js' after 10 ms
[14:36:57] Finished 'default' after 4.77 s
…
[14:43:28] Finished 'styles' after 9.1 s
[Browsersync] 2 files changed (bootstrap.min.css, style.min.css)
[14:43:28] Finished 'styles' after 9.19 s
$ drush cr

The theme appears unthemed if the setting for library is “None”. To fix this. navigate to Appearance » Appearance settings and in the pulldown menu for “Load library”, replace “None” with “Local”).

If you now visit the front page, it looks like this:

barrio_sass_test.png
Newly created Barrio SASS subtheme.

IMHO, the theme does not look ready to use. Contrast is too low, and the branding in the navbar and the footer has an awkward placement of the elements.

The regions are roughly the same as those in the base theme. There are some differences as the regions in the blue navbar, colours and to constraints, but I haven't drilled down yet.

barrio_regions.png
Demonstrate block regions (My Bootstrap)

Directories in the custom subtheme.

Files in the scss directory, which is the main place to customize the subtheme. Changes from 5.0.0 to 5.0.2 indicated.

By default the import of material design bootstrap is commented out in import.scss:

//material design bootstrap
//@import "../node_modules/mdbootstrap/scss/mdb-free.scss";

Importing it change the subtheme for the force. It changes the primary colour and chops off left edge of content. I just left it commented out for now.

To customize the style, you should edit variables.scss and add custom styling to style.scss.

Defining primary and accent colours as Bootstrap variables will generate the whole colour schema using Google Material Design colour management concept.

For example, changing the variable $accent-shade from #0079C0 to #7e57c2 will change the background colour of the navbar.

The array $theme-colors defines the colours use for the Bootstrap 4 colour utility classes.

Background:

Working with the SASS subtheme

I am not using the CDN subtheme. The rest of this chapter is assuming you are working with the SASS subtheme.

Most of the configuration of the Barrio SASS subtheme is done by the GUI. This section starts out by giving an overview of the GUI for the SASS subtheme, the rest goes through various objectives (e.g. replacing the logo), and how to resolve them.

GUI settings overview

A lot of settings can be set in the theme's GUI by navigating to Appearance » List » My Bootstrap » Settings. The vertical tab has the following elements:

Additional settings are:

Uploading an .svg logo through the subtheme's GUI doesn't work (invalid file type). But placing it in or below public:// works. The screenshot below shows a logo with the path public://unmanaged/guided.svg being used instead of the default.

logopath.png
Path to custom logo.

Copy core/themes/stable/templates/misc/feed-icon.html.twig into the templates directory. Edit the file to remove all markup, then rebuild the cache.

Show ISO date in byline

Change the default medium date.

Adjust page layout

Out of the box, the width of the non-fluid main container with no sidebars are 1140 pixels, with 1110 remaining after gutters are removed..

To remove the sidebars, navigate to Appearance » List » Settings » Layout » Sidebar position to set sidebar position. The options are “Left”, “Both sides” and “Right”. There is no option for “None”, but navigating to Structure » Block layout let you remove the “Search” and “Tools” block from the sidebars and (for example) place them in the “Header” region. The result will be a full width page with no sidebars.

Templates

The SASS subtheme comes with the following two templates:

All other templates are inherited. To work with page layout, copy these from the parent theme:

Other templates may be copied from core:

Changing the navbar

#bar_sassregions ???

There are two ribbons in the navbar. They contain the following regions:

To change the settings for both, navigate to Appearance » List, and click “Settings” for the subtheme. Expand Components » Navbar structure

Here is a list of the settings that exists. The initial settings are in square brackets, my preferred settings, if different, in curly brackets.:

For both navbars, the background colour can be set to:

For both navbars, the link colour can be set to:

For the link settings, “Dark” provides light colour ($gray-100) suitable for a dark theme). “Light” vice versa ($gray-800).

Responsive images

To make all images responsive. navigate to Appearance » Appearance settings » Components » Images and check “Apply img-fluid style to all content images”.

noteNote that the Bootstrap 3 class “img-responsive” is gone. See SO: No img-responsive in Bootstrap 4.

Manage flex

GBS: Flex.

Colours

Some colours are defines by a combination of style.scss and variables.scss as follows.

Backgrounds:

body { background: $white; }                   // white      - body
.bg-inverse { background: $primary-shade; }    // red-orange - unknown use
.site-footer {background: $accent-shade; }     // dark blue  - footer

Anchors:

a { color: $accent-shade; }                    // dark blue
.menu--main li a { color: $primary-shade; }    // red-orange
.menu--account li a { color: $primary-shade; } // red-orange
.bg-secondary

Here are the colours defined:

--blue: #007bff;
--indigo: #6610f2;
--purple: #6f42c1;
--pink: #e83e8c;
--red: #dc3545;
--orange: #fd7e14;
--yellow: #ffc107;
--green: #28a745;
--teal: #20c997;
--cyan: #17a2b8;
--white: #fff;
--gray: #6c757d;
--primary: #0079C0;
--secondary: #ff4e2e;
--success: #28a745;
--info: #17a2b8;
--warning: #ffc107;
--danger: #dc3545;
--light: #f8f9fa;
--gray-dark: #343a40;
--dark: #343a40;

Theme development

The numbers refer to the video tutorials linked below.

To activate Twig debug, do:

$ cd sites/default
$ cp default.services.yml services.yml

Edit services.yml and in the “twig.config” section, change “debug: false” to “debug: true”. Clear the cache. When you now inspect pafe source, you'll find injected comments that will help you in theme debugging.

The main source for this section is the Youtube channel Drupal up. It provide a series of videos about Drupal 8 theme development. Most of it are still relevant for Drupal 10. Those I've viewed are linked below.

  1. Generating a Barrio sub-theme super quickly (4:45) 1 Dec 2019 – outdated
  2. Setup for Drupal Barrio theming developing (5:58) 11 Dec 2019
  3. Creating a Bootstrap Cards list with the help of Bootstrap Views module (7:18) 18 Dec 2019
  4. X () 2019
  5. X () 2019
  6. X () 2019
  7. X () 2019
  8. X () 2019
  9. X () 2019
  10. X () 2019

Drupal up: Setting up responsive images in Drupal 8 (Youtube 11:47)

Final word

[TBA]

Last update: 2021-01-28 [gh].