Updated documentation formatting and information for 1.4 release.
Brandon Taylor
parent
cffbd8534e
commit
ac2cecf291
128
README.md
128
README.md
|
|
@ -1,22 +1,39 @@
|
|||
admin-sortable
|
||||
=============
|
||||
# Django Admin Sortable
|
||||
|
||||
What is it?
|
||||
=============
|
||||
The adminsortable app adds generic drag-and-drop facilities
|
||||
to any Django model class or Inlines via Django Admin and jQueryUI.
|
||||
This project makes it easy to add drag-and-drop ordering to any model in
|
||||
Django admin. Inlines for a sortable model may also be made sortable,
|
||||
enabling individual items or groups of items to be sortable.
|
||||
|
||||
Installation
|
||||
=============
|
||||
1. Run ``setup.py`` or add ``adminsortable`` to your PYTHONPATH.
|
||||
2. Copy the ``adminsortable`` folder from the static folder to the
|
||||
location you server static files from, or if you're using the StaticFiles app
|
||||
https://docs.djangoproject.com/en/1.3/ref/contrib/staticfiles/,
|
||||
run: $ python manage.py collectstatic to move the files to the location
|
||||
you've specified for static files.
|
||||
3. Add ``adminsortable`` to your INSTALLED_APPS.
|
||||
4. Ensure "django.core.context_processors.static" is in your TEMPLATE_CONTEXT_PROCESSORS.
|
||||
5. Have a look at the included sample_project to see working examples.
|
||||
## Requirements
|
||||
jQuery
|
||||
|
||||
|
||||
## Installation
|
||||
1. pip install django-admin-sortable
|
||||
|
||||
--or--
|
||||
|
||||
Download django-admin-sortable from [source](https://github.com/iambrandontaylor/django-admin-sortable/archive/master.zip)
|
||||
|
||||
1. Unzip the directory and cd into the uncompressed project directory
|
||||
2. *Optional: Enable your virtualenv
|
||||
3. Run `$ python setup.py install` or add `adminsortable` to your PYTHONPATH.
|
||||
|
||||
|
||||
## Configuration
|
||||
1. Add `adminsortable` to your `INSTALLED_APPS`.
|
||||
2. Ensure `django.core.context_processors.static` is in your `TEMPLATE_CONTEXT_PROCESSORS`.
|
||||
|
||||
### Static Media
|
||||
Preferred:
|
||||
Use the [staticfiles app](https://docs.djangoproject.com/en/1.4/ref/contrib/staticfiles/)
|
||||
|
||||
Alternate:
|
||||
Copy the `adminsortable` folder from the `static` folder to the
|
||||
location you server static files from.
|
||||
|
||||
### Testing
|
||||
Have a look at the included sample_project to see working examples.
|
||||
The login credentials for admin are: admin/admin
|
||||
|
||||
When a model is sortable, a tool-area link will be added that says "Change Order".
|
||||
|
|
@ -25,19 +42,19 @@ the records into order.
|
|||
|
||||
Tabular inlines may be drag-and-dropped into any order directly from the change form.
|
||||
|
||||
Usage
|
||||
=============
|
||||
Models
|
||||
----------------------
|
||||
To add sorting to a model, your model needs to inherit from ``Sortable`` and
|
||||
have an inner Meta class that inherits from ``Sortable.Meta``
|
||||
|
||||
## Usage
|
||||
|
||||
### Models
|
||||
To add sorting to a model, your model needs to inherit from `Sortable` and
|
||||
have an inner Meta class that inherits from `Sortable.Meta`
|
||||
|
||||
#models.py
|
||||
from adminsortable.models import Sortable
|
||||
|
||||
class MySortableClass(Sortable):
|
||||
class Meta(Sortable.Meta):
|
||||
pass
|
||||
pass
|
||||
|
||||
title = models.CharField(max_length=50)
|
||||
|
||||
|
|
@ -57,7 +74,7 @@ even if that model does not inherit from Sortable:
|
|||
|
||||
class Project(Sortable):
|
||||
class Meta(Sortable.Meta):
|
||||
pass
|
||||
pass
|
||||
|
||||
category = SortableForeignKey(Category)
|
||||
title = models.CharField(max_length=50)
|
||||
|
|
@ -68,14 +85,12 @@ even if that model does not inherit from Sortable:
|
|||
|
||||
Sortable has one field: `order` and adds a default ordering value set to `order`.
|
||||
|
||||
South
|
||||
------
|
||||
If you're adding Sorting to an existing model, it is recommended that you use django-south,
|
||||
http://south.areacode.com/ to create a migration to add the "order" field to your model.
|
||||
### South
|
||||
If you're adding Sorting to an existing model, it is recommended that you use [django-south](http://south.areacode.com/) to create a migration to add the "order" field to your model.
|
||||
|
||||
|
||||
*Django Admin Usage*
|
||||
To enable sorting in the admin, you need to inherit from SortableAdmin:
|
||||
### Django Admin
|
||||
To enable sorting in the admin, you need to inherit from `SortableAdmin`:
|
||||
|
||||
from django.contrib import admin
|
||||
from myapp.models import MySortableClass
|
||||
|
|
@ -104,7 +119,7 @@ SortableStackedInline:
|
|||
class MySortableStackedInline(SortableStackedInline):
|
||||
"""Your inline options go here"""
|
||||
|
||||
!!! *IMPORTANT* !!!
|
||||
*** IMPORTANT ***
|
||||
With stacked inline models, their height can dynamically increase,
|
||||
which can cause sortable stacked inlines to not behave as expected.
|
||||
If the height of the stacked inline is going to be very tall, I would
|
||||
|
|
@ -112,8 +127,7 @@ suggest NOT using SortableStackedInline. I'm currently working on
|
|||
a way to make this more usable.
|
||||
|
||||
|
||||
Potential Gotcha
|
||||
=============
|
||||
### Potential Gotcha
|
||||
|
||||
If you have an existing model that you're now making Sortable, existing
|
||||
rows won't have an "order" attribute. Django-admin-sortable depends on
|
||||
|
|
@ -123,16 +137,15 @@ A good rule of thumb if you're adding django-admin-sortable to an existing
|
|||
project is to create a Data Migration using South to set the "order" column
|
||||
according to your needs.
|
||||
|
||||
For example, if you have a SortableForeignKey field, you would need to set
|
||||
For example, if you have a `SortableForeignKey` field, you would need to set
|
||||
the "order" column relative to that field, instead of setting the "order"
|
||||
column in linear succession.
|
||||
|
||||
See: http://south.readthedocs.org/en/latest/tutorial/part3.html for more
|
||||
See: [this link](http://south.readthedocs.org/en/latest/tutorial/part3.html) for more
|
||||
information on Data Migrations.
|
||||
|
||||
|
||||
Rationale
|
||||
=============
|
||||
### Rationale
|
||||
Other projects have added drag-and-drop ordering to the ChangeList
|
||||
view, however this introduces a couple of problems...
|
||||
|
||||
|
|
@ -145,41 +158,20 @@ impossible.
|
|||
- The ChangeList supports in-line editing, and adding drag-and-drop
|
||||
ordering on top of that just seemed a little much in my opinion.
|
||||
|
||||
Status
|
||||
=============
|
||||
admin-sortable is currently used in production.
|
||||
### Status
|
||||
django-admin-sortable is currently used in production.
|
||||
|
||||
|
||||
What's new in 1.3.8?
|
||||
=============
|
||||
- CSS fixes for tabular inlines courtesty of @ionelmc: https://github.com/ionelmc
|
||||
- Updated documentation
|
||||
### What's new in 1.4?
|
||||
- Django 1.5 compatibility
|
||||
|
||||
Features
|
||||
=============
|
||||
Current
|
||||
---------
|
||||
- Supports Django 1.4+
|
||||
- Adds an admin view to any model that inherits from Sortable and SortableAdmin
|
||||
that allows you to drag and drop objects into any order via jQueryUI.
|
||||
- Adds drag and drop ordering to Tabular and Stacked Inline models that inherit from
|
||||
SortableTabularInline and SortableStackedInline
|
||||
- Allows ordering of objects that are sorted on a Foreign Key, and adds ordering
|
||||
to the foreign key object if it also inherits from Sortable.
|
||||
- Supports non-integer primary keys.
|
||||
|
||||
Future
|
||||
------
|
||||
### Future
|
||||
- Support for foreign keys that are self referential
|
||||
- More unit tests
|
||||
- Move unit tests out of sample project
|
||||
- Travis CI integration
|
||||
|
||||
Requirements
|
||||
=============
|
||||
Sample Project
|
||||
----------------
|
||||
Requires django-appmedia, included
|
||||
|
||||
License
|
||||
=============
|
||||
The admin-sortable app is released
|
||||
under the Apache Public License v2.
|
||||
### License
|
||||
django-admin-sortable is released under the Apache Public License v2.
|
||||
|
|
|
|||
Loading…
Reference in New Issue