https://github.com/springload/wagtailmodelchoosers

A Wagtail app to pick generic models (rather than snippets or pages)
https://github.com/springload/wagtailmodelchoosers

modelchooser wagtail

Last synced: 4 months ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/springload/wagtailmodelchoosers
• Owner: springload
• License: mit
• Created: 2016-07-05T21:30:32.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2023-06-27T23:36:17.000Z (over 2 years ago)
• Last Synced: 2024-11-07T05:09:53.838Z (over 1 year ago)
• Topics: modelchooser, wagtail
• Language: Python
• Homepage:
• Size: 1.12 MB
• Stars: 24
• Watchers: 20
• Forks: 7
• Open Issues: 16
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

          
.. image:: https://travis-ci.org/springload/wagtailmodelchoosers.svg?branch=master

   :target: https://travis-ci.org/springload/wagtailmodelchoosers

.. image:: https://img.shields.io/pypi/v/wagtailmodelchoosers.svg

   :target: https://pypi.python.org/pypi/wagtailmodelchoosers

   

wagtailmodelchoosers

====================

    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.

.. image:: https://cdn.rawgit.com/springload/wagtailmodelchoosers/b7b6202/.github/wagtailmodelchoosers-screenshot.png

   :width: 728 px

Installation

------------

Grab the package from pip with ``pip install wagtailmodelchoosers``, then add ``wagtailmodelchoosers`` in ``INSTALLED_APPS`` in your settings.

Usage

-----

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

.. code:: python

    from wagtail.wagtailcore import blocks

    from wagtailmodelchoosers.blocks import ModelChooserBlock

    

    class CustomBlock(blocks.StructBlock):

        custom_model = ModelChooserBlock('custom_model')  # `chooser` can be a positional argument, the keyword is used here for clarity.

       

``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.

.. code:: python

    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'),  # `chooser` can be a positional argument, the keyword is used here for clarity.

        ]

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

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.

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.

.. code:: python

    MODEL_CHOOSERS_OPTIONS = {

        'navigation': {

            'label': 'Navigation',                                   # The label to use for buttons or modal title

            'display': 'name',                                       # 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'},

            ],

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

            'fields_to_save': ['id'] + RATE_CHOOSER_DISPLAY_FIELDS,  # ONLY FOR REMOTE: The remote objects fields to save to the DB. Leave empty to save the whole object.

            'remote_endpoint': 'http://...'                          # ONLY FOR REMOTE: The remote API endpoint.

            'pk_name': 'uuid',                                       # The primary key name of the model

        }

    }

    

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``

.. code:: sh

    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

~~~~~~~~

.. code:: sh

    make help            # See what commands are available.

TODO: Complete

Releases

~~~~~~~~

*  Make a new branch for the release of the new version.

*  Update the `CHANGELOG `_.

*  Update the version number in ``wagtailmodelchoosers/__init__.py`` and ``package.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!