-
Notifications
You must be signed in to change notification settings - Fork 7
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
Closed
Changes from 15 commits
Commits
Show all changes
16 commits
Select commit
Hold shift + click to select a range
8923ec8
Update test matrix
4c8ca3a
Update paths
8608bd7
Add django-filter to dependencies
3a0b346
Fix Django 2 compatibility
e209648
Add modelchoosers fields to test page
4ec6eff
Make edit handlers Wagtail 2.0 compatible
e99fb86
Update test matrix
e2d9b8e
Convert README to markdown
b00e198
Update screenshot
a8f63af
Clarify documentation
1893cf4
Upgrade React to match Wagtail 2.0
7b0ab54
Remove unneeded Python 2
50c5e43
Hook with Wagtail's features and Wagtail
ab03eed
Update sources for Draftail 0.17 compatibility
0e7aaad
Fix tests
3bade45
Release 2.0b1
mojeto File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
nvm install | ||
npm install | ||
``` | ||
|
||
### Commands | ||
|
||
```sh | ||
make help # See what commands are available. | ||
|
||
# TODO: Complete commands | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could be as simple as using the output of
|
||
``` | ||
|
||
### 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! |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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.