Skip to main content

A Wagtail app to pick generic models (rather than snippets or pages)

Project description

Travis PyPi

Wagtail Model Choosers

A Wagtail app to pick generic models (rather than snippets or pages).

This is alpha software, use at your own risk. Do not use in production (yet).

Check out Awesome Wagtail for more awesome packages and resources from the Wagtail community.



  1. Grab the package from pip with pip install wagtailmodelchoosers.
  2. Add wagtailmodelchoosers in INSTALLED_APPS in your settings.


Blocks & Fields

ModelChooserBlock takes the name of the chooser configuration as first positional argument. Use other block kwargs (e.g. required) as usual.

from wagtail.wagtailcore import blocks
from wagtailmodelchoosers.blocks import ModelChooserBlock

class CustomBlock(blocks.StructBlock):
    custom_model = ModelChooserBlock(chooser='custom_model')

ModelChooserPanel takes the name of the field as first positional argument (like a regular Panel) and the name of the chooser configuration as second positional argument. Use other panel kwargs as usual.

from django.db import models
from wagtail.core.models import Page
from wagtailmodelchoosers.edit_handlers import ModelChooserPanel

class CustomPage(Page):
    custom_model = models.ForeignKey('myapp.CustomModel')

    panels = [
        ModelChooserPanel('custom_model', chooser='custom_model'),

To select a model from a remote API, respectively use RemoteModelChooserBlock and RemoteModelChooserPanel instead.


Important: Whether you use WagtailDraftail or use Wagtail 2.x built-in Draftail editor, the underlying version of Draftail needs to be at least v0.17.0.

If you have WagtailDraftail installed, it will automatically register the ModelSource and RemoteModelSource to the JS. Refer to WagtailDraftail's documentation to hook it up properly.

If you use Draftail from Wagtail 2.x, do the following in you app's file:

from wagtailmodelchoosers.rich_text import get_chooser_feature

register_custom_model_chooser_feature, register_custom_model_chooser_plugin = get_chooser_feature(
    # Required.
    chooser='custom_model',       # Same as what was used for the block and/or panel.
    feature_name='custom_model',  # RichText's feature name (e.g. `RichTextField(features=['bold', 'custom_model'])`).
    feature_type='CUSTOM_MODEL',  # Draftail's *unique* and *never changing* feature ID.

    # Optional but recommended for nice UI display.
    icon='icon icon-snippet',
    label='Custom Model',
    description='Insert a Custom Model inline',

    # Optional if you need to customise the generic behaviour.
    # Note that it requires good knowlegde of Draftail source/decorators and Wagtail features converters.
    from_database_format=None,    # Wagtail from database converter
    to_database_format=None,      # Wagtail to database converter
    js_source='',                 # Draftail Source
    js_decorator='',              # Draftail Decorator

def register_chooser_feature(features):

def insert_chooser_js():
    return register_custom_model_chooser_plugin


It looks for a MODEL_CHOOSERS_OPTIONS dictionary in the settings where the key is the name of the chooser and the value, a dictionary of options.

The ModelChooser and RemoteModelChooser share a similar base configuration and only have a few specific fields.

    'navigation': {
        'label': 'Navigation',                                   # The label to use for buttons or modal title
        'display': NAVIGATION_DISPLAY,                           # The field to display when selecting an object
        'list_display': [                                        # The fields to display in the chooser
            {'label': 'Name', 'name': 'name'},
            {'label': 'Identity', 'name': 'identity'},
            {'label': 'Active', 'name': 'active'},
        'pk_name': 'uuid',                                       # The primary key name of the model

        # ONLY FOR MODEL:
        'content_type': 'core.Navigation',                       # The django content type of the model

        # ONLY FOR REMOTE:
        'fields_to_save': ['id', NAVIGATION_DISPLAY],            # The remote objects fields to save to the DB (it should contain the `display` field). Leave empty to save the whole object.
        'remote_endpoint': 'https://...'                         # The remote API endpoint.

In addition, you can customise the mapping of the key of the API, see the configuration key names being used for the query and the response.



Requirements: virtualenv, pyenv, twine

git clone
cd wagtailmodelchoosers/
virtualenv .venv
source ./.venv/bin/activate
pip install -e .[testing,docs] -U
nvm install
npm install


make help            # See what commands are available.

# TODO: Complete commands


  1. Make a new branch for the release of the new version.
  2. Update the CHANGELOG.
  3. Update the version number in wagtailmodelchoosers/ and package.json, following semver.
  4. Make a PR and squash merge it.
  5. Back on master with the PR merged, use make publish (confirm, and enter your password).
  6. Finally, go to GitHub and create a release and a tag for the new version.
  7. Done!

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wagtailmodelchoosers-2.0b1.tar.gz (147.1 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page