A Wagtail app to pick generic models (rather than snippets or pages)
Project description
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.
[]
Installation
- Grab the package from pip with
pip install wagtailmodelchoosers
. - Add
wagtailmodelchoosers
inINSTALLED_APPS
in your settings.
Usage
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.
Draftail
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 wagtail_hooks.py
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
)
@hooks.register('register_rich_text_features')
def register_chooser_feature(features):
register_custom_model_chooser_feature(features)
@hooks.register('insert_editor_js')
def insert_chooser_js():
return register_custom_model_chooser_plugin
Configuration
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_DISPLAY = 'name'
MODEL_CHOOSERS_OPTIONS = {
'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.
Development
Installation
Requirements: virtualenv
, pyenv
, twine
git clone git@github.com:springload/wagtailmodelchoosers.git
cd wagtailmodelchoosers/
virtualenv .venv
source ./.venv/bin/activate
pip install -e .[testing,docs] -U
nvm install
npm install
Commands
make help # See what commands are available.
# TODO: Complete commands
Releases
- Make a new branch for the release of the new version.
- Update the CHANGELOG.
- Update the version number in
wagtailmodelchoosers/__init__.py
andpackage.json
, following semver. - Make a PR and squash merge it.
- Back on master with the PR merged, use
make publish
(confirm, and enter your password). - Finally, go to GitHub and create a release and a tag for the new version.
- Done!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for wagtailmodelchoosers-2.0b1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f9abe9f4bb5b584a9839edc79cfbe2a4b04db239f2a6e83c97482e6bc45b3a3f |
|
MD5 | 4bfe7a594f0986db881a4cf798862663 |
|
BLAKE2b-256 | 300ae784bd09c307354e964e30024370f472b6e59f11f42f16fc08c9a33ed621 |