Creating & Using Custom Settings In Your Wagtail Site

By Chelsea Shaw Christopher Shaw

This week we are looking at how we can create custom settings and use them across our Wagtail site. We'll also look at how these can be used across a number of sites using Wagtail's multi-site feature.



Hi and welcome to this weeks installment of Wagtail Wednesdays.

In todays video we’re going to show you how to set up and use custom site settings - Which you can use for all sorts of things, in this tutorial we’ll just use it as a place to store the social media info for our site.

Create Site Settings

The first thing we need to do is add the settings contrib module to our file. We’ll put this down here at the bottom of our INSTALLED_APPS list.

Let’s create a new folder called sitesettings and inside it we’ll make an file and a file which will contain all of our settings models.

At the top of our file we need to import models from django.db and BaseSetting and register_setting from wagtail.contrib.settings.models

Register Site Settings

We now need to register the settings we want to add, if you’ve created snippets before, this will feel familiar.

First we type @register_setting to let wagtail know we are about to define a setting model that we want to register.

Now we can create a class which will essentially define a group of settings.

We’ll call ours SocialMediaSettings and inherit from BaseSetting. We can then define any fields we want to exist within our SocialMediaSettings model. I’ll just add one called Twitter which will be a CharField with some basic attributes like max_length and help_text set up.

class SocialMediaSettings(BaseSetting):
    twitter = models.CharField(
        max_length=255, help_text='Twitter username, without the @', blank=True)

Now that we’ve set up our model lets make sure we remember to add sitesettings to our list of INSTALLED_APPS and also to make and run our migrations.

Using This In The Template

If we go into our wagtail admin and click Settings on the side bar, we’ll see that a button for our Social Media Settings has appeared here. If we click this we’ll be taken to a page where we can fill out these settings.

I’ll just put vixdigital in here for our twitter username and hit save.

To use our settings values in our templates, we need to add a context_processor to our file.

If we scroll down to our TEMPLATES object we can add our new processor down here underneath the django messages context processor. We need to add wagtail.contrib.settings.context_processors.settings.

In our template we can display the value of our twitter setting by adding

{{ settings.sitesettings.SocialMediaSettings.twitter }}

Now if we look at our page we can see vixdigital is displayed.

Using This In Python

If we want to access our settings values in our python code then we can simply import our SocialMediaSettings from sitesettings.models and call the for_site method on it passing in a request object.

We’ll quickly override the context of our home page to demonstrate this.

Now if we go to our template we can test this has worked by typing social_settings.twitter. If we refres our page we should see that this now also displays the twitter name we entered.

Using Site Settings With Multi-Site

Another good thing about settings is that when using wagtail multisite deployments we can specify different settings values for each one of our sites. To demonstrate this we’ll create a new homepage that uses the same template as our first site, and a new site that uses that homepage as its root.

If we head over to our social media settings we will now see a little dropdown box in the top right corner which we can use to toggle between the different sites in our multisite setup.

Let’s switch to site two and set the twitter username to wagtail. If we point our browser to sitetwo.localhost:8000 we’ll see our new setting value for sitetwo is being displayed instead of vixdigital!


Thanks for watching this weeks Wagtail Wednesday video, we hope you enjoyed it and got something out of it.

Don’t forget to subscribe to our channel for more videos, you can also get early access to our videos by signing up to our mailing - just follow the link in the description below.

Thanks again, and we’ll see you next time.

Want Early Access To Future Videos?

Pop your email address in the box below and receive new videos before everyone else!

<< Back to Insights