Bootstrap (and Material)#

There are two Bootstrap themes, both of which use Bootstrap version 5.

Choosing your theme#

The default Bootstrap theme is based off the default settings that ship with Bootstrap. It’s recommended if you want a simple, practical starting point or if you want to use your own theme.

The Material theme is based on Creative Tim’s Material Kit and Material Dashboard products. It’s flashier than the default theme, though is more opinionated and less compatible with other products.

You can watch a 3-minute tour of the Material theme here:

Customizing the theme#

Pegasus’s file structure is based on the Bootstrap documentation. Any of the variables used in Bootstrap can be changed by modifying the assets/styles/site-bootstrap.scss file.

A complete list of available variables can be found in ./node_modules/bootstrap/scss/variables.

Try adding the following lines to your file (after importing functions) to see how it changes things:

// Configuration
@import "~bootstrap/scss/functions";

$primary: #2e7636;  // change primary color to green
$body-color: #00008B;  // change main text to blue

// rest of file here...

You’ll have to run npm run dev to see the changes take. For more details on building the CSS files, see the front end documentation.

The Bootstrap documentation has much more detail on customizing your theme!

Customizing the Material theme#

The customization process outlined above largely works for the Material theme as well.

For example, you can change the primary color from the default magenta to a dark green by adding the following lines towards the top of assets/styles/site-bootstrap.scss:

// Configuration
@import "~bootstrap/scss/functions";

// add these lines
$primary: #2e7636;  // change primary color + gradients to green
$primary-gradient: #2e7676;
$primary-gradient-state: #2e7676;

You will also have to build your front end to see the changes.

Material has more customization options than the default theme, which can be found in the Material Dashboard documentation. The theme files live in the assets/material-dashboard folder. You can see the modifications that have been made for Pegasus support on Github here. In particular, a few bugs have been fixed, and the unused pro files have been removed.

Creative Tim offers pro versions of Material Dashboard and Material Kit which are helpful if you want to have access to more pages / components. These should integrate seamlessly with the Pegasus theme.

Enabling Material’s JavaScript#

Pegasus doesn’t ship with the Material theme JavaScript built in. If you would like to use their JavaScript functionality (required for many of their components) you can take the following steps:

  1. Download the material-kit.min.js file from Creative Tim’s Github repository.

  2. Copy it into your Django static directory. For example, to <project_root>/static/js

  3. Add it to the <head> section of your base.html template (or wherever you want to use it):

<script src="{% static 'js/material-kit.min.js'%}"></script>

After completing these steps, the Material Kit JavaScript functionality should work.

Working with JavaScript in Django templates#

If you want to call bootstrap JavaScript from a Django template file, you can make the bootstrap library (or subsets of it) available on the browser window.

To make all of bootstrap available, you can modify site-bootstrap.jsb to just be these lines:

require('./styles/site-bootstrap.scss');
window.bootstrap = require('bootstrap');

After rebuilding the front end you can then call bootstrap in a Django template like this:

{% block page_js %}
<script>
  document.addEventListener('DOMContentLoaded', function() {
    const onLoadModal = new bootstrap.Modal(document.getElementById('onLoadModal'));
    onLoadModal.show();
  });
</script>
{% endblock %}

This example will open the modal with ID onLoadModal on page load.

Alternatively, you can add individual bootstrap javascript modules via site-bootstrap.js like this:

require('./styles/site-bootstrap.scss');
// <other require statements here>
window.Modal = require('bootstrap/js/dist/modal');  // modals (used by teams)

And then call it in a Django template like this (with no bootrap. prefix):

const onLoadModal = new Modal(document.getElementById('landing-page-modal'));