Merge pull request #1812 from gasman/feature/block-template-context

Allow block subclasses to pass extra context variables to templates

docs/topics/streamfield.rst

@@ -442,6 +442,28 @@ Within the template, the block value is accessible as the variable ``value``:
 The line ``value.bound_blocks.biography.render`` warrants further explanation. While blocks such as RichTextBlock are aware of their own rendering, the actual block *values* (as returned when accessing properties of a StructBlock, such as ``value.biography``), are just plain Python values such as strings. To access the block's proper HTML rendering, you must retrieve the 'bound block' - an object which has access to both the rendering method and the value - via the ``bound_blocks`` property.
 
 
+To pass additional context variables to the template, block subclasses can override the ``get_context`` method:
+
+.. code-block:: python
+
+    import datetime
+
+    class EventBlock(blocks.StructBlock):
+        title = blocks.CharBlock(required=True)
+        date = blocks.DateBlock(required=True)
+
+        def get_context(self, value):
+            context = super(EventBlock, self).get_context(value)
+            context['is_happening_today'] = (value['date'] == datetime.date.today())
+            return context
+
+        class Meta:
+            template = 'myapp/blocks/event.html'
+
+
+In this example, the variable ``is_happening_today`` will be made available within the block template.
+
+
 Custom block types
 ------------------
 

wagtail/tests/testapp/blocks.py

@@ -0,0 +1,14 @@
+from wagtail.wagtailcore import blocks
+
+
+class LinkBlock(blocks.StructBlock):
+    title = blocks.CharBlock()
+    url = blocks.URLBlock()
+
+    def get_context(self, value):
+        context = super(LinkBlock, self).get_context(value)
+        context['classname'] = 'important' if value['title'] == 'Torchbox' else 'normal'
+        return context
+
+    class Meta:
+        template = 'tests/blocks/link_block.html'

wagtail/tests/testapp/templates/tests/blocks/link_block.html

@@ -0,0 +1 @@
+<a href="{{ self.url }}" class="{{ classname }}">{{ self.title }}</a>

wagtail/wagtailcore/blocks/base.py

@@ -200,6 +200,12 @@ class Block(six.with_metaclass(BaseBlock, object)):
         """
         return value
 
+    def get_context(self, value):
+        return {
+            'self': value,
+            self.TEMPLATE_VAR: value,
+        }
+
     def render(self, value):
         """
         Return a text rendering of 'value', suitable for display on templates. By default, this will
@@ -208,10 +214,7 @@ class Block(six.with_metaclass(BaseBlock, object)):
         """
         template = getattr(self.meta, 'template', None)
         if template:
-            return render_to_string(template, {
-                'self': value,
-                self.TEMPLATE_VAR: value,
-            })
+            return render_to_string(template, self.get_context(value))
         else:
             return self.render_basic(value)
 

wagtail/wagtailcore/tests/test_blocks.py

@@ -1439,3 +1439,14 @@ class TestSystemCheck(TestCase):
         self.assertEqual(errors[1].id, 'wagtailcore.E001')
         self.assertEqual(errors[1].hint, "Block names cannot contain spaces")
         self.assertEqual(errors[0].obj, failing_block_2)
+
+
+class TestTemplateRendering(TestCase):
+    def test_render_with_custom_context(self):
+        from wagtail.tests.testapp.blocks import LinkBlock
+
+        block = LinkBlock()
+        value = block.to_python({'title': 'Torchbox', 'url': 'http://torchbox.com/'})
+        result = block.render(value)
+
+        self.assertEqual(result, '<a href="http://torchbox.com/" class="important">Torchbox</a>')