Customizing Bootstrap 4 (SCSS) in b4st - SimonPadbury/b4st GitHub Wiki

This tutorial is for people who are not familiar with using command line apps (NDM, Node.js, Gulp, Bower, Webpack, etc.). Here I will explain how to get started with Bootstrap SCSS using preprocessor software with a Graphical User Interfce (GUI).

Introduction

b4st is a Bootstrap 4 starter theme for for WordPress. It calls Boostrap 4 from cdnjs.com.

If you want to customize the Bootstrap CSS from its SCSS files, then you will need to get the Boostrap Source Files and place them in a local folder within b4st. Then you will need to modify the b4st enqueues to point to the downloaded Bootstrap instead of Bootstrap on the CDN. And you will need a CSS preprocessor.

Some options for preprocessing SCSS into CSS:

  1. Free command line software with modules for preprocessing many coding languages, including CSS: e.g. Grunt, Gulp or Webpack. You can even use the static website generator Jeckyll, for it's built-in SCSS preprocessing capability. (But as you've on this webpage to learn about how to integrate Bootstrap SCSS into b4st, a WordPress theme, you won't be wanting to use Jeckyll at the same time).
  2. Paid-for software with a GUI that can preprocess many coding languages, including CSS: e.g. Codekit or Prepros.
  3. Free software preprocessors with a GUI: Koala and Scout-App.

It is beyond the scope of this tutorial to advise and instruct on the use of a command-line preprocessor. Most people who want to preprocess Bootstrap CSS are already familiar with that.

Summary of what you will learn, in this tutorial:

A. How to obtain the Bootstrap Source Files – and put Bootstrap and its SCSS files "locally" inside your b4st project.

B. How to set up the preprocessor. To date (Dec 2017) this tutorial has been designed for (and tested on) CodeKit, Koala and Scout App.

C. How to compile, customize, and build upon Bootstrap.

If you have not done so already, you need to learn how to compose styles using SCSS[1], e.g. from its creators, at sass-lang.com. There are also some excellent tutorials online, including some YouTube tutorials.

Note [1]: Sass and SCSS are similar. Both collectively (and confusingly) known as "Sass" and are both being developed by the same people. Sass 'proper' (file extension .sass) was invented first, but SCSS (file extension .scss) has become more popular. Sass proper differs from SCSS in that it doesn't have all those {curly brackets} and semi-colons; instead it relies upon tab-indented syntax (which the preprocessor understands). But SCSS looks more like the traditional SCSS. Other than this difference, both are the same in having variables, nesting, mixins and extending.

Bootstrap 4 was built from SCSS files, and these are available for you to use in the Boostrap Source Files download.

If you know CSS, then you are already half-way in learning SCSS :-)

A. Getting started: you need a local copy of Bootstrap (including Bootstrap SCSS) inside b4st

  1. First, download the Boostrap Source Files from the bootstrap website.

  2. In the dowloaded source files you will find, besides the other stuff, the dist/ folder and the scss/ folder.

    1. Copy the dist/ folder into the b4st/ root folder and rename it as bootsrap/.
    2. Then copy the scss/ folder into your bootstrap/[2] folder, so that you have:
    b4st/
│
├── bootstrap/
│   ├── css/
│   ├── js/
│   └── scss/
|
├── functions/
|
├── loops/
|
├── theme/
│   ├── css/
│   ├── js/
│   └── scss/[3]
│
...and all the other root theme files

    Note [2]: In the next step, you are going register and enqueue your new local Bootstrap CSS and JS that are in your bootstrap/ folder – instead of linking (as b4st does) to CDNJS for obtaining them. For conistency, you can download a local copy of modernizr.com.js, popper.js (the Bootstrap JS depends upon Popper tooltips, popovers and collapsed navbar "hamburger" open/close), and maybe Font Awesome too. But this tutorial only provides instructions for having a local Bootstrap.

  3. Create another scss/ folder inside your theme/ folder[3].

    Note [3]: When you get down to customizing Bootstrap, you will be generating it from a SCSS file that you will create inside theme/scss/. (And it will be an embedded part of your theme CSS – so, we will eventually be 'commenting out' the register and enqueue for bootstrap.min.css, as you will see below.)

  4. Now modify the b4st enqueues file functions/enqueues.php so that it points to your local Bootstrap CSS[4] and JS.

    Note [4]: The register and enqueue for this bootstrap.min.css will eventually be commented out, as you will not be needing it. I have included it here, just to give you satisfaction with testing (see below).

    /* Styles */

wp_register_style('bootstrap-css', get_template_directory_uri() . '/bootstrap/css/bootstrap.min.css', false, '4.0.0-beta.2', null);
wp_enqueue_style('bootstrap-css');

[...and b4st.css]

/* Scripts */

[Font Awesome 5, Modernizer, jQuery, Popper...]

wp_register_script('bootstrap-js', get_template_directory_uri() . '/bootstrap/js/bootstrap.min.js', false, '4.0.0-beta.2', true);
wp_enqueue_script('bootstrap-js');

[...and b4st.js...]

  5. Test that everything is working OK. Navigate to your website (or refresh your browser)[5] and use the inspector to check the location URLs of bootstrap.min.css and bootstrap.min.js. These should now show that Bootstrap is being sourced locally, from within your b4st/ folder, instead of from the CDN.

    Note [5]: You may need to Empty Caches in your browser, before you see the changes. (In some browsers you can Disable Caches so that you don't have to keep emptying them during development.)

B. Set up and Configure your CSS preprocessor

To date (Dec 2017) this tutorial has been designed for, and tested on, CodeKit, Koala and Scout App.

It will be helpful to you to learn how to use these apps before continuing this tutorial. However, some brief instructions on what you need to do for each app are included below.

  1. Copy b4st.css from theme/css/ to theme/scss/ and rename it as b4st.scss[5].

    Note [5]: This new file that you have just created is genuine SCSS (because all CSS is also genuine SCSS).

  2. Now delete (or rename, so as to keep) the original b4st.css – because your preprocessor is going to compile a new b4st.css from b4st.scss.

  3. In the new file b4st.scss, near the top (i.e. before all the other b4st styles), add an @import for the Bootstrap SCSS file, with the correct path so that your preprocessor can find it:

    /*
 * b4st (SCSS project)[6]
 * ===================
 * Imports and customizes Bootstrap SCSS, 
 * and then adds website specific styling.
 */
 
@import "../../bootstrap/scss/bootstrap";[7]

...and then all the other b4st styles

    Note [6]: It is good practice to add a title comment of some kind, and an introduction/ explanation to remind yourself (or to inform co-workers) what this file contains.

    Note [7]: You don't need to add the .scss extension, because the preprocessor will obtain the file according to its (path and) filename.

  4. Now comment out the register and enqueue for your local bootstrap.min.css (which you set up in step A.4.).

    // wp_register_style('bootstrap-css', get_template_directory_uri() . '/bootstrap/css/bootstrap.min.css', false, '4.0.0-beta.2', null);
// wp_enqueue_style('bootstrap-css');

  5. Preprocess: compile theme/css/b4st.css from theme/scss/b4st.scss. Brief instructions follow.

In Codekit:

  1. Drag and drop (or select) the entire b4st/ root folder as the Project Folder.
  2. Codekit will automatically watch everything for changes and then preprocess accordingly (if you made no change, you can still get it to compile by clicking the Compile button).
  3. However, unless you tell it otherwise, CodeKit will generate the CSS file in the same folder as the SCSS file. So, you must go into the Project folder tree in CodeKit, find b4st.scss and then, in the Options sidebar, click the Change link next to the Output To This Path reference. Set it to theme/css/.
  4. Unless you tell CodeKit otherwise, it will minify the CSS and name the compiled file as b4st-min.css – you need to Change that (same route as above), because you are still your WordPress theme is still looking for b4st.css in its enqueues.

In Scout-App:

  1. Drag and drop (or select) the entire b4st/ root folder as the Project Folder.
  2. Select theme/scss/ as the Input Folder.
  3. Select theme/css/ as the Output Folder.
  4. Now press Play (blue circle button with white triangle icon), and Scout-App will begin watching for changes in the Input Folder. Every time you save b4st.scss (or save something that is imported into b4st.scss), Scout-App will compile b4st.css.

In Koala:

  1. Drag and drop (or select, using the big white "+" icon) the entire b4st/ root folder as the Project Folder.
  2. Koala will now find and list all the files within your project that Koala knows how to compile and minify – e.g. SCSS, CSS, JS (and several others not in Bootstrap or b4st). Koala will watch these files for changes, and compile and minify accordingly.
  3. However, unless you tell it otherwise, Koala will generate the CSS file in the same folder as the SCSS file. So, select theme/scss/b4st.scss on Koala's list of Styles, then do right-click > Set Output Path and select theme/css/ and fill the Save As: b4st.css.
  4. Now press the Compile button to generate the new b4st.css file.

C. Customizing and building upon Bootstrap

You are now ready to customize and build upon Bootstrap SCSS – without actually touching or modifying the Bootstrap SCSS at all.

Before you read the following, go to the Theming page in the Bootstrap 4 docs and have a read.

The following tutorial notes are intened to help newbies get more out of working with (but not actually touching) Bootstrap SCSS, so that they can better understand and do the stuff mentioned in the Bootstrap 4 Theming docs.

1. Overriding Bootstrap !default variables

The Bootstrap SCSS has many hundreds of reusable SCSS variables defining colors, spacing, media query breakpoints, typography, tables, form elements, z-indexes of components, and other component details.

These variables are all set in one file, scss/_variables.scss[8] – and this is imported into scss/bootstrap.scss before any of the other imports that use these variables.

Note [8]: The underscore (_) prefix for some SCSS files tells the preprocessor that this is not a file to be compiled into its own CSS file – it is a partial that is intended to be @imported into another SCSS file.

Each of these Bootstrap variables is set as !default variables – so that you can override them.

What this means for you is: for any of these variables, if you declare the same variables before the Bootstrap variables are declared, but with your own chosen values, then the preprocessor will preferentially incorporate your chosen values into the compiled CSS.

Of the many hundreds of variables, here is one example of what you can do: you can change the Bootstrap primary color (used for buttons, forms, badges and some other stuff). Like so:

  1. In the Bootstrap scss/_variables.scss you will see:

    $primary:       $blue !default;

    And that variable $blue has been set earlier in the variables file, in the Bootstrap color system.

    Read more about Bootstrap colors here: http://getbootstrap.com/docs/4.0/getting-started/theming/#color

  2. You can override that $primary color variable. If you set your own choice of $primary color in your theme/scss/b4st.scss before you import bootstrap.scss then your chosen $primary color overrides the $primary: $blue !default; and gets compiled into the b4st.css – everywhere that the $primary variable is used.

    /*
 * b4st (SCSS project)
 * ===================
 * Notes...
 */

// Your variables

$primary:       #009922;
...

@import "../../bootstrap/scss/bootstrap";

...and then all the other b4st styles

    So now, .btn-primary and other stuff that uses $primary will adopt the color #009922.

  3. You can do better than that. Think of b4st.scss as your master SCSS file, into which you @import and organize everything else.

    /*
 * b4st (SCSS project)
 * ===================
 * Notes...
 */

@import "your-variables";

@import "../../bootstrap/scss/bootstrap";

@import "your-header";
@import "your-sidebar";
@import "your-whatever";
...

2. Enabling/disabling the Bootstrap built-in theme

You may remember that Bootstrap 3 had a separate theme file, bootstrap-theme.css that added gradients, shadows and other decoration to the otherwise "flat" Bootstrap CSS.

There is a similar theme built-in to Bootstrap 4 SCSS (but not enabled). You don't need to load a separate CSS file; you only need to "toggle" the Bootstrap variables that enable/disable these decorative styles, and switch them on (some or all – it's up to you).

So, in the Bootstrap scss/variables.scss file you will see:

// Options
//
// Quickly modify global styling by enabling or disabling optional features.

$enable-caret:              true !default;
$enable-rounded:            true !default;
$enable-shadows:            false !default;
$enable-gradients:          false !default;
$enable-transitions:        true !default;
$enable-hover-media-query:  false !default;
$enable-grid-classes:       true !default;
$enable-print-styles:       true !default;

Try it out: just override the shadows and gradients like so:

$enable-shadows:            true;
$enable-gradients:          true;

Read more about these global styling variables here: http://getbootstrap.com/docs/4.0/getting-started/theming/#sass-options

3. @importing only part of Bootstrap

Step B.3. above assumes that you wish to @import the whole of Bootstrap 4 into your theme CSS.

But what if you are sure that there are some Bootstrap components that you will never use? Then you can simply remove the unwanted stuff by not @importing it into your stylesheet.

You could speed up your website load times that way, and improve your SEO and not lose visitors who may bounce away, tired of waiting for your website to load on their phone.

Instead of simply doing this step B.3. you can do this:

  1. Duplicate bootstrap.scss into your theme/scss/ (and rename it);
  2. Delete (or 'comment out') those component @imports inside it, that you don't want, and then
  3. @import your smaller Bootstrap instead, as e.g.:
@import "your-smaller-bootstrap.scss";

4. Using Bootstrap variables in your SCSS

You were introduced to Bootstrap variables in C.1. above.

As Bootstrap SCSS is being @imported into your SCSS project, you can also use its variables (with whatever your values are), in your downstream additional styling.

For example, do you need your .something to have the same background color and the same rounded corners as are used in Bootstrap?

.something {
	...
	background-color: $success;
	border-radius: $border-radius;
	...
}

5. Other advanced stuff that you can do

That's the basics covered. The Bootstrap docs is the place to learn things you can do in theming Bootstrap.

http://getbootstrap.com/docs/4.0/getting-started/theming/

Postscript

You may also need a "kitchen sink" collection of all the Bootstrap 4 components, so that you can see what your customization looks like.

So here are a couple of options – from these you can copy all the Bootstrap stuff from the HTML file, and place it in a WordPress Post or Page, and away you go.

Atomic Boot Pug

This is a little side-project of mine.

Inspired by Brad Frost's Atomic Design, Atomic Boot Pug is comprised of a set of Bootstrap 4 docs demo snippets (tranformed into Pug mixins) reorganized into a starter styleguide.

https://github.com/SimonPadbury/Atomic-Boot-Pug

"Bootstrap 4 Components Reference Kitchen Sink" on Codepen

https://codepen.io/JacobLett/pen/KaMoEm