From 2f8a43cd66c88eca1f329700da12ce4ab945a0ed Mon Sep 17 00:00:00 2001 From: Tim Heap Date: Mon, 28 Nov 2016 11:45:01 +1100 Subject: [PATCH] Document new blocks in login template The old `branding.rst` docs were combined with the new docs on customising the login page in a new `admin_templates.rst` document. --- CHANGELOG.txt | 1 + .../{branding.rst => admin_templates.rst} | 91 ++++++++++++++++--- docs/advanced_topics/customisation/index.rst | 2 +- docs/releases/1.8.rst | 3 +- 4 files changed, 82 insertions(+), 15 deletions(-) rename docs/advanced_topics/customisation/{branding.rst => admin_templates.rst} (54%) diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 2726ea812..03a41fffb 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -17,6 +17,7 @@ Changelog * Added new StreamField block type `StaticBlock` (Benoît Vogel) * Updated Cloudflare cache module to use the v4 API (Albert O'Connor) * Added `exclude_from_explorer` attribute to the `ModelAdmin` class to allow hiding instances of a page type from Wagtail's explorer views (Andy Babic) + * Added `above_login`, `below_login`, `fields` and `login_form` customisation blocks to the login page template (Tim Heap) * Fix: `AbstractForm` now respects custom `get_template` methods on the page model (Gagaro) * Fix: Use specific page model for the parent page in the explore index (Gagaro) * Fix: Remove responsive styles in embed when there is no ratio available (Gagaro) diff --git a/docs/advanced_topics/customisation/branding.rst b/docs/advanced_topics/customisation/admin_templates.rst similarity index 54% rename from docs/advanced_topics/customisation/branding.rst rename to docs/advanced_topics/customisation/admin_templates.rst index ddd950379..beb8adf42 100644 --- a/docs/advanced_topics/customisation/branding.rst +++ b/docs/advanced_topics/customisation/admin_templates.rst @@ -1,36 +1,44 @@ -.. _custom_branding: - -Custom branding -=============== +=========================== +Customising admin templates +=========================== In your projects with Wagtail, you may wish to replace elements such as the Wagtail logo within the admin interface with your own branding. This can be done through Django's template inheritance mechanism. .. 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 `_ instead. -You need to create a ``templates/wagtailadmin/`` folder within one of your apps - this may be an existing one, or a new one created for this purpose, for example, ``dashboard``. This app must be registered in ``INSTALLED_APPS`` before ``wagtail.wagtailadmin``:: +You need to create a ``templates/wagtailadmin/`` folder within one of your apps - this may be an existing one, or a new one created for this purpose, for example, ``dashboard``. This app must be registered in ``INSTALLED_APPS`` before ``wagtail.wagtailadmin``: + +.. code-block:: python INSTALLED_APPS = ( # ... 'dashboard', - + 'wagtail.wagtailcore', 'wagtail.wagtailadmin', - + # ... ) -The template blocks that are available to be overridden are as follows: +.. _custom_branding: + +Custom branding +=============== + +The template blocks that are available to customise the branding in the admin interface are as follows: ``branding_logo`` ----------------- -To replace the default logo, create a template file ``dashboard/templates/wagtailadmin/base.html`` that overrides the block ``branding_logo``:: +To replace the default logo, create a template file ``dashboard/templates/wagtailadmin/base.html`` that overrides the block ``branding_logo``: + +.. code-block:: html+django {% extends "wagtailadmin/base.html" %} {% load staticfiles %} - + {% block branding_logo %} Custom Project {% endblock %} @@ -38,7 +46,9 @@ To replace the default logo, create a template file ``dashboard/templates/wagtai ``branding_favicon`` -------------------- -To replace the favicon displayed when viewing admin pages, create a template file ``dashboard/templates/wagtailadmin/admin_base.html`` that overrides the block ``branding_favicon``:: +To replace the favicon displayed when viewing admin pages, create a template file ``dashboard/templates/wagtailadmin/admin_base.html`` that overrides the block ``branding_favicon``: + +.. code-block:: html+django {% extends "wagtailadmin/admin_base.html" %} {% load staticfiles %} @@ -50,7 +60,9 @@ To replace the favicon displayed when viewing admin pages, create a template fil ``branding_login`` ------------------ -To replace the login message, create a template file ``dashboard/templates/wagtailadmin/login.html`` that overrides the block ``branding_login``:: +To replace the login message, create a template file ``dashboard/templates/wagtailadmin/login.html`` that overrides the block ``branding_login``: + +.. code-block:: html+django {% extends "wagtailadmin/login.html" %} @@ -59,8 +71,61 @@ To replace the login message, create a template file ``dashboard/templates/wagta ``branding_welcome`` -------------------- -To replace the welcome message on the dashboard, create a template file ``dashboard/templates/wagtailadmin/home.html`` that overrides the block ``branding_welcome``:: +To replace the welcome message on the dashboard, create a template file ``dashboard/templates/wagtailadmin/home.html`` that overrides the block ``branding_welcome``: + +.. code-block:: html+django {% extends "wagtailadmin/home.html" %} {% block branding_welcome %}Welcome to Frank's Site{% endblock %} + +Extending the login form +======================== + +To add extra controls to the login form, create a template file ``dashboard/templates/wagtailadmin/login.html``. + +``above_login`` and ``below_login`` +----------------------------------- + +To add content above or below the login form, override these blocks: + +.. code-block:: html+django + + {% extends "wagtailadmin/login.html" %} + + {% block above_login %} If you are not Frank you should not be here! {% endblock %} + +``fields`` +---------- + +To add extra fields to the login form, override the ``fields`` block. You will need to add ``{{ block.super }}`` somewhere in your block to include the username and password fields: + +.. code-block:: html+django + + {% extends "wagtailadmin/login.html" %} + + {% block fields %} + {{ block.super }} +
  • +
    + Two factor auth token +
    + +
    +
    +
    • + {% endblock %} + +``login_form`` +-------------- + +To completely customise the login form, override the ``login_form`` block. This block wraps the whole contents of the ``
    `` element: + +.. code-block:: html+django + + {% extends "wagtailadmin/login.html" %} + + {% block login_form %} +

    Some extra form content

    + {{ block.super }} + {% endblock %} diff --git a/docs/advanced_topics/customisation/index.rst b/docs/advanced_topics/customisation/index.rst index d02f6b18e..58fc3bd2a 100644 --- a/docs/advanced_topics/customisation/index.rst +++ b/docs/advanced_topics/customisation/index.rst @@ -6,5 +6,5 @@ Customising Wagtail :maxdepth: 2 page_editing_interface - branding + admin_templates custom_user_models diff --git a/docs/releases/1.8.rst b/docs/releases/1.8.rst index 834cedb85..cf5a390c6 100644 --- a/docs/releases/1.8.rst +++ b/docs/releases/1.8.rst @@ -42,7 +42,8 @@ Minor features * Modeladmin forms now respect ``fields`` / ``exclude`` options passed on custom model forms (Thejaswi Puthraya) * Added new StreamField block type ``StaticBlock`` for blocks that occupy a position in a stream but otherwise have no configuration; see :ref:`streamfield_staticblock` (Benoît Vogel) * Updated Cloudflare cache module to use the v4 API (Albert O'Connor) - * Added `exclude_from_explorer` attribute to the `ModelAdmin` class to allow hiding instances of a page type from Wagtail's explorer views (Andy Babic) + * Added ``exclude_from_explorer`` attribute to the ``ModelAdmin`` class to allow hiding instances of a page type from Wagtail's explorer views (Andy Babic) + * Added ``above_login``, ``below_login``, ``fields`` and ``login_form`` customisation blocks to the login page template - see :doc:`/advanced_topics/customisation/admin_templates` (Tim Heap) Bug fixes