Added apphook topic (#6047)

Also:

* fixed minor typos
* fixed incorrect "Unreleased" heading for 3.1.4
* reordered topic sections

docs/how_to/apphooks.rst

@@ -66,7 +66,7 @@ If you fail to this, then any templates in the application that invoke URLs usin
 or views that call (for example) ``reverse('myapp:index')`` will throw a ``NoReverseMatch`` error.
 
 *Unless* the class that defines the apphook specifies an ``app_name``, it can be attached only to one page at a time.
-Attempting to apply it a second times will cause an error. See :ref:`multi_apphook` for more on having multiple apphook
+Attempting to apply it a second time will cause an error. See :ref:`multi_apphook` for more on having multiple apphook
 instances.
 
 

docs/topics/apphooks.rst

@@ -0,0 +1,60 @@
+.. _about_apphooks:
+
+##############################
+Application hooks ("apphooks")
+##############################
+
+An Application Hook, usually simply referred to as an apphook, is a way of attaching
+the functionality of some other application to a django CMS page. It's a convenient way
+of integrating other applications into a django CMS site.
+
+For example, suppose you have an application that maintains and publishes information
+about Olympic records. You could add this application to your site's ``urls.py`` (before
+the django CMS URLs pattern), so that users will find it at ``/records``.
+
+However, although it would thus be integrated into your *project*, it would not be
+fully integrated into django CMS, for example:
+
+* django CMS would not be aware of it, and - for example - would allow your users to create a CMS page with the same
+  ``/records`` slug, that could never be reached.
+* The application's pages won't automatically appear in your site's menus.
+* The application's pages won't be able to take advantage of the CMS's publishing
+  workflow, permissions or other functionality.
+
+Apphooks offer a more complete way of integrating other applications, by attaching them
+to a CMS page. In this case, the attached application takes over the page and its URL
+(and all the URLs below it, such as ``/records/1984``).
+
+The application can be served at a URL defined by the content managers, and easily moved
+around in the site structure.
+
+The *Advanced settings* of a CMS page provides an *Application* field. :ref:`Adding an apphook class <apphooks_how_to>` to the
+application will allow it to be selected in this field.
+
+
+*********************************
+Multiple apphooks per application
+*********************************
+
+It's possible for an application to be added multiple times, to different pages. See :ref:`multi_apphook` for more.
+
+Also possible to provide **multiple apphook configurations**:
+
+
+**********************
+Apphook configurations
+**********************
+
+You may require the same application to behave differently in different locations on your site. For example, the Olympic
+Records application may be required to publish athletics results at one location, but cycling results at another, and so on.
+
+An :ref:`apphook configuration <apphook_configurations>` class allows the site editors to create multiple configuration
+instances that specify the behaviour. The kind of configuration available is presented in an admin form, and determined by the
+application developer.
+
+..  important:
+
+    It's important to understand that an apphook (and therefore also an apphook configuration) serves no function until it is
+    attached to a page - and until the page is **published**, the application will be unable to fulfil any publishing function.
+
+

docs/topics/index.rst

@@ -11,11 +11,12 @@ concerned with explaining *how to do things* than with helping you understand
 .. toctree::
     :maxdepth: 1
 
-    touch
-    menu_system
+    apphooks
     publishing
     multiple_languages
     i18n
     permissions
+    touch
+    menu_system
     commonly_used_plugins
     searchdocs

docs/upgrade/3.1.4.rst

@@ -1,8 +1,8 @@
 .. _upgrade-to-3.1.4:
 
-########################################
-3.1.4 release notes - Unreleased - Draft
-########################################
+###################
+3.1.4 release notes
+###################
 
 *******************
 What's new in 3.1.4