Documentation and release notes for #3275

CHANGELOG.txt

@@ -4,6 +4,7 @@ Changelog
 1.9 (xx.xx.xxxx) - IN DEVELOPMENT
 ~~~~~~~~~~~~~~~~
 
+ * `get_context` methods on StreamField blocks can now access variables from the parent context (Mikael Svensson, Peter Baumgartner)
  * View live / draft links in the admin now consistently open in a new window (Marco Fucci)
  * `ChoiceBlock` now omits the blank option if the block is required and has a default value (Andreas Nüßlein)
  * Fix: Help text for StreamField is now visible and does not cover block controls (Stein Strindhaug)

CONTRIBUTORS.rst

@@ -202,6 +202,8 @@ Contributors
 * Nikolai Røed Kristiansen
 * Alex Zagorodniuk
 * glassresistor
+* Mikael Svensson
+* Peter Baumgartner
 
 Translators
 ===========

docs/releases/1.9.rst

@@ -10,9 +10,13 @@ Wagtail 1.9 release notes - IN DEVELOPMENT
 What's new
 ==========
 
+Accessing parent context from StreamField block ``get_context`` methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``get_context`` method on StreamField blocks now receives a ``parent_context`` keyword argument, consisting of the dict of variables passed in from the calling template. For example, this makes it possible to perform pagination logic within ``get_context``, retrieving the current page number from ``parent_context['request'].GET``. See :ref:`get_context on StreamField blocks <streamfield_get_context>`. This feature was developed by Mikael Svensson and Peter Baumgartner.
 
 
-Minor features
+Other features
 ~~~~~~~~~~~~~~
 
  * View live / draft links in the admin now consistently open in a new window (Marco Fucci)
@@ -29,3 +33,32 @@ Bug fixes
 Upgrade considerations
 ======================
 
+``get_context`` methods on StreamField blocks need updating
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously, ``get_context`` methods on StreamField blocks returned a dict of variables which would be merged into the calling template's context before rendering the block template. ``get_context`` methods now receive a ``parent_context`` dict, and are responsible for returning the final context dictionary with any new variables merged into it. The old calling convention is now deprecated, and will be phased out in Wagtail 1.11.
+
+In most cases, the method will be calling ``get_context`` on the superclass, and can be updated by passing the new ``parent_context`` keyword argument to it:
+
+.. code-block:: python
+
+    class MyBlock(Block):
+
+        def get_context(self, value):
+            context = super(MyBlock, self).get_context(value)
+            ...
+            return context
+
+becomes:
+
+.. code-block:: python
+
+    class MyBlock(Block):
+
+        def get_context(self, value, parent_context=None):
+            context = super(MyBlock, self).get_context(value, parent_context=parent_context)
+            ...
+            return context
+
+
+Note that ``get_context`` methods on page models are unaffected by this change.

docs/topics/streamfield.rst

@@ -636,8 +636,8 @@ As well as passing variables from the parent template, block subclasses can pass
         title = blocks.CharBlock(required=True)
         date = blocks.DateBlock(required=True)
 
-        def get_context(self, value):
-            context = super(EventBlock, self).get_context(value)
+        def get_context(self, value, parent_context=None):
+            context = super(EventBlock, self).get_context(value, parent_context=parent_context)
             context['is_happening_today'] = (value['date'] == datetime.date.today())
             return context
 
@@ -645,7 +645,7 @@ As well as passing variables from the parent template, block subclasses can pass
             template = 'myapp/blocks/event.html'
 
 
-In this example, the variable ``is_happening_today`` will be made available within the block template.
+In this example, the variable ``is_happening_today`` will be made available within the block template. The ``parent_context`` keyword argument is available when the block is rendered through an ``{% include_block %}`` tag, and is a dict of variables passed from the calling template.
 
 
 BoundBlocks and values