Merge pull request #1862 from antsar/master

Add subclassing pattern/example

docs/becomingbig.rst

@@ -35,7 +35,7 @@ Subclass.
 The :class:`~flask.Flask` class has many methods designed for subclassing. You
 can quickly add or customize behavior by subclassing :class:`~flask.Flask` (see
 the linked method docs) and using that subclass wherever you instantiate an
-application class. This works well with :ref:`app-factories`.
+application class. This works well with :ref:`app-factories`. See :doc:`/patterns/subclassing` for an example.
 
 Wrap with middleware.
 ---------------------

docs/patterns/index.rst

@@ -41,3 +41,4 @@ Snippet Archives <http://flask.pocoo.org/snippets/>`_.
    methodoverrides
    requestchecksum
    celery
+   subclassing

docs/patterns/subclassing.rst

@@ -0,0 +1,22 @@
+Subclassing Flask
+=================
+
+The :class:`~flask.Flask` class is designed for subclassing.
+
+One reason to subclass would be customizing the Jinja2 :class:`~jinja2.Environment`. For example, to add a new global template variable::
+
+    from flask import Flask
+    from datetime import datetime
+
+    class MyFlask(Flask):
+        """ Flask with more global template vars """
+
+        def create_jinja_environment(self):
+            """ Initialize my custom Jinja environment. """
+            jinja_env = super(MyFlask, self).create_jinja_environment(self)
+            jinja_env.globals.update(
+                current_time = datetime.datetime.now()
+            )
+            return jinja_env
+
+This is the recommended approach for overriding or augmenting Flask's internal functionality.