Merge pull request #1 from cfpb/initial-work

Add initial version of wagtail-treemodeladmin

.gitattributes

@@ -1 +1,2 @@
+# Auto detect text files and perform LF normalization
 /CHANGELOG.md merge=union

.travis.yml

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

MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+global-include *.html

README.md

@@ -1,106 +1,121 @@
-#### 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](http://docs.wagtail.io/en/latest/reference/contrib/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` (and `wagtail.contrib.modeladmin` if it's not already) as an installed app in your Django `settings.py`:
 
-# 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 = (
+     ...
+     'wagtail.contrib.modeladmin',
+     '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 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)

setup.py

@@ -0,0 +1,51 @@
+from setuptools import find_packages, setup
+
+
+with open('README.md') as f:
+    long_description = f.read()
+
+
+install_requires = [
+    'Django>=1.8,<2.1',
+    'wagtail>=1.13,<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',
+    ]
+)

tox.ini

@@ -0,0 +1,61 @@
+[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}
+    coverage report -m
+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/*

treemodeladmin/__init__.py

@@ -0,0 +1 @@
+default_app_config = 'treemodeladmin.apps.WagtailTreeModelAdminAppConfig'

treemodeladmin/apps.py

@@ -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")

treemodeladmin/helpers.py

@@ -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']
+        )