Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Wagtail 2.0 Compatibility #22

Closed
wants to merge 16 commits into from
Closed
Binary file modified .github/wagtailmodelchoosers-screenshot.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 8 additions & 8 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,18 @@ cache:
matrix:
# See `Which version combinations to include in Travis test matrix?` in `/docs/README.md`.
include:
- env: TOXENV=py34-dj111-wt113
- env: TOXENV=py34-dj2-wt21
python: 3.4
- env: TOXENV=py35-dj111-wt113
- env: TOXENV=py35-dj2-wt21
python: 3.5
- env: TOXENV=py36-dj111-wt112
- env: TOXENV=py36-dj111-wt2
python: 3.6
- env: TOXENV=py36-dj111-wt113
- env: TOXENV=py36-dj111-wt21
python: 3.6
- env: TOXENV=py36-dj2-wt2
python: 3.6
- env: TOXENV=py36-dj2-wt21
python: 3.6
# - env: TOXENV=py36-dj111-wt2b
# python: 3.6
# - env: TOXENV=py36-dj2-wt2b
# python: 3.6
install:
- nvm install
- npm install
Expand Down
156 changes: 156 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
[![Travis](https://travis-ci.org/springload/wagtailmodelchoosers.svg?branch=master)](https://travis-ci.org/springload/wagtailmodelchoosers)
[![PyPi](https://img.shields.io/pypi/v/wagtailmodelchoosers.svg)](https://pypi.python.org/pypi/wagtailmodelchoosers)

# 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](https://github.com/springload/awesome-wagtail) for more awesome packages and resources from the Wagtail community.

[![screenshot](https://cdn.rawgit.com/springload/wagtailmodelchoosers/b7b6202/.github/wagtailmodelchoosers-screenshot.png)]

## Installation

1. Grab the package from pip with `pip install wagtailmodelchoosers`.
1. Add `wagtailmodelchoosers` in `INSTALLED_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.

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

```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'),
]
```

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

### Draftail

**Important**: Whether you use [WagtailDraftail](https://github.com/springload/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](https://github.com/springload/wagtaildraftail#configuration) to hook it up properly.

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

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

```python
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](https://github.com/springload/wagtailmodelchoosers/blob/c36bb877eef4ac4af6b221f0d7ff7416354754c7/wagtailmodelchoosers/utils.py#L107-L112) and the [response](https://github.com/springload/wagtailmodelchoosers/blob/c36bb877eef4ac4af6b221f0d7ff7416354754c7/wagtailmodelchoosers/utils.py#L115-L123).


## Development

### Installation

Requirements: `virtualenv`, `pyenv`, `twine`

```sh
git clone git@github.com:springload/wagtailmodelchoosers.git
cd wagtailmodelchoosers/
virtualenv .venv
source ./.venv/bin/activate
pip install -e .[testing,docs] -U
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be replaced by make init, which takes care of the migrations too.

nvm install
npm install
```

### Commands

```sh
make help # See what commands are available.

# TODO: Complete commands
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could be as simple as using the output of make help:

make help            # See what commands are available.
make init            # Install dependencies and initialise for development.
make clean-pyc       # Remove Python file artifacts.
make start           # Starts the development server.
make lint            # Lint the project.
make test            # Test the project.
make test-coverage   # Run the tests while generating test coverage data.
make test-ci         # Continuous integration test suite.
make update-test-fixture # Update test fixture from the db.
make dist            # Compile the JS and CSS for release.
make publish         # Publishes a new version to pypi.

```

### Releases

1. Make a new branch for the release of the new version.
1. Update the [CHANGELOG](https://github.com/springload/wagtailmodelchoosers/blob/master/CHANGELOG.md).
1. Update the version number in `wagtailmodelchoosers/__init__.py` and `package.json`, following semver.
1. Make a PR and squash merge it.
1. Back on master with the PR merged, use `make publish` (confirm, and enter your password).
1. Finally, go to GitHub and create a release and a tag for the new version.
1. Done!
121 changes: 0 additions & 121 deletions README.rst

This file was deleted.

6 changes: 4 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,16 @@ We align our browser support targets with that of Wagtail. Have a look at the [o

Python versions as defined in `setup.py` classifiers.

Wagtail versions as [supported](http://docs.wagtail.io/en/latest/releases/upgrading.html) by Wagtail (LTS, current and current-1).
Wagtail versions `>=2.0` and as [supported](http://docs.wagtail.io/en/latest/releases/upgrading.html) by Wagtail (LTS, current and current-1).

Django/Wagtail combinations as [supported](http://docs.wagtail.io/en/latest/releases/upgrading.html#compatible-django-python-versions) by Wagtail (for the Wagtail versions as defined above).

Note: The last version of this plugin to support Wagtail prior to 2.0 is `v0.1.2`.

### Which version combinations to include in Travis test matrix?

In order to keep for CI build time from growing out of control, not all Python/Django/Wagtail combinations will be tested.

Test as follow:
- All supported Django/Wagtail combinations with the latest supported Python version of the `3.x` series.
- All supported Django/Wagtail combinations with the latest supported Python version.
- The latest supported Django/Wagtail combination for the remaining Python versions.
Loading