VIX-Chevron-Up

Setting Up Foundation Sass With Wagtail

By Catherine McDonough

A Bit Of Background...

We’ve recently spent some time migrating our company website from Jekyll to Wagtail CMS. We love Jekyll but we were finding that it wasn’t quite robust enough to deal with our needs so we decided to take the plunge and move to a full blown CMS - enter wagtail.io. You can read more about why we chose wagtail in Chelsea’s article.

In our Jekyll site we had a gulp/npm setup for our assets. Compiling js files, stylesheets and images.

Wagtail uses Django which is a python framework. I had never used Python or Django before so there was some learning to do to get our front-end setup migrated over.

Interacting With Requirements.Txt

Using a requirements.txt file ensures that you always have the correct versions of packages installed, similar to how a package.json file works for node modules.

Below are few commands which I found really useful when interacting with the project requirements and installing the packages needed for this task.

# Install all the packages in listed in requirements 
pip install -r requirements.txt

# Install a new package 
pip install <package name>

# List installed packages in requirements format.
pip freeze

# Get all installed packages and saves them to requirements file
pip freeze > requirements.txt
Step #1 - Setting Up Compressor

Django compressor compresses linked and inline CSS into a single cached file, it can also be used for JavaScript. Compressor is a dependency of Django Libsass which is what we’re going to be using to compile our Sass files.

To setup Django compressor

Install django compressor

pip install django_compressor

It’s a good idea to then save this to your projects requirements. To do this see the 'Interacting with requirements.txt' section above.

You will then need to make some changes to the base.py settings file..

# Add django-compressor to the list of installed apps
INSTALLED_APPS = [
    'compressor',
]

# Add the file finer to the static finders setting 
STATICFILES_FINDERS = [
    'compressor.finders.CompressorFinder',
]

# Set custom settings for compressor 
COMPRESS_OUTPUT_DIR = 'compressed'
COMPRESS_OFFLINE = True

NB. There are some custom settings that you can use, more information can be found in the docs.

Finally, add the compressor tags to your base.html file, example below

{% load compress %}

{% compress css %}
		<link rel="stylesheet" href="/static/css/one.css" type="text/css" charset="utf-8">
{% endcompress %}

If compressor has been setup correctly, your css should now be rendered something like this

<link rel="stylesheet" href="/static/CACHE/css/f7c661b7a124.css" type="text/css" charset="utf-8">
Step #2 - Setting Up Libsass

Django-libsass is a django-compressor filter to compile Sass files using libsass. It was created by Torchbox - the creators of wagtail.io

Install django-libsass, again it is a good idea to save this to your requirements file

pip install django-libsass

Add the code snippet below to your base.py settings file.

COMPRESS_PRECOMPILERS = (
    ('text/x-scss', 'django_libsass.SassCompiler'),
)

Update the code snippet in base.html . It should now be linking to a sass file and the type field should be set to scss rather than css

{% compress css %}
    <link href="{% static 'css/app.scss' %}" media="screen" rel="stylesheet" type="text/x-scss">
{% endcompress %}

As long as all your sass files are being imported into your main app.scss file, all your styling should be outputted into a single app.css file.

Step #3 - Bower And Foundation

Using Bower to install Foundation isn’t essential, however it can be useful as Bower installs the right versions of the packages you’ve specified as well as their dependencies.

To setup django-bower with Foundation

Install django-bower, again it is a good idea to save this to your requirements file

npm install -g bower
pip install django-bower

You will then need to make some changes to the base.py settings file to make sure that django-bower is setup correctly and is installing the foundation sites components.

# Add djangobower to your list of installed apps
INSTALLED_APPS = [
    'djangobower',
]

# Add the staticfinder 
STATICFILES_FINDERS = [
    'djangobower.finders.BowerFinder'
]

# Specify the route to the location you would like the bower components to be installed 
BOWER_COMPONENTS_ROOT = '/PROJECT_ROOT/static/components/'

# Add foundation sites to the list of bower componenets to be installed 
BOWER_INSTALLED_APPS = (
    'foundation-sites',
)

The final step is to correctly setup Foundation so that you can overwrite the base foundation settings and it integrates with your own sass files.

Take a copy of the foundation _settings.scss file and add it your own sass files.

You will need to update the @import path at around line 44 so that it relates to wherever you have you bower components located.

@import 'components/bower_components/foundation-sites/scss/util/util’;

You will then need to add a _foundation.scss file to select which foundation components you want to include in your project. It might look something like this..

// Make sure the charset is set appropriately
@charset 'UTF-8';

// Foundation Settings
// --------------------------------------------------
// Import the settings file where we set variables that
// override Foundation's default styles
@import '../base/settings';

// Foundation Components
// --------------------------------------------------
// Behold, here are all the Foundation components.

@import 'components/bower_components/foundation-sites/scss/foundation';

@include foundation-global-styles;
@include foundation-grid;
@include foundation-typography;
@include foundation-button;
// @include foundation-forms;
// @include foundation-visibility-classes;

Again you will need to ensure you have the correct path to your bower components folder.

Add the _foundation.scss file to your main app.scss file and foundation will now be compiled along with your own sass files into your app.css file.

That’s it!

Some useful resources:

A django-compressor filter to compile SASS files using libsass

Django-bower documentation

Foundation Install Docs

<< Back to Insights