Ticket #15244: doc-custom_renderer_howto.patch

docs/howto/custom-widget-renderer.txt

@@ +1 @@
+============================================
+Writing (and using) a custom widget renderer
+============================================
+
+It's possible to override a renderer for a specific widget by subclassing
+it. A good example is the RadioSelect widget that, by default, outputs
+a list of items. 
+
+To override this behavior, we need to subclass the widget. In particular
+its renderer function. For example, take this piece of code that can be
+included in ``myproject/myapp/forms.py``:
+
+.. code-block:: python
+    from django.forms.widgets import RadioFieldRenderer, RadioSelect
+    from django.utils.encoding import StrAndUnicode, force_unicode
+    from django.utils.safestring import mark_safe
+    
+    class CustomRenderer(RadioFieldRenderer):
+        def render(self):
+            return mark_safe(u'\n%s\n' % u'\n'.join([u'<tr><td>%s</td></tr>'
+                    % force_unicode(w) for w in self]))
+    
+    class CustomRadioSelect(RadioSelect):
+        renderer = CustomRenderer
+
+
+You can then use the new widget like this:
+
+.. code-block::  python
+    class OSChoiceForm(forms.Form):
+        OS_CHOICES = (
+                ('linux', 'Linux'),
+                ('windows', 'Windows'),
+                ('mac', 'Macintosh'),
+                )
+        os = forms.ChoiceField(label='', widget=CustomRadioSelect, choices=OS_CHOICES )
+
+And the form will be rendered as table rows instead of list items.
+

docs/howto/index.txt

@@ -15 +15 @@
    custom-model-fields
    custom-template-tags
    custom-file-storage
+   custom-widget-renderer
    deployment/index
    error-reporting
    initial-data