=====================
Wagtail model chooser
=====================
A plugin for Wagtail that provides convenience methods for setting up chooser modals
for arbitrary models.
Installing
==========
Install using pip::
pip install wagtail-modelchooser
Then add it to your ``INSTALLED_APPS``:
.. code-block:: python
INSTALLED_APPS = [
# ...
'wagtailmodelchooser',
# ...
]
It works with Wagtail 4.0 and upwards.
For older versions of Wagtail check previous versions of the package.
Quick start
===========
To enable the chooser for your model, you must register the model.
For simple cases, decorate your model with ``@register_model_chooser``:
.. code:: python
from django.db import models
from wagtailmodelchooser import register_model_chooser
@register_model_chooser
class Author(models.Model):
name = models.CharField(max_length=255)
def __str__(self):
# The ``str()`` of your model will be used in the chooser
return self.name
You can then use either ``FieldPanel`` in an edit handler definition,
or ``ModelChooserBlock`` in a ``StreamField`` definition:
.. code:: python
from wagtail.wagtailcore.blocks import RichTextBlock
from wagtail.wagtailcore.fields import StreamField
from wagtail.wagtailcore.models import Page
from wagtail.wagtailadmin.edit_handlers import FieldPanel
from wagtailmodelchooser.blocks import ModelChooserBlock
class Book(Page):
name = models.CharField(max_length=255)
author = models.ForeignKey(Author)
content_panels = [
FieldPanel('name'),
FieldPanel('author'),
]
class ContentPage(Page):
body = StreamField([
('text', RichTextBlock()),
('author', ModelChooserBlock('books.Author')),
])
content_panels = [
StreamFieldPanel('body'),
]
Customisation options
=====================
If you want to customize the content or behaviour of the model chooser modal you have several options. These are illustrated through some examples below.
If you wanted to add an additional filter field to the popup, you might do that as follows:
.. code:: python
from django.db import models
from wagtailmodelchooser import register_model_chooser, Chooser
class City(models.Model):
name = models.CharField(max_length=255)
capital = models.BooleanField()
def __str__(self):
# The ``str()`` of your model will be used in the chooser
return self.name
@register_model_chooser
class CityChooser(Chooser):
model = City
modal_template = 'app_name/city_modal.html'
modal_results_template = 'app_name/city_modal_results.html'
def get_queryset(self, request):
qs = super().get_queryset(request)
if request.GET.get('capital'):
qs = qs.filter(capital=request.GET.get('capital') == '0')
return qs
Since wagtailmodelchooser is built largely on the ChooserViewSet_ functionality already found in Wagtail, if you wish to do deeper customisation it is recommended to use that feature directly.
.. _ChooserViewSet: https://docs.wagtail.org/en/stable/extending/generic_views.html#chooserviewset
Raw data
{
"_id": null,
"home_page": "https://github.com/takeflight/wagtailmodelchooser/",
"name": "wagtail-modelchooser",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Tim Heap",
"author_email": "developers@neonjungle.studio",
"download_url": "https://files.pythonhosted.org/packages/cb/16/1609db0fb3d7aaac1693424f6aafa6af90dbcd6f49295aae93739faeeabc/wagtail-modelchooser-4.0.1.tar.gz",
"platform": null,
"description": "=====================\nWagtail model chooser\n=====================\n\nA plugin for Wagtail that provides convenience methods for setting up chooser modals \nfor arbitrary models.\n\n\nInstalling\n==========\n\nInstall using pip::\n\n pip install wagtail-modelchooser\n\nThen add it to your ``INSTALLED_APPS``:\n\n.. code-block:: python\n\n INSTALLED_APPS = [\n # ...\n 'wagtailmodelchooser',\n # ...\n ]\n\nIt works with Wagtail 4.0 and upwards.\nFor older versions of Wagtail check previous versions of the package.\n\nQuick start\n===========\n\nTo enable the chooser for your model, you must register the model.\nFor simple cases, decorate your model with ``@register_model_chooser``:\n\n.. code:: python\n\n from django.db import models\n\n from wagtailmodelchooser import register_model_chooser\n\n\n @register_model_chooser\n class Author(models.Model):\n name = models.CharField(max_length=255)\n\n def __str__(self):\n # The ``str()`` of your model will be used in the chooser\n return self.name\n\nYou can then use either ``FieldPanel`` in an edit handler definition,\nor ``ModelChooserBlock`` in a ``StreamField`` definition:\n\n.. code:: python\n\n from wagtail.wagtailcore.blocks import RichTextBlock\n from wagtail.wagtailcore.fields import StreamField\n from wagtail.wagtailcore.models import Page\n from wagtail.wagtailadmin.edit_handlers import FieldPanel\n from wagtailmodelchooser.blocks import ModelChooserBlock\n\n class Book(Page):\n name = models.CharField(max_length=255)\n author = models.ForeignKey(Author)\n\n content_panels = [\n FieldPanel('name'),\n FieldPanel('author'),\n ]\n\n class ContentPage(Page):\n body = StreamField([\n ('text', RichTextBlock()),\n ('author', ModelChooserBlock('books.Author')),\n ])\n\n content_panels = [\n StreamFieldPanel('body'),\n ]\n\n\n\nCustomisation options\n=====================\n\nIf you want to customize the content or behaviour of the model chooser modal you have several options. These are illustrated through some examples below.\n\nIf you wanted to add an additional filter field to the popup, you might do that as follows:\n\n.. code:: python\n\n from django.db import models\n\n from wagtailmodelchooser import register_model_chooser, Chooser\n\n\n class City(models.Model):\n name = models.CharField(max_length=255)\n capital = models.BooleanField()\n\n def __str__(self):\n # The ``str()`` of your model will be used in the chooser\n return self.name\n\n @register_model_chooser\n class CityChooser(Chooser):\n model = City\n modal_template = 'app_name/city_modal.html'\n modal_results_template = 'app_name/city_modal_results.html'\n\n def get_queryset(self, request):\n qs = super().get_queryset(request)\n if request.GET.get('capital'):\n qs = qs.filter(capital=request.GET.get('capital') == '0')\n\n return qs\n\n\nSince wagtailmodelchooser is built largely on the ChooserViewSet_ functionality already found in Wagtail, if you wish to do deeper customisation it is recommended to use that feature directly.\n\n.. _ChooserViewSet: https://docs.wagtail.org/en/stable/extending/generic_views.html#chooserviewset\n\n\n",
"bugtrack_url": null,
"license": "BSD License",
"summary": "Model choosers for Wagtail admin",
"version": "4.0.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6f62bf5d063ae5bd3e9ddfca750da1e22c3f57779a34ace1e864c672b580ad33",
"md5": "3b1c1e5f1d1946603edb89e0b709684a",
"sha256": "b7ea0fb81cdd7367ed90dff043289e264502d97a9297b7fb69c148a0a81cee6a"
},
"downloads": -1,
"filename": "wagtail_modelchooser-4.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b1c1e5f1d1946603edb89e0b709684a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12145,
"upload_time": "2023-03-30T04:08:30",
"upload_time_iso_8601": "2023-03-30T04:08:30.028135Z",
"url": "https://files.pythonhosted.org/packages/6f/62/bf5d063ae5bd3e9ddfca750da1e22c3f57779a34ace1e864c672b580ad33/wagtail_modelchooser-4.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb161609db0fb3d7aaac1693424f6aafa6af90dbcd6f49295aae93739faeeabc",
"md5": "a7f90b3fa3cf387c4ea85ac1456fce1f",
"sha256": "ec1c9c7598cdc019683c7e93ed95b0acf1d32b9b24e8a564b8f373bf48a9ed36"
},
"downloads": -1,
"filename": "wagtail-modelchooser-4.0.1.tar.gz",
"has_sig": false,
"md5_digest": "a7f90b3fa3cf387c4ea85ac1456fce1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9920,
"upload_time": "2023-03-30T04:08:32",
"upload_time_iso_8601": "2023-03-30T04:08:32.890596Z",
"url": "https://files.pythonhosted.org/packages/cb/16/1609db0fb3d7aaac1693424f6aafa6af90dbcd6f49295aae93739faeeabc/wagtail-modelchooser-4.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-30 04:08:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "takeflight",
"github_project": "wagtailmodelchooser",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "wagtail-modelchooser"
}
JSON
