Docs: Updates for dynamically loaded applications

The customisation section required some changes as it's not often
necessary to override the root application instance to change URLs or
views of subapps.

docs/source/howto/how_to_change_a_url.rst

@@ -11,13 +11,15 @@ It builds upon the steps described in :doc:`/topics/customisation`. Please
 read it first and ensure that you've:
 
 * Created a Python module with the the same label
-* Added it as Django app
+* Added it as Django app to ``INSTALLED_APPS``
+* Created a custom ``app.py``
 
 Example
 -------
 
-In order to customise Oscar's URLs, you need to use a custom app instance in
-your root ``urls.py`` instead of Oscar's default instance.  Hence, to use
+In order to customise Oscar's URLs, you need to use a custom app instance
+instead of Oscar's default instance.  ``/catalogue`` is wired up in the root
+application, so we need to replace that. Hence, to use
 ``catalog`` instead of ``catalogue``, create a subclass of Oscar's main
 ``Application`` class and override the ``get_urls`` method::
 
@@ -48,3 +50,16 @@ Now modify your root ``urls.py`` to use your new application instance::
     )
 
 All URLs containing ``catalogue`` previously are now displayed as ``catalog``.
+
+If you wanted to change URLs of a sub-app (e.g. ``/catalogue/category/``),
+you only need to replace the ``catalogue`` app. There's no need to change
+your ``urls.py`` or touch the root ``application`` instance. ``application``
+instances dynamically load their sub-apps, so it just pick up your replacement::
+
+    # oscar/app.py
+    class Shop(Application):
+        name = None
+
+        catalogue_app = get_class('catalogue.app', 'application')
+        customer_app = get_class('customer.app', 'application')
+        ...

docs/source/howto/how_to_customise_a_view.rst

@@ -7,7 +7,8 @@ your project.  It builds upon the steps described in
 :doc:`/topics/customisation`. Please read it first and ensure that you've:
 
 * Created a Python module with the the same label
-* Use custom root and local ``app.py``
+* Added it as Django app to ``INSTALLED_APPS``
+* Use custom ``app.py``
 
 Example
 -------

docs/source/howto/how_to_override_a_core_class.rst

@@ -11,7 +11,7 @@ It builds upon the steps described in :doc:`/topics/customisation`. Please
 read it first and ensure that you've:
 
 * Created a Python module with the the same label
-* Added it as Django app
+* Added it as Django app to ``INSTALLED_APPS``
 
 Example
 -------

docs/source/topics/customisation.rst

@@ -14,21 +14,19 @@ doesn't stop there. Almost every aspect of it can be altered.
 :doc:`Various techniques </internals/design-decisions>` are employed to achieve
 that level of adaptability.
 
-To extend the behavior of a Oscar core app, you will at least need to create an
+To extend the behavior of an Oscar core app, you will at least need to create an
 app with the same label. Depending on what should be adapted, different steps
 are necessary beyond that. The steps are detailed below; this overview might
 help you to figure out what needs to be done.
 
-==================================  ====================  ====================================  ========================
-Goals vs. necessary steps           Override model class  Override view class (or change URLs)  Override any other class
-==================================  ====================  ====================================  ========================
-Python module with same label       Necessary             Necessary                             Necessary
-Custom root and local ``app.py``    Not necessary         Necessary                             Not necessary
-Add as Django app                   Necessary             Not necessary                         Necessary
-==================================  ====================  ====================================  ========================
+================================  =============================  =================  =================
+Goals vs. necessary steps         Python module with same label  Add as Django app  Custom ``app.py``
+================================  =============================  =================  =================
+Override a model class            Necessary                      Necessary          Not necessary
+Override any other class or view  Necessary                      Necessary          Not necessary
+Change app URLs or add views      Necessary                      Necessary          Necessary
+================================  =============================  =================  =================
 
-If more complex changes are desired, it is usually easiest to do all of the
-steps.
 Please also refer to the following how-tos for further instructions and examples.
 
 * :doc:`/howto/how_to_customise_models`
@@ -47,16 +45,13 @@ E.g., to create a local version of ``oscar.apps.order``, do the following::
     $ touch yourproject/order/__init__.py
 
 
-Custom root and local ``app.py``
-================================
-
-Root ``app.py``
----------------
+Custom ``app.py``
+=================
 
 Oscar's views and URLs use a tree of 'app' instances, each of which subclass
 :class:`oscar.core.application.Application` and provide ``urls`` property.
-Oscar has a root app instance in ``oscar/app.py`` which can be imported into
-your ``urls.py``::
+Oscar has a root app instance in ``oscar/app.py`` which should already be
+wired up in your ``urls.py``::
 
     # urls.py
     from oscar.app import application
@@ -66,9 +61,12 @@ your ``urls.py``::
        (r'', include(application.urls)),
     )
 
-To get control over the mapping between URLs and views, you need to use a local
-``application`` instance, that (usually) subclasses Oscar's.  Hence, create
-``yourproject/app.py`` with contents::
+Modifying root app
+------------------
+
+If you want to change URLs or views of the root application above, you need to
+replace it with your own ``application`` instance, that (usually) subclasses
+Oscar's.  Hence, create ``yourproject/app.py`` with contents::
 
     # yourproject/app.py
     from oscar.app import Shop
@@ -89,34 +87,33 @@ Now hook this up in your ``urls.py`` instead::
         (r'', include(application.urls)),
     )
 
-This step only needs to be done once. All customisation will only entail
-overriding parts of the newly added ``BaseApplication``.
+Modifying sub-apps
+------------------
 
-Local ``app.py``
-----------------
+Sub-apps such as the ``catalogue`` app are loaded dynamically, just as most
+other classes in Oscar::
 
-If you want to modify a view or change a URL, you need to create an ``app.py``
-for your local app. It will usually inherit from Oscar's version::
+    # oscar/app.py
+    class Shop(Application):
+        name = None
 
-    # yourproject/order/app.py
+        catalogue_app = get_class('catalogue.app', 'application')
+        customer_app = get_class('customer.app', 'application')
+        ...
+
+That means you can leave the root app unchanged, and just need to create another
+``application`` instance. It will usually inherit from Oscar's version::
+
+    # yourproject/promotions/app.py
 
     from oscar.apps.promotions.app import PromotionsApplication as CorePromotionsApplication
+    from .views import MyExtraView
 
     class PromotionsApplication(CorePromotionsApplication):
-        pass
+        extra_view = MyExtraView
 
     application = PromotionsApplication()
 
-and hook it up in your root ``app.py``::
-
-    # yourproject/app.py
-    from oscar.app import Shop
-
-    from yourproject.promotions.app import application as promotions_app
-
-    class BaseApplication(Shop):
-        promotions_app = promotions_app
-
 
 Add as Django app
 =================