{ "info": { "author": "Carl Meyer", "author_email": "carl@oddbird.net", "bugtrack_url": null, "classifiers": [ "Development Status :: 5 - Production/Stable", "Environment :: Web Environment", "Framework :: Django", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5" ], "description": "===============\ndjango-markitup\n===============\n\n.. image:: https://img.shields.io/pypi/v/django-markitup.svg\n :target: https://pypi.python.org/pypi/django-markitup/\n :alt: Latest PyPI version\n\n.. image:: https://img.shields.io/pypi/dm/django-markitup.svg\n :target: https://pypi.python.org/pypi/django-markitup/\n :alt: Number of PyPI downloads\n\n.. image:: https://img.shields.io/pypi/pyversions/django-markitup.svg\n :target: https://pypi.python.org/pypi/django-markitup/\n :alt: Supported Python versions\n\n.. image:: https://travis-ci.org/zsiciarz/django-markitup.svg\n :target: https://travis-ci.org/zsiciarz/django-markitup\n\nA Django reusable application for end-to-end markup handling. Includes:\n\n* Easy integration of the `MarkItUp!`_ markup editor widget (by Jay\n Salvat) in Django projects, with server-side support for MarkItUp!'s\n AJAX preview. Plug in MarkItUp! via form widget or template tags.\n\n* ``MarkupField``, a ``TextField`` that automatically renders and\n stores both its raw and rendered values in the database, on the\n assumption that disk space is cheaper than CPU cycles in a web\n application.\n\n.. _MarkItUp!: http://markitup.jaysalvat.com/\n\n\nInstallation\n============\n\nInstall from PyPI with ``easy_install`` or ``pip``::\n\n pip install django-markitup\n\nTo use ``django-markitup`` in your Django project:\n\n 1. Add ``'markitup'`` to your ``INSTALLED_APPS`` setting.\n\n 2. Make the contents of the ``markitup/static/markitup`` directory\n available at ``STATIC_URL/markitup``; the simplest way is via\n `django.contrib.staticfiles`_.\n\n 3. Set `the MARKITUP_FILTER setting`_.\n\n 4. If you want to use AJAX-based preview, add\n ``url(r'^markitup/', include('markitup.urls'))`` in your root URLconf.\n\n.. _django.contrib.staticfiles: https://docs.djangoproject.com/en/dev/howto/static-files/\n\n\nDependencies\n------------\n\n``django-markitup`` 3.x requires `Django`_ 1.8 or later and Python 2.7+ or 3.4+.\n\n``django-markitup`` 2.x requires `Django`_ 1.4 or later and Python 2.6+ or 3.3+.\n\n``django-markitup`` 1.x requires `Django`_ 1.3 or later and Python 2.5 or later.\n\n`MarkItUp!`_ is not an external dependency; it is bundled with\n``django-markitup``.\n\n.. _Django: http://www.djangoproject.com/\n\nUsing the MarkItUp! widget\n==========================\n\nThe MarkItUp! widget lives at ``markitup.widgets.MarkItUpWidget``, and\ncan be used like any other Django custom widget.\n\nTo assign it to a form field::\n\n from markitup.widgets import MarkItUpWidget\n\n class MyForm(forms.Form):\n content = forms.CharField(widget=MarkItUpWidget())\n\nWhen this form is displayed on your site, you must include the form media\nsomewhere on the page using ``{{ form.media }}``, or the MarkItUpWidget will\nhave no effect. By default ``{{ form.media }}`` also includes the jQuery\nlibrary based on your `JQUERY_URL`_ setting. To prevent including jQuery, set\nthe `JQUERY_URL`_ setting to ``None``.\n\nMarkItUpWidget accepts three optional keyword arguments:\n``markitup_set`` and ``markitup_skin`` (see `Choosing a MarkItUp!\nbutton set and skin`_) and ``auto_preview`` (to override the value of\nthe `MARKITUP_AUTO_PREVIEW`_ setting).\n\nTo use the widget in the Django admin::\n\n from markitup.widgets import AdminMarkItUpWidget\n\n class MyModelAdmin(admin.ModelAdmin):\n ...\n def formfield_for_dbfield(self, db_field, request, **kwargs):\n if db_field.name == 'content':\n kwargs['widget'] = AdminMarkItUpWidget()\n return super(MyModelAdmin, self).formfield_for_dbfield(db_field, request, **kwargs)\n\nYou can also use the formfield_overrides attribute of the ModelAdmin, which\nis simpler but only allows setting the widget per field type (so it isn't\npossible to use the MarkItUpWidget on one TextField in a model and not\nanother)::\n\n from markitup.widgets import AdminMarkItUpWidget\n\n class MyModelAdmin(admin.ModelAdmin):\n formfield_overrides = {models.TextField: {'widget': AdminMarkItUpWidget}}\n\nIf you use `MarkupField`_ in your model, it is rendered in the admin\n with an ``AdminMarkItUpWidget`` by default.\n\nUsing MarkItUp! via templatetags\n================================\n\nIn some cases it may be inconvenient to use ``MarkItUpWidget`` (for\ninstance, if the form in question is defined in third-party code). For\nthese cases, django-markitup provides template tags to achieve the\nsame effect purely in templates.\n\nFirst, load the django-markitup template tag library::\n\n {% load markitup_tags %}\n\nThen include the MarkItUp! CSS and Javascript in the
of your page::\n\n {% markitup_media %}\n\nBy default the ``markitup_media`` tag also includes jQuery, based on the value\nof your `JQUERY_URL`_ setting, with a fallback to the version hosted at Google\nAjax APIs. To suppress the inclusion of jQuery (if you are already including it\nyourself), set the `JQUERY_URL`_ setting to ``None``.\n\nIf you prefer to link CSS and Javascript from different locations, the\n``markitup_media`` tag can be replaced with two separate tags,\n``markitup_css`` and ``markitup_js``. ``markitup_js`` accepts a\nparameter to suppress jQuery inclusion, just like\n``markitup_media``. (Note that jQuery must be included in your\ntemplate before the ``markitup_editor`` tag is used).\n\nLast, use the ``markitup_editor`` template tag to apply the MarkItUp!\neditor to a textarea in your page. It accepts one argument, the HTML\nid of the textarea. If you are rendering the textarea in the usual way\nvia a Django form object, that id value is available as\n``form.fieldname.auto_id``::\n\n {{ form.fieldname }}\n\n {% markitup_editor form.fieldname.auto_id %}\n\nYou can use ``markitup_editor`` on as many different textareas as you\nlike.\n\n``markitup_editor`` accepts an optional second parameter, which can be\neither ``\"auto_preview\"`` or ``\"no_auto_preview\"`` to override the\nvalue of the `MARKITUP_AUTO_PREVIEW`_ setting.\n\nThe actual HTML included by these templatetags is defined by the\ncontents of the templates ``markitup/include_css.html``,\n``markitup/include_js.html``, and ``markitup/editor.html``. You can\noverride these templates in your project and customize them however\nyou wish.\n\nMarkupField\n===========\n\nYou can apply the MarkItUp! editor control to any textarea using the\nabove techniques, and handle the markup on the server side however you\nprefer.\n\nFor a seamless markup-handling solution, django-markitup also provides\na ``MarkupField`` model field that automatically renders and stores\nboth its raw and rendered values in the database, using the value of\n`the MARKITUP_FILTER setting`_ to parse the markup into HTML.\n\nA ``MarkupField`` is easy to add to any model definition::\n\n from django.db import models\n from markitup.fields import MarkupField\n\n class Article(models.Model):\n title = models.CharField(max_length=100)\n body = MarkupField()\n\n``MarkupField`` automatically creates an extra non-editable field\n``_body_rendered`` to store the rendered markup. This field doesn't\nneed to be accessed directly; see below.\n\nAccessing a MarkupField on a model\n----------------------------------\n\nWhen accessing an attribute of a model that was declared as a\n``MarkupField``, a ``Markup`` object is returned. The ``Markup``\nobject has two attributes:\n\n``raw``:\n The unrendered markup.\n``rendered``:\n The rendered HTML version of ``raw`` (read-only).\n\nThis object also has a ``__unicode__`` method that calls\n``django.utils.safestring.mark_safe`` on ``rendered``, allowing\n``MarkupField`` attributes to appear in templates as rendered HTML\nwithout any special template tag or having to access ``rendered``\ndirectly.\n\nAssuming the ``Article`` model above::\n\n >>> a = Article.objects.all()[0]\n >>> a.body.raw\n '*fancy*'\n >>> a.body.rendered\n 'fancy
'\n >>> print(unicode(a.body))\nfancy
\n >>> a.body.render_with('markitup.renderers.render_rest')\n >>> print(unicode(a.body))\n 'fancy
\\n