Django integration with the MarkItUp universal markup editor
Project description
Easy integration of the MarkItUp markup editor widget (by Jay Salvat) in Django projects. Includes server-side support for MarkItUp!’s AJAX preview.
Installation
Install from PyPI with easy_install or pip:
pip install django-markitup
or get the in-development version:
pip install django-markitup==dev
To use django-markitup in your Django project:
Add 'markitup' to your INSTALLED_APPS setting.
Make the contents of the markitup/media/markitup directory available at MEDIA_URL/markitup. This can be done by copying the files, making a symlink, or through your webserver configuration.
If you want to use AJAX-based preview:
Add url(r'^markitup/', include('markitup.urls') in your root URLconf.
Set the MARKITUP_PREVIEW_FILTER setting (see Using AJAX preview below).
Using the MarkItUp! widget
The MarkItUp! widget lives at markitup.widgets.MarkItUpWidget, and can be used like any other Django custom widget.
To assign it to a form field:
from markitup.widgets import MarkItUpWidget ... content = forms.TextField(widget=MarkItUpWidget())
When this form is displayed on your site, you must include the form media somewhere on the page using {{ form.media }}, or the MarkItUpWidget will have no effect.
To use MarkItUpWidget in the Django admin:
from markitup.widgets import MarkItUpWidget
class MyModelAdmin(admin.ModelAdmin):
...
def formfield_for_dbfield(self, db_field, **kwargs):
if db_field.name == 'content':
kwargs['widget'] = MarkItUpWidget(attrs={'class': 'vLargeTextField'})
return super(MyModelAdmin, self).formfield_for_dbfield(db_field, **kwargs)
You can also use the formfield_overrides attribute of the ModelAdmin, which is simpler but only allows setting the widget per field type (so it isn’t possible to use the MarkItUpWidget on one TextField in a model and not another).
Using MarkItUp! via templates
In some cases it may be inconvenient to use MarkItUpWidget (for instance, if the form in question is defined in third-party code). For these cases, django-markitup provides template tags to achieve the same effect purely in templates.
First, load the django-markitup template tag library:
{% load markitup_tags %}
Then include the MarkItUp! CSS and Javascript in the <head> of your page:
{% markitup_head %}
By default the markitup_head tag also includes jQuery, based on the value of your JQUERY_URL setting, with a fallback to the version hosted at Google Ajax APIs (see below). To suppress the inclusion of jQuery (if you are already including it yourself), pass any non-zero argument to the tag:
{% markitup_head "no-jquery" %}
If you prefer to link CSS and Javascript from different locations, the markitup_head tag can be replaced with two separate tags, markitup_css and markitup_js. markitup_js accepts a parameter to suppress jQuery inclusion, just like markitup_head. (Note that jQuery must be included in your template before the markitup_editor tag is used).
Last, use the markitup_editor template tag to apply the MarkItUp! editor to a textarea in your page. It accepts one argument, the HTML id of the textarea. Note that if you are rendering the textarea in the usual way via a Django form object, that id value is available as form.fieldname.auto_id:
{{ form.fieldname }}
{% markitup_editor form.fieldname.auto_id %}
You can use markitup_editor on as many different textareas as you like.
The actual HTML included by these templatetags is defined by the contents of the templates markitup/include_css.html, markitup/include_js.html, and markitup/editor.html. You can override these templates and customize them however you wish.
Using AJAX preview
If you’ve included markitup.urls in your root URLconf (as demonstrated above under Installation), all you need to enable server-side AJAX preview is the MARKITUP_PREVIEW_FILTER setting.
MARKITUP_PREVIEW_FILTER must be a two-tuple.
The first element must be a string, the Python dotted path to a markup filter function. This function should accept markup as its first argument and return HTML. It may accept other keyword arguments as well. You may parse your markup for preview using any method you choose, as long as you can wrap it in a function that meets these criteria.
The second element must be a dictionary of keyword arguments to pass to the filter function. The dictionary may be empty.
For example, if you have python-markdown installed, you could use it like this:
MARKITUP_PREVIEW_FILTER = ('markdown.markdown', {'safe_mode': True})
Alternatively, you could use the “textile” filter provided by Django like this:
MARKITUP_PREVIEW_FILTER = ('django.contrib.markup.templatetags.markup.textile', {})
(The textile filter function doesn’t accept keyword arguments, so the kwargs dictionary must be empty in this case.)
- Note: If you use your own custom MarkItUp! set, be sure to set the
previewParserPath option to '/markitup/preview/'.
Other settings
MarkItUp! requires the jQuery Javascript library. By default, django-markitup links to the most recent minor version of jQuery 1.3 available at ajax.googleapis.com (via the URL http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js). If you wish to use a different version of jQuery, or host it yourself, set the JQUERY_URL setting. For example:
JQUERY_URL = 'jquery.min.js'
This will use the jQuery available at MEDIA_URL/jquery.min.js.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
