Move custom user forms example to a new page under advanced_topics/customisation

docs/advanced_topics/customisation/custom_user_models.rst

@@ -0,0 +1,90 @@
+Custom user models
+==================
+
+Custom user forms example
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example shows how to add a text field and foreign key field to a custom user model
+and configure Wagtail user forms to allow the fields values to be updated.
+
+Create a custom user model. In this case we extend the ``AbstractUser`` class and add
+two fields. The foreign key references another model (not shown).
+
+.. code-block:: python
+
+  class User(AbstractUser):
+      country = models.CharField(verbose_name='country', max_length=255)
+      status = models.ForeignKey(MembershipStatus, on_delete=models.SET_NULL, null=True, default=1)
+
+Add the app containing your user model to ``INSTALLED_APPS`` and set AUTH_USER_MODEL_ to reference
+your model. In this example the app is called ``users`` and the model is ``User``
+
+.. code-block:: python
+
+  AUTH_USER_MODEL = 'users.User'
+
+Create your custom user create and edit forms in your app:
+
+.. code-block:: python
+
+  from django import forms
+  from django.utils.translation import ugettext_lazy as _
+
+  from wagtail.wagtailusers.forms import UserEditForm, UserCreationForm
+
+  from users.models import MembershipStatus
+
+
+  class CustomUserEditForm(UserEditForm):
+      country = forms.CharField(required=True, label=_("Country"))
+      status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
+
+
+  class CustomUserCreationForm(UserCreationForm):
+      country = forms.CharField(required=True, label=_("Country"))
+      status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
+
+
+Extend the Wagtail user create and edit templates. These extended template should be placed in a
+template directory ``wagtailusers/users``.
+
+Template create.html:
+
+.. code-block:: html+django
+
+  {% extends "wagtailusers/users/create.html" %}
+
+  {% block extra_fields %}
+      {% include "wagtailadmin/shared/field_as_li.html" with field=form.country %}
+      {% include "wagtailadmin/shared/field_as_li.html" with field=form.status %}
+  {% endblock extra_fields %}
+
+.. note::
+   Using ``{% extends %}`` in this way on a template you're currently overriding is only supported in Django 1.9 and above. On Django 1.8, you will need to use `django-overextends <https://github.com/stephenmcd/django-overextends>`_ instead.
+
+Template edit.html:
+
+.. code-block:: html+django
+
+  {% extends "wagtailusers/users/edit.html" %}
+
+  {% block extra_fields %}
+      {% include "wagtailadmin/shared/field_as_li.html" with field=form.country %}
+      {% include "wagtailadmin/shared/field_as_li.html" with field=form.status %}
+  {% endblock extra_fields %}
+
+The ``extra_fields`` block allows fields to be inserted below the last name field
+in the default templates. Other block overriding options exist to allow appending
+fields to the end or beginning of the existing fields, or to allow all the fields to
+be redefined.
+
+Add the wagtail settings to your project to reference the user form additions:
+
+.. code-block:: python
+
+  WAGTAIL_USER_EDIT_FORM = 'users.forms.CustomUserEditForm'
+  WAGTAIL_USER_CREATION_FORM = 'users.forms.CustomUserCreationForm'
+  WAGTAIL_USER_CUSTOM_FIELDS = ['country', 'status']
+
+
+.. _AUTH_USER_MODEL: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#substituting-a-custom-user-model

docs/advanced_topics/customisation/index.rst

@@ -7,3 +7,4 @@ Customising Wagtail
 
     page_editing_interface
     branding
+    custom_user_models

docs/advanced_topics/settings.rst

@@ -300,6 +300,8 @@ Tags are case-sensitive by default ('music' and 'Music' are treated as distinct
 Custom User Edit Forms
 ----------------------
 
+See :doc:`/advanced_topics/customisation/custom_user_models`.
+
 .. code-block:: python
 
   WAGTAIL_USER_EDIT_FORM = 'users.forms.CustomUserEditForm'
@@ -320,90 +322,6 @@ a custom user model is being used and extra fields are required in the user crea
 
 A list of the extra custom fields to be appended to the default list.
 
-Custom user forms example
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This example shows how to add a text field and foreign key field to a custom user model
-and configure Wagtail user forms to allow the fields values to be updated.
-
-Create a custom user model. In this case we extend the ``AbstractUser`` class and add
-two fields. The foreign key references another model (not shown).
-
-.. code-block:: python
-
-  class User(AbstractUser):
-      country = models.CharField(verbose_name='country', max_length=255)
-      status = models.ForeignKey(MembershipStatus, on_delete=models.SET_NULL, null=True, default=1)
-
-Add the app containing your user model to ``INSTALLED_APPS`` and set AUTH_USER_MODEL_ to reference
-your model. In this example the app is called ``users`` and the model is ``User``
-
-.. code-block:: python
-
-  AUTH_USER_MODEL = 'users.User'
-
-Create your custom user create and edit forms in your app:
-
-.. code-block:: python
-
-  from django import forms
-  from django.utils.translation import ugettext_lazy as _
-
-  from wagtail.wagtailusers.forms import UserEditForm, UserCreationForm
-
-  from users.models import MembershipStatus
-
-
-  class CustomUserEditForm(UserEditForm):
-      country = forms.CharField(required=True, label=_("Country"))
-      status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
-
-
-  class CustomUserCreationForm(UserCreationForm):
-      country = forms.CharField(required=True, label=_("Country"))
-      status = forms.ModelChoiceField(queryset=MembershipStatus.objects, required=True, label=_("Status"))
-
-
-Extend the Wagtail user create and edit templates. These extended template should be placed in a
-template directory ``wagtailusers/users``.
-
-Template create.html:
-
-.. code-block:: python
-
-  {% extends "wagtailusers/users/create.html" %}
-
-  {% block extra_fields %}
-      {% include "wagtailadmin/shared/field_as_li.html" with field=form.country %}
-      {% include "wagtailadmin/shared/field_as_li.html" with field=form.status %}
-  {% endblock extra_fields %}
-
-Template edit.html:
-
-.. code-block:: python
-
-  {% extends "wagtailusers/users/edit.html" %}
-
-  {% block extra_fields %}
-      {% include "wagtailadmin/shared/field_as_li.html" with field=form.country %}
-      {% include "wagtailadmin/shared/field_as_li.html" with field=form.status %}
-  {% endblock extra_fields %}
-
-The ``extra_fields`` block allows fields to be inserted below the last name field
-in the default templates. Other block overriding options exist to allow appending
-fields to the end or beginning of the existing fields, or to allow all the fields to
-be redefined.
-
-Add the wagtail settings to your project to reference the user form additions:
-
-.. code-block:: python
-
-  WAGTAIL_USER_EDIT_FORM = 'users.forms.CustomUserEditForm'
-  WAGTAIL_USER_CREATION_FORM = 'users.forms.CustomUserCreationForm'
-  WAGTAIL_USER_CUSTOM_FIELDS = ['country', 'status']
-
-
-.. _AUTH_USER_MODEL: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#substituting-a-custom-user-model
 
 URL Patterns
 ~~~~~~~~~~~~