Installation

Bootstrap Barrio SASS Theme Development Guide

This guide explains how to set up and develop a custom Bootstrap Barrio SASS sub-theme for Drupal.

Table of Contents

• Requirements
• Installation
• Development Setup
• Asset Compilation
• Production Deployment
• Troubleshooting

Requirements

Before you begin, ensure you have:

• Node.js v16 installed on your server
• Drupal 8/9/10 installed
• Composer for dependency management

Installation

1. Install Base Themes

First, install the required base themes using Composer:

composer require drupal/bootstrap_barrio 
composer require drupal/bootstrap_sass

2. Create Sub-theme

The sub-theme creation process involves these steps:

1. Navigate to the bootstrap_sass directory:

   cd web/themes/contrib/bootstrap_sass

2. Make the script executable:

   chmod +x scripts/create_subtheme.sh

3. Run the sub-theme creation script:

   ./scripts/create_subtheme.sh

4. Follow the on-screen prompts to name your sub-theme

Your directory structure should look like this:

Drupal root (web/)
├── themes
│   ├── contrib
│   │   ├── bootstrap_barrio
│   │   └── bootstrap_sass
│   └── custom
│       └── mycustom_bootstrap_sass  # Your sub-theme name

3. Clean Up

After creating your sub-theme, you can remove the starter kit:

composer remove drupal/bootstrap_sass

Development Setup

1. Node.js Setup

Ensure you're using Node.js v16:

nvm use 16

2. Install Dependencies

Navigate to your sub-theme directory and install dependencies:

cd web/themes/custom/mycustom_bootstrap_sass
npm install

Optional Dependencies

• Material Design Bootstrap:

  npm install mdbootstrap

• Gulp CLI (globally):

  npm install --global gulp-cli

3. Configure BrowserSync

Edit your gulpfile.js to enable live reloading:

browserSync.init({
  proxy: "http://yourdomain.com",
});

Asset Compilation

Run Gulp to compile and watch your assets:

gulp

This will:

• Compile SASS to CSS
• Minify JavaScript
• Watch for changes
• Auto-reload the browser

Production Deployment

CSS Files

Gulp generates two CSS files:

• style.css - Development version with source maps
• style.min.css - Production version (minified)

To switch between versions, update your SUBTHEME.libraries.yml file:

css:
  theme:
    css/style.min.css: {}  # For production
    # css/style.css: {}    # For developmentopment

Troubleshooting

Common Issues

1. Script Permission Errors
   • Solution: chmod +x scripts/create_subtheme.sh
   • Alternative: bash scripts/create_subtheme.sh
2. Sub-theme Not Created
   • Verify you're in the correct directory
   • Check file permissions
   • Ensure Node.js version is correct
3. Gulp Not Working
   • Verify Node.js version: node -v
   • Check for missing dependencies: npm install
   • Ensure gulp-cli is installed globally
4. Bootstrap Library Compatibility Warnings

   A known compatibility issue exists between Bootstrap and SASS libraries, resulting in deprecation warnings during Gulp compilation.

   Resolution: Install a specific SASS version to suppress these warnings:

   npm install sass@1.77.6 --save-dev

   For detailed information, refer to Drupal issue #3471634

Getting Help

• Check the Bootstrap Barrio issue queue
• Review the Bootstrap documentation
• Join the Drupal Slack channel #bootstrap-barrio