Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

add docs for mptt.register

  • Loading branch information...
commit 348a4b2aafc2bd7692ca18802f7d44a681e48644 1 parent 56c8f09
@craigds craigds authored
Showing with 40 additions and 18 deletions.
  1. +17 −0 docs/models.txt
  2. +23 −18 docs/upgrade.txt
View
17 docs/models.txt
@@ -105,6 +105,23 @@ exist, they will be added to the model dynamically:
as trees of categories, which should always be in alphabetical order.
+Registration of existing models
+===============================
+
+The preferred way to do model registration in ``django-mptt`` 0.4 is by subclassing ``MPTTModel``.
+
+However, sometimes that doesn't quite work. For instance, suppose you want to modify Django's Group model to be hierarchical.
+
+You can't subclass MPTTModel without modifying the Group source. Instead, you can do::
+
+ import mptt
+ from django.contrib.auth.models import Group
+
+ mptt.register(Group, order_insertion_by=['name'])
+
+``mptt.register()`` was removed in 0.4.0 but restored in 0.4.2, when this use case was reported.
+
+
MPTTModel instance methods
==========================
View
41 docs/upgrade.txt
@@ -6,12 +6,28 @@ Upgrade Notes - 0.3 to 0.4
Model changes in 0.4
====================
-``mptt.register`` replaced by ``MPTTModel``
--------------------------------------------
+MPTT attributes on ``MyModel._meta`` deprecated, moved to ``MyModel._mptt_meta``
+----------------------------------------------------------------------------------
+
+Most people won't need to worry about this, but if you're using any of the following, note that these are deprecated and will be removed in 0.5::
+
+ MyModel._meta.left_attr
+ MyModel._meta.right_attr
+ MyModel._meta.tree_id_attr
+ MyModel._meta.level_attr
+ MyModel._meta.tree_manager_attr
+ MyModel._meta.parent_attr
+ MyModel._meta.order_insertion_by
+
+They'll continue to work as previously for now, but you should upgrade your code if you can. Simply replace ``_meta`` with ``_mptt_meta``.
+
-In ``django-mptt`` 0.4, mptt.register() has been removed in favour of model inheritance.
+Use model inheritance where possible
+------------------------------------
-Suppose you start with this, which works with ``django-mptt`` 0.3::
+The preferred way to do model registration in ``django-mptt`` 0.4 is via model inheritance.
+
+Suppose you start with this::
class Node(models.Model):
...
@@ -34,21 +50,10 @@ Then remove your call to ``mptt.register()``. If you were passing it keyword arg
order_insertion_by = ['name']
parent_attr = 'padre'
-MPTT attributes on ``MyModel._meta`` deprecated, moved to ``MyModel._mptt_meta``
-----------------------------------------------------------------------------------
-
-Most people won't need to worry about this, but if you're using any of the following, note that these are deprecated and will be removed in 0.5::
-
- MyModel._meta.left_attr
- MyModel._meta.right_attr
- MyModel._meta.tree_id_attr
- MyModel._meta.level_attr
- MyModel._meta.tree_manager_attr
- MyModel._meta.parent_attr
- MyModel._meta.order_insertion_by
-
-They'll continue to work as previously for now, but you should upgrade your code if you can. Simply replace ``_meta`` with ``_mptt_meta``.
+If necessary you can still use ``mptt.register``. It was removed in 0.4.0 but restored in 0.4.2, since people reported use cases that didn't work without it.)
+For instance, if you need to register models where the code isn't under your control, you'll need to use ``mptt.register``.
+It may also come in handy for keeping libraries compatible with ``django-mptt`` 0.3.
You're probably all upgraded at this point :) A couple more notes for more complex scenarios:
Please sign in to comment.
Something went wrong with that request. Please try again.