Skip to content

Getting started

Installation

Wagtail Personalisation requires Wagtail 7+ and Django 5.2+.

To install the package with pip:

pip install wagtail-personalisation

Next, include the wagtail_personalisation, wagtail_modeladmin and wagtailfontawesomesvg apps in your project's INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'wagtail_modeladmin',  # Don't repeat if it's there already
    'wagtail_personalisation',
    'wagtailfontawesomesvg',
    # ...
]

Make sure that django.contrib.sessions.middleware.SessionMiddleware has been added in first, this is a prerequisite for this project.

MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware',
    # ...
]

Configuring available rules (optional)

By default, all built-in rules and any custom rules that inherit from AbstractBaseRule will be available in the Segment admin interface. If you want to control which rules are available, you can specify them using the WAGTAIL_PERSONALISATION_RULES setting in your Django settings:

WAGTAIL_PERSONALISATION_RULES = [
    'wagtail_personalisation.TimeRule',
    'wagtail_personalisation.DayRule',
    'wagtail_personalisation.DeviceRule',
    'wagtail_personalisation.UserIsLoggedInRule',
    'wagtail_personalisation.QueryRule',
    'wagtail_personalisation.ReferralRule',
    'wagtail_personalisation.VisitCountRule',
    'wagtail_personalisation.OriginCountryRule',
    # Add your custom rules here
    'myapp.CustomRule',
]

If this setting is not specified, all rules will be available (default behavior).

The format for rule names is 'app_label.ModelName'. This is particularly useful when:

  • You want to exclude certain built-in rules that aren't relevant to your project
  • You've created custom rules and want to ensure only specific rules are available
  • You want to prevent unexpected custom rules from appearing automatically

Using the sandbox

To experiment with the package you can use the sandbox provided in the repository. It includes a couple of segments with rules, a personalisable page with a variant and a personalisable StreamField block.

To install this you will need to create and activate a virtualenv and then run make sandbox. This will start a fresh Wagtail install, with the personalisation module enabled, on http://localhost:8000 and http://localhost:8000/cms/. The superuser credentials are superuser@example.com with the password testing.