diff --git a/djadmin2/renderers.py b/djadmin2/renderers.py index 8fb8a31..96fb417 100644 --- a/djadmin2/renderers.py +++ b/djadmin2/renderers.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- """ -This module contains default renderers for admin fields. They are used for -example in the list view. +There are currently a few renderers that come directly with django-admin2. They +are used by default for some field types. """ from __future__ import division, absolute_import, unicode_literals diff --git a/docs/index.rst b/docs/index.rst index 10f569a..ec3a21b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -80,6 +80,7 @@ Reference ref/permissions ref/views ref/built-in-views + ref/renderers ref/meta Indices and tables diff --git a/docs/ref/renderers.rst b/docs/ref/renderers.rst new file mode 100644 index 0000000..a5ad395 --- /dev/null +++ b/docs/ref/renderers.rst @@ -0,0 +1,62 @@ +================ +Custom Renderers +================ + +It is possible to create custom renderers for specific fields. Currently they +are only used in the object list view, for example to render boolean values +using icons. Another example would be to customize the rendering of dates. + + +Renderers +--------- + +A renderer is a function that accepts a value and the field and returns a HTML +representation of it. For example, the very simple builtin datetime renderer +works like this: + +.. code-block:: python + + def title_renderer(value, field): + """Render a string in title case (capitalize every word).""" + return unicode(value).title() + +In this case the ``field`` argument is not used. Sometimes it useful though: + +.. code-block:: python + + def number_renderer(value, field): + """Format a number.""" + if isinstance(field, models.DecimalField): + return formats.number_format(value, field.decimal_places) + return formats.number_format(value) + +You can create your renderers anywhere in your code, but it is recommended to +put them in a file called ``renderers.py`` in your project. + + +Using Renderers +--------------- + +The renderers can be specified in the Admin2 class using the +``field_renderers`` attribute. The attribute contains a dictionary that maps a +field name to a renderer function. + +By default, some renderers are automatically applied, for example the boolean +renderer when processing boolean values. If you want to suppress that renderer, +you can assign ``None`` to the field in the ``field_renderers`` dictionary. + +.. code-block:: python + + class PostAdmin(djadmin2.ModelAdmin2): + list_display = ('title', 'body', 'published') + field_renderers = { + 'title': renderers.title_renderer, + 'published': None, + } + + +Builtin Renderers +----------------- + +.. automodule:: djadmin2.renderers + :members: