-
Notifications
You must be signed in to change notification settings - Fork 8
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
Add initial version of wagtail-treemodeladmin #1
Changes from 1 commit
f2a2d6b
1decc3b
0db4c77
a1043ac
5e6b38b
d136f45
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,2 @@ | ||
# Auto detect text files and perform LF normalization | ||
/CHANGELOG.md merge=union |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
language: python | ||
cache: pip | ||
|
||
matrix: | ||
include: | ||
- env: TOXENV=lint | ||
python: 3.6 | ||
- env: TOXENV=py27-dj18-wag113 | ||
python: 2.7 | ||
- env: TOXENV=py27-dj111-wag113 | ||
python: 2.7 | ||
- env: TOXENV=py36-dj18-wag113 | ||
python: 3.6 | ||
- env: TOXENV=py36-dj111-wag113 | ||
python: 3.6 | ||
- env: TOXENV=py36-dj20-wag20 | ||
python: 3.6 | ||
|
||
install: | ||
pip install tox coveralls | ||
|
||
script: | ||
tox | ||
|
||
after_success: | ||
coveralls |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
include LICENSE | ||
include README.md | ||
global-include *.html |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,106 +1,120 @@ | ||
#### CFPB Open Source Project Template Instructions | ||
# Wagtail-TreeModelAdmin | ||
|
||
1. Create a new project. | ||
2. [Copy these files into the new project](#installation) | ||
3. Update the README, replacing the contents below as prescribed. | ||
4. Add any libraries, assets, or hard dependencies whose source code will be included | ||
in the project's repository to the _Exceptions_ section in the [TERMS](TERMS.md). | ||
- If no exceptions are needed, remove that section from TERMS. | ||
5. If working with an existing code base, answer the questions on the [open source checklist](opensource-checklist.md) | ||
6. Delete these instructions and everything up to the _Project Title_ from the README. | ||
7. Write some great software and tell people about it. | ||
[![Build Status](https://travis-ci.org/cfpb/wagtail-treemodeladmin.svg?branch=master)](https://travis-ci.org/cfpb/wagtail-treemodeladmin) | ||
[![Coverage Status](https://coveralls.io/repos/github/cfpb/wagtail-treemodeladmin/badge.svg?branch=master)](https://coveralls.io/github/cfpb/wagtail-treemodeladmin?branch=master) | ||
|
||
> Keep the README fresh! It's the first thing people see and will make the initial impression. | ||
Wagtail-TreeModelAdmin is an extension for Wagtail's ModelAdmin that allows for a page explorer-like navigation of Django model relationships within the Wagtail admin. | ||
|
||
- [Dependencies](#dependencies) | ||
- [Installation](#installation) | ||
- [Concepts](#concepts) | ||
- [Usage](#usage) | ||
- [Quickstart](#quickstart) | ||
- [API](#api) | ||
- [Getting help](#getting-help) | ||
- [Getting involved](#getting-involved) | ||
- [Licensing](#licensing) | ||
- [Credits and references](#credits-and-references) | ||
|
||
## Dependencies | ||
|
||
- Django 1.8+ (including Django 2.0) | ||
- Wagtail 1.13+ (including Wagtail 2.0) | ||
- Python 2.7+, 3.6+ | ||
|
||
## Installation | ||
|
||
To install all of the template files, run the following script from the root of your project's directory: | ||
1. Install wagtail-treemodeladmin: | ||
|
||
``` | ||
bash -c "$(curl -s https://raw.githubusercontent.com/CFPB/development/master/open-source-template.sh)" | ||
```shell | ||
pip install wagtail-treemodeladmin | ||
``` | ||
|
||
---- | ||
2. Add `treemodeladmin` as an installed app in your Django `settings.py`: | ||
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. On wagtail-sharing I added explicit documentation about its dependency on Wagtail ModelAdmin, as ModelAdmin is optional and isn't part of the standard Wagtail setup. |
||
|
||
# Project Title | ||
|
||
**Description**: Put a meaningful, short, plain-language description of what | ||
this project is trying to accomplish and why it matters. | ||
Describe the problem(s) this project solves. | ||
Describe how this software can improve the lives of its audience. | ||
```python | ||
INSTALLED_APPS = ( | ||
... | ||
'treemodeladmin', | ||
... | ||
) | ||
``` | ||
|
||
Other things to include: | ||
## Concepts | ||
|
||
- **Technology stack**: Indicate the technological nature of the software, including primary programming language(s) and whether the software is intended as standalone or as a module in a framework or other ecosystem. | ||
- **Status**: Alpha, Beta, 1.1, etc. It's OK to write a sentence, too. The goal is to let interested people know where this project is at. This is also a good place to link to the [CHANGELOG](CHANGELOG.md). | ||
- **Links to production or demo instances** | ||
- Describe what sets this apart from related-projects. Linking to another doc or page is OK if this can't be expressed in a sentence or two. | ||
Wagtail-TreeModelAdmin allows for a Wagtail page explorer-like navigation of Django one-to-many relationships within the Wagtail admin. In doing this, it conceptualizes the Django [`ForeignKey`](https://docs.djangoproject.com/en/2.0/ref/models/fields/#django.db.models.ForeignKey) relationship as one of parents-to-children. The parent is the destination `to` of the `ForeignKey` relationship, the child is the source of the relationship. | ||
|
||
Wagtail-TreeModelAdmin is an extension of [Wagtail's ModelAdmin](http://docs.wagtail.io/en/latest/reference/contrib/modeladmin/index.html). It is intended to be used exactly like `ModelAdmin`. | ||
|
||
**Screenshot**: If the software has visual components, place a screenshot after the description; e.g., | ||
## Usage | ||
|
||
![](https://raw.githubusercontent.com/cfpb/open-source-project-template/master/screenshot.png) | ||
### Quickstart | ||
|
||
To use Wagtail-TreeModelAdmin you first need to define some models that will be exposed in the Wagtail Admin. | ||
|
||
## Dependencies | ||
``` | ||
# libraryapp/models.py | ||
|
||
Describe any dependencies that must be installed for this software to work. | ||
This includes programming languages, databases or other storage mechanisms, build tools, frameworks, and so forth. | ||
If specific versions of other software are required, or known not to work, call that out. | ||
from django.db import models | ||
|
||
## Installation | ||
|
||
Detailed instructions on how to install, configure, and get the project running. | ||
This should be frequently tested to ensure reliability. Alternatively, link to | ||
a separate [INSTALL](INSTALL.md) document. | ||
class Author(models.Model): | ||
name = models.CharField(max_length=255) | ||
|
||
## Configuration | ||
class Book(models.Model): | ||
author = models.ForeignKey(Author, on_delete=models.PROTECT) | ||
title = models.CharField(max_length=255) | ||
``` | ||
|
||
If the software is configurable, describe it in detail, either here or in other documentation to which you link. | ||
Then create the `TreeModelAdmin` subclasses and register the root the tree using `modeladmin_register`: | ||
|
||
## Usage | ||
```python | ||
# libraryapp/wagtail_hooks.py | ||
from wagtail.contrib.modeladmin.options import modeladmin_register | ||
|
||
Show users how to use the software. | ||
Be specific. | ||
Use appropriate formatting when showing code snippets. | ||
from treemodeladmin.options import TreeModelAdmin | ||
from libraryapp.models import Author, Book | ||
|
||
## How to test the software | ||
|
||
If the software includes automated tests, detail how to run those tests. | ||
class BookModelAdmin(TreeModelAdmin): | ||
model = Book | ||
parent_field = 'author' | ||
|
||
## Known issues | ||
|
||
Document any known significant shortcomings with the software. | ||
@modeladmin_register | ||
class AuthorModelAdmin(TreeModelAdmin): | ||
menu_label = 'Library' | ||
menu_icon = 'list-ul' | ||
model = Author | ||
child_field = 'book_set' | ||
child_model_admin = BookModelAdmin | ||
``` | ||
|
||
## Getting help | ||
Then visit the Wagtail admin. `Library` will be in the menu, and will give you a list of authors, and each author will have a link that will take to their books. | ||
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. Typo? "that will take [you] to their books". |
||
|
||
Instruct users how to get help with this software; this might include links to an issue tracker, wiki, mailing list, etc. | ||
## API | ||
|
||
**Example** | ||
Wagtail-TreeModelAdmin uses three new attributes on ModelAdmin subclasses to express parent/child relationships: | ||
|
||
If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker. | ||
- `parent_field`: The name of the Django [`ForeignKey`](https://docs.djangoproject.com/en/2.0/ref/models/fields/#django.db.models.ForeignKey) on a child model. | ||
- `child_field`: The [`related_name`](https://docs.djangoproject.com/en/2.0/ref/models/fields/#django.db.models.ForeignKey.related_name) on a Django `ForeignKey`. | ||
- `child_model_admin` | ||
|
||
## Getting involved | ||
Any `TreeModelAdmin` subclass can specify both parent and child relationships. The root of the tree (either the `TreeModelAdmin` included in a `ModelAdminGroup` or the `@modeladmin_register`ed `TreeModelAdmin` subclass) should only include `child_*` fields. | ||
|
||
This section should detail why people should get involved and describe key areas you are | ||
currently focusing on; e.g., trying to get feedback on features, fixing certain bugs, building | ||
important pieces, etc. | ||
## Getting help | ||
|
||
General instructions on _how_ to contribute should be stated with a link to [CONTRIBUTING](CONTRIBUTING.md). | ||
Please add issues to the [issue tracker](https://github.com/cfpb/wagtail-treemodeladmin/issues). | ||
|
||
## Getting involved | ||
|
||
---- | ||
General instructions on _how_ to contribute can be found in [CONTRIBUTING](CONTRIBUTING.md). | ||
|
||
## Open source licensing info | ||
## Licensing | ||
1. [TERMS](TERMS.md) | ||
2. [LICENSE](LICENSE) | ||
3. [CFPB Source Code Policy](https://github.com/cfpb/source-code-policy/) | ||
|
||
|
||
---- | ||
|
||
## Credits and references | ||
|
||
1. Projects that inspired you | ||
2. Related projects | ||
3. Books, papers, talks, or other sources that have meaningful impact or influence on this project | ||
1. Forked from [cfgov-refresh](https://github.com/cfpb/cfgov-refresh) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,53 @@ | ||
from setuptools import find_packages, setup | ||
|
||
try: | ||
import pypandoc | ||
long_description = pypandoc.convert('README.md', 'rst') | ||
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. Is this conversion to RST still necessary now that PyPI properly supports Markdown READMEs? 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. Probably not. I'd like to do some experimentation though, considering that the Markdown support didn't work with the latest release of wagtail-flags. |
||
except (IOError, ImportError): | ||
long_description = open('README.md', 'r').read() | ||
|
||
|
||
install_requires = [ | ||
'Django>=1.8,<2.1', | ||
'wagtail>=1.10,<2.1', | ||
] | ||
|
||
|
||
testing_extras = [ | ||
'mock>=2.0.0', | ||
'coverage>=3.7.0', | ||
] | ||
|
||
|
||
setup( | ||
name='wagtail-treemodeladmin', | ||
url='https://github.com/cfpb/wagtail-treemodeladmin', | ||
author='CFPB', | ||
author_email='tech@cfpb.gov', | ||
description='TreeModelAdmin for Wagtail', | ||
long_description=long_description, | ||
license='CC0', | ||
version='0.1.0', | ||
include_package_data=True, | ||
packages=find_packages(), | ||
install_requires=install_requires, | ||
extras_require={ | ||
'testing': testing_extras, | ||
}, | ||
classifiers=[ | ||
'Framework :: Django', | ||
'Framework :: Django :: 1.11', | ||
'Framework :: Django :: 1.8', | ||
'Framework :: Django :: 2.0', | ||
'Framework :: Wagtail', | ||
'Framework :: Wagtail :: 1', | ||
'Framework :: Wagtail :: 2', | ||
'License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication', | ||
'License :: Public Domain', | ||
'Programming Language :: Python', | ||
'Programming Language :: Python :: 2', | ||
'Programming Language :: Python :: 2.7', | ||
'Programming Language :: Python :: 3', | ||
'Programming Language :: Python :: 3.6', | ||
] | ||
) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,60 @@ | ||
[tox] | ||
skipsdist=True | ||
envlist= | ||
lint, | ||
py{27,36}-dj{18,111}-wag{113}, | ||
py{36}-dj{20}-wag{20} | ||
|
||
[testenv] | ||
install_command=pip install -e ".[testing]" -U {opts} {packages} | ||
commands= | ||
coverage erase | ||
coverage run --source='treemodeladmin' {envbindir}/django-admin.py test {posargs} | ||
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. How would you feel about adding a third 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. I actually like this idea a lot. I'll do it! |
||
setenv= | ||
DJANGO_SETTINGS_MODULE=treemodeladmin.tests.settings | ||
|
||
basepython= | ||
py27: python2.7 | ||
py36: python3.6 | ||
|
||
deps= | ||
dj18: Django>=1.8,<1.9 | ||
dj111: Django>=1.11,<1.12 | ||
dj20: Django>=2.0,<2.1 | ||
wag113: wagtail>=1.13,<1.14 | ||
wag20: wagtail>=2.0,<2.1 | ||
|
||
[testenv:lint] | ||
basepython=python3.6 | ||
deps= | ||
flake8>=2.2.0 | ||
isort>=4.2.15 | ||
commands= | ||
flake8 . | ||
isort --check-only --diff --recursive treemodeladmin | ||
|
||
[flake8] | ||
ignore=E731,W503 | ||
exclude= | ||
.tox, | ||
__pycache__, | ||
treemodeladmin/migrations/*, | ||
treemodeladmin/tests/treemodeladmintest/migrations/* | ||
|
||
[isort] | ||
combine_as_imports=1 | ||
lines_after_imports=2 | ||
include_trailing_comma=1 | ||
multi_line_output=3 | ||
skip=.tox,migrations | ||
not_skip=__init__.py | ||
use_parentheses=1 | ||
known_django=django | ||
known_wagtail=wagtail | ||
known_future_library=future,six | ||
default_section=THIRDPARTY | ||
sections=FUTURE,STDLIB,DJANGO,WAGTAIL,THIRDPARTY,FIRSTPARTY,LOCALFOLDER | ||
|
||
[coverage:run] | ||
omit = | ||
treemodeladmin/tests/* |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
default_app_config = 'treemodeladmin.apps.WagtailTreeModelAdminAppConfig' |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
from django.apps import AppConfig | ||
from django.utils.translation import ugettext_lazy as _ | ||
|
||
|
||
class WagtailTreeModelAdminAppConfig(AppConfig): | ||
name = 'treemodeladmin' | ||
label = 'wagtailtreemodeladmin' | ||
verbose_name = _("Wagtail TreeModelAdmin") |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
from wagtail.contrib.modeladmin.helpers import ButtonHelper | ||
|
||
|
||
class TreeButtonHelper(ButtonHelper): | ||
|
||
def add_button(self, classnames_add=None, classnames_exclude=None): | ||
return super(TreeButtonHelper, self).add_button( | ||
classnames_add=['button-small'] | ||
) |
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.
Link to ModelAdmin docs?