Integrate markItUp! Into the Django Admin

What is markItUp?

markItUp! is attempting to be a universal markup editor that will support working with a variety of markup syntaxes. It is simple to setup and can turn any textarea into a full-fledged editor with just a few lines of code. They've also provided a lot of hooks to make it customizable so you can easily add new features or change the behavior. The documentation still needs a fair bit of work, but I was able to get it up and running by just poking around.

My motivation for investigating markItUp was that I realized a need to create some editing tools that would reduce the time it takes me to write posts and automate some of the styling that I like to use to highlight important keywords, people, and sites that I mention in my articles. But aren't markup syntaxes supposed to do this already? Yes they do, but it can still be tedious to manually add lot of links and add specific styling. Let me point out that my mindset with the creation of this blog has been to benefit from the learning experience. While I could of course use this, that, and the other tool/editor out there for building and managing my content, part of the enjoyment for me has been learning about the problem sets accompany publishing and content creation.

I think it is a common pattern for us custom blog builders to represent posts with an Entry model that contains two fields to hold the actual content. One field holds the "raw" content - typically in a markup format - and the other field holds the display content. Then we override the model's save method to process the markup content into HTML suitable for live content and stick that into the display field. So what I was looking for was an easy way to beef up the raw content field with some utilities so that composing entries would be a little easier.

I just happened to come across markItUp and was pleased to see that it would probably provide much of what I wanted and it looks like I'll be able to customize it to provide the shortcuts that are specific to my writing and styling preferences. I'm also a fan of jQuery. Obviously it would be preferable to just extend the admin since it's already so powerful so if I could just drop something in that would make editing a little saner that would seem to be a huge win.

Installing and Configuring markItUp!

I had a little confusion starting out because I followed the download link from the home page, which provides with you with the default set. markItUp uses the notion of "sets" to configure the specific markup language to work with. The default set is simply HTML. Once I found the downloads page I realized that I needed to also grab the Markdown set (my preferred markup syntax at the moment). From there installation proceeded well enough by combining referencing their sparse documentation with a few peeks into Firebug. In fact, I'm writing this post with the editor in place!

Extending the Admin

All we really need to do is drop a few javascript and CSS references and a little javascript snippet into the __ to turn our textarea field into a markItUp! editor. If you've never done any admin customization before, take a gander through the chapter in the Django book. I added a change_form.html template to /mytemplates/admin/article/entry. "mytemplates" is specified as a template directory in my Django settings, article is the app, and entry refers to the Entry model. The admin knows to look there first for any appropriate templates and load those rather its own template. Here is what my change_form.html template looks like:

{% extends "admin/change_form.html" %}

{% block extrahead %}
{{block.super}}
<link rel="stylesheet" type="text/css" href="{{MEDIA_URL}}css/markitup/markdown/style.css" />
<link rel="stylesheet" type="text/css" href="{{MEDIA_URL}}css/markitup/skins/markitup/style.css" />

<script src="{{MEDIA_URL}}js/jquery.js"></script>
<script type="text/javascript" src="{{MEDIA_URL}}js/markitup/jquery.markitup.js"></script>
<script type="text/javascript" src="{{MEDIA_URL}}js/markitup/markdown/set.js"></script>
<script type="text/javascript" >
   $(document).ready(function() {
      $("#id_body").markItUp(mySettings);
   });
</script>
{% endblock %}

A few notes:

• The code snippet in the Django book does not include {{block.super}}. If you don't include this, then your change form won't pull in all of the helper scripts that provide some of the dynamic functionality you may rely on such as "pre-populate from". I don't know why they don't mention this in the book, but in most cases you'll probably want the admin to have the normal scripts available.
  
• The "markitup/markdown/style.css" comes from the Markdown set and it provides the styling for the Markdown-specific buttons on the toolbar. The other one comes from the default set and provides some of the basic styling for the editor regardless of what markup set you happen to be working with.
• I had to do a little find/replace on the css files to get the background image paths to match up to my configuration. The stylesheets assume that the images are all located in an images directory located at the root of the site. I house all my media (images,css,js) under a "site_media" directory and then I like to organize resources into subfolders so the markItUp! default scheme didn't work for me.
• The "set.js" comes from the Markdown set. The defaults worked fine for me just to get everything going and I added a previewParserPath (more on that in a minute).
• The little javascript snippet simply directs markItUp! to the textarea on the page and sets up the editor with the settings that are specified in "set.js". #id_body refers to the textarea corresponding to the body field on my Entry model.

This is all you need to do to get the editor working on a textarea on your admin change form page. The editor also has a "Preview" button (the checkmark) which will show the actual output in an iFrame below your textarea - a very handy feature! However you need to do a little extra work to have that functionality available.

Adding Preview Functionality

The editor will simply make an XHR POST with the markup content and dump the response back into the iFrame. So you just need to set up a view that will accept a data POST parameter, format it according to your preferred markup syntax, and return a full HTML page containing the output. Here is what a view could look like - add in your own exception handling and error checking to taste:

from markdown import markdown
from django.template.context import RequestContext
from django.shortcuts import render_to_response

def apply_markdown( request ):
    markup = markdown( request.POST['data'], extensions=['codehilite'] )
    return render_to_response( 'utils/markup/markdown/preview.html',
                              {'preview':markup},
                              context_instance=RequestContext(request))

You'll notice that I pass the codehilite extension to markdown to handle making code snippets all nice and pretty. You may not need this in which case you can simply omit the second parameter. I am using a RequestContext since I would like access to the MEDIA_URL in the template. This makes it easy to include the special stylesheet utilized by codehilite in a portable manner (syntax.css). Here is the template:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
    <title>Markdown Preview</title>
    <link rel="stylesheet" type="text/css" href="{{MEDIA_URL}}css/syntax.css" />
</head>
<body>
    {{preview|safe}}
</body>
</html>

The last thing to get this working is to add the path to your view in the previewParserPath in the set.js. Now you can simply hit the Preview button and get an idea of what your final output will look like. One minor annoyance is that once the Preview iFrame is open there does not appear to be an easy way to close it and what will happen is that as you continue editing your markup the iFrame will refresh whenever you hit Enter.

Conclusion

One issue worth a little attention is that if you are using the built-in development server to serve media with the Django static media view, adding in the markItUp! editor will add a lot of overhead since it pulls in a few extra javascripts, a few extra CSS files, and fair amount of small graphics to provide the toolbar. As the Django documentation clearly states, the development server was not designed with media serving in mind. You may find that your admin pages bog down quite a bit on loading. If this bugs you, I recommend taking a few minutes to set up a local media server for yourself. That way you'll get the benefits of the debug environment combined with the snappy performance of a dedicated file server.

markItUp! has already provided some tangible benefits to my work flow and I am looking forward to doing some further customization to make it even more useful. In a future article I plan to cover any useful bits I come across. markItUp! may not be for everyone. In particular there are some known issues with how Safari handles events on Ctrl and Shift keys. Also, this is still beta software so use at your own risk. As I mentioned, the documentation could benefit from a little more detail and some more code examples.

<<     Back to Unbracketed Home Post a Comment Now 121 Comments Below

Comments