@@ -2,12 +2,132 @@ django-markupfield ================== -An implementation of MarkupField for Django +An implementation of a custom MarkupField for Django. A MarkupField is in +essence a TextField with an associated markup type. The field also caches +its rendered value on the assumption that disk space is cheaper than CPU +cycles in a web application. + +Installation +============ + +You can obtain the latest release of django-markupfield via +`PyPI <http://pypi.python.org/pypi/django-honeypot>`_ or check out the +`latest source <http://github.com/jamesturk/django-markupfield>`_ + +To install a source distribution:: + + python setup.py install + +It is also possible to install django-markupfield with +`pip <http://pypi.python.org/pypi/pip>`_ or easy_install. + +It is not necessary to add ``'markupfield'`` to your ``INSTALLED_APPS``, it +merely needs to be on your ``PYTHONPATH``. + +Settings +======== + +To best make use of MarkupField you should define the +``MARKUP_FIELD_TYPES`` setting, a dictionary of strings to callables that +'render' a markup type:: + + import markdown + from docutils.core import publish_parts + + def render_rest(markup): + parts = publish_parts(source=markup, writer_name="html4css1") + return parts["fragment"] + + MARKUP_FIELD_TYPES = { + 'markdown': markdown.markdown, + 'ReST': render_rest, + } + +Usage +===== + +Using MarkupField is relatively easy, it can be used in any model definition:: + + from django.db import models + from markupfield.fields import MarkupField + + class Article(models.Model): + title = models.CharField(max_length=100) + slug = models.SlugField(max_length=100) + body = MarkupField() + +``Article`` objects can then be created with any markup type defined in +``MARKUP_FIELD_TYPES``:: + + Article.objects.create(title='some article', slug='some-article', + body='*fancy*', body_markup_type='markdown') + +You will notice that a field named ``body_markup_type`` exists that you did +not declare, MarkupField actually creates two extra fields here +``body_markup_type`` and ``_body_rendered``. These fields are always named +according to the name of the declared ``MarkupField``. + +Arguments +--------- + +``MarkupField`` also takes two optional arguments ``default_markup_type`` and +``markup_type``. Either of these arguments may be specified but not both. + +``default_markup_type``: + Set a markup_type that the field will default to if one is not specified. + It is still possible to edit the markup type attribute and it will appear + by default in ModelForms. + +``markup_type``: + Set markup type that the field will always use, ``editable=False`` is set + on the hidden field so it is not shown in ModelForms. + +Accessing a MarkupField on a model +---------------------------------- + +When accessing an attribute of a model that was declared as a ``MarkupField`` +a special ``Markup`` object is returned. The ``Markup`` object has three +parameters: + +``raw``: + The unrendered markup. +``markup_type``: + The markup type. +``rendered``: + The rendered HTML version of ``raw``, this attribute is read-only. + +This object has a ``__unicode__`` method that calls +``django.utils.safestring.mark_safe`` on ``rendered`` allowing MarkupField +objects to appear in templates as their rendered selfs without any template +tag or having to access ``rendered`` directly. + +Assuming the ``Article`` model above:: + + >>> a = Article.objects.all()[0] + >>> a.body.raw + u'*fancy*' + >>> a.body.markup_type + u'markdown' + >>> a.body.rendered + u'<p><em>fancy</em></p>' + >>> print unicode(a.body) + <p><em>fancy</em></p> + +Assignment to ``a.body`` is equivalent to assignment to ``a.body.raw`` and +assignment to ``a.body_markup_type`` is equivalent to assignment to +``a.body.markup_type``. + +.. note:: + a.body.rendered is only updated when a.save() is called + + +Todo +==== -TODO: * validate markup_type options * write documentation * convert tests from doctest to unittest + * add a test for __unicode__ Origin ====== README.rst 659a67300830401bcdf464b02f94bb1be9df9e27 James Turk james.p.turk@gmail.com http://github.com/jamesturk/django-markupfield/commit/acb851cd4cd278db918c4a3b8840ec48231ebdc1 acb851cd4cd278db918c4a3b8840ec48231ebdc1 2009-06-18T16:44:18-07:00 2009-06-18T16:44:18-07:00 updated README 6ada131b149795327379ec2ffdcd550cf42b6b2b James Turk james.p.turk@gmail.com