The idea here is to add a delete link on the shouts that the user created as she is viewing the shout history. We will use the jQuery library to dynamically add click handlers to these links. The click handler functions will make an AJAX post to the server and request that a shout be deleted. The server view function will verify that the user sending the request actually created the shout in question. If so, the shout will be deleted from the database and then a response sent back to the client. This response will be then be used by our Javascript to hide the deleted shout. Thus we will have deleted a shout without refreshing the entire page.

The first thing I did was modify the shout history template to output a link underneath a shout if the current user authored that shout. This template (shoutbox/view.html) was presented in part 5. I’ll just show the new code inside the for loop that adds these links:

    {% ifequal user shout.user %}
        | <a href="#" class="shout-del" id="shout-del-{{ shout.id }}">Delete</a>
    {% endifequal %}

The important thing to note is our links don’t go anywhere, they have the CSS class “shout-del”, and we give them an id of “shout-del-xx” where xx is the id of the shout from the database.

I then modified the shoutbox_app.js document ready function to look for all links that have the class “shout-del” and I attach a click function to them. The click function asks the user via the Javascript confirm() function if they really want to delete the shout. If they confirm, I then use javascript regular expression magic to pull out the shout’s  primary key from the <a> tag’s id, and send a POST request to the server to delete that shout. The relevant snippet is shown below.

     $('.shout-del').click(function () {
         if (confirm('Really delete this shout?')) {
             id = this.id;
             if (id.match(/shout-del-(\d+)/)) {
                $.post('/shout/delete/', { id : RegExp.$1 }, function(id) {
                    id = '#shout-del-' + id
                    $(id).parents('tr').hide();
                    $('div.shoutbox-history table tr:visible:even').removeClass('odd');
                    $('div.shoutbox-history table tr:visible:odd').addClass('odd');
                    }, 'text');
             }
         }
         return false;
     });

We are posting to the URL /shout/delete, and passing along the shout ID in the id parameter. We also supply a callback function that gets called when the delete happens successfully. More on that later. Finally the click function returns false so that the default action of clicking on a link is not executed.

We now turn to the server, and examine the view function that handles the URL /shout/delete. You’ll notice similar code as presented in part 5′s edit view function. This time I have discovered Django’s classes that derive from HttpResponse, and I use them in the error cases.

def delete(request):
    """This view deletes a shout. It is called by AJAX from the shoutbox history view."""
    if request.user.is_authenticated():
        id = request.POST.get('id', None)
        if id is None:
            return HttpResponseBadRequest()
        try:
            shout = Shout.objects.get(pk=id)
        except Shout.DoesNotExist:
            return HttpResponseBadRequest()
        if request.user != shout.user:
            return HttpResponseForbidden()
        shout.delete()
        return HttpResponse(id)

    return HttpResponseForbidden()

We check to see if the user is authenticated before proceeding. We then retrieve the shout ID from the POST QueryDict. From the ID we retrieve the actual shout from the database using the Django ORM. And finally, if and only if the user making the request is the same user that created the shout, we delete it. If all of that went well, we send back a positive HTTP response that includes the ID of the shout that was deleted.

Now refer back to our Javascript, posted above.  In the callback function we receive the ID as text from the server. We then convert the numeric ID to the CSS ID and use jQuery to select the parent <tr> of our <a> tag, and hide it. Wow! That was a very compact way to do all of that work.

The remaining logic takes care of the table presentation. I used CSS to style every other row in the shout history table with a class called “odd”. Since we just hid one row, that scheme got messed up. Luckily, the compact notation of jQuery again comes to the rescue and we can quickly restyle all odd visible rows with our class “odd”, taking care to remove the style from the new even rows first.

And there we have a shoutbox written in Django and Javascript for the new version of my site. Not bad for my first attempt, and it certainly was much easier than I imagined. All in all, there is a lot less Python code than the existing PHP code, and we even get neat-o AJAX’y features that the old one didn’t have. So I think we will go with this for the first pass of the site. Once I get more comfortable with jQuery I may decide to redo the scrolling itself with it. We could also look into posting shouts to the database without a complete page refresh. There is always something to go back and refactor as you learn more about your tools and best practices. I hope someone found this quick series of posts useful.

The first thing I did was create a “shout history” view. This allows you to view the shouts in a full page context. In my views.py file I created this:

def view(request, page=1):
    """This view allows one to view the shoutbox history."""
    paginator = DiggPaginator(Shout.objects.all(), SHOUTS_PER_PAGE, body=5, tail=3, margin=3, padding=2)
    try:
        the_page = paginator.page(int(page))
    except InvalidPage:
        raise Http404

    return render_to_response('shoutbox/view.html', {
        'page': the_page,
        },
        context_instance = RequestContext(request))

Here I am using the DiggPaginator, which is a very nice paginator that gives you “Digg-style” pagination. I then pass the page object to the template which does most of the interesting work.

In order to get the edit-in-place funcitonality to work, I am leveraging the Jeditable jQuery plugin. In order to use this plugin, in my shoutbox/view.html template I include <script> tags to bring in both the jQuery javascript library and the Jeditable plugin code. I then loop over the shouts for the page and display them along with the avatar and links to the user that made the shout. You’ll also see me using the smilify fiilter I discussed in part 4.

{% extends 'base.html' %}
<pre>{% load avatar_tags %}
{% load smiley_tags %}
{% block custom_css %}
<link rel="stylesheet" type="text/css" href="{{ MEDIA_URL }}css/shoutbox_app.css" />
<link rel="stylesheet" type="text/css" href="{{ MEDIA_URL }}css/pagination.css" />
{% endblock %}
{% block custom_js %}
<script type="text/javascript" src="{{ MEDIA_URL }}js/jquery-1.2.6.min.js"></script>
<script type="text/javascript" src="{{ MEDIA_URL }}js/jquery.jeditable.mini.js"></script>
<script type="text/javascript" src="{{ MEDIA_URL }}js/shoutbox_app.js"></script>
{% endblock %}
{% block title %}Shout History{% endblock %}
{% block content %}
<h2>Shout History</h2>
{% if page.object_list %}
{% include 'core/pagination.html' %}

<div class="shoutbox-history">
<table>
{% for shout in page.object_list %}
<tr class="{% cycle 'even' 'odd' %}">
<th>
<a href="{% url bio-view_profile username=shout.user.username %}">{% avatar shout.user %}</a>
<a href="{% url bio-view_profile username=shout.user.username %}">{{ shout.user.username }}</a>
</th>
<td>
<div {% ifequal user shout.user %}class="edit" id="shout-{{ shout.id }}"{% endifequal %}>{{ shout.shout|smilify|urlize }}</div>
</div>
<br />
<span class="date">{{ shout.shout_date|date:"D M d Y H:i:s" }}</span>
</td>
</tr>
{% endfor %}
</table>
</div>

{% include 'core/pagination.html' %}
{% else %}
<p>No shouts at this time.</p>
{% endif %}
{% endblock %}

In order to get the edit-in-place working, I need to enclose the shouts the user can edit in a special div with the class “edit”. I do this inside the loop, adding the class attribute if the current user matches the shout user. I also give each of these divs an id of “shout-xx” where xx is the id of the shout being displayed. I thought about just using the shout id as the id, but thought this might clash with other page elements, so I prefixed it with “shout-”. This adds a tiny bit of work back in the view code, but not much.

Now that I have “tagged” the divs the user can edit, I configure the plugin with the following bit of jQuery magic in the shoutbox_app.js file:

$(document).ready(function() {
     $('.edit').editable('/shout/edit/', {
         loadurl : '/shout/text/',
         indicator : 'Saving...',
         tooltip   : 'Click to edit your shout...',
         submit : 'OK',
         cancel : 'Cancel'
     });
 });

This code instructs jQuery to find all elements with the class “edit” and call the editable() function on them. The first parameter to editable() is the URL to send the edited text to when the user hits enter or clicks OK. In our case, this is /shout/edit. I’ll show this view in a minute. The next parameter to the editable() function is a javascript options object with several interesting options:

• loadurl – this is the URL that Jeditable will call to retrieve the text to edit. Recall that our text is smilified, so we don’t want the user edited the XHTML markup. We want the user to edit the original shout text.
• indicator – after saving the edit, the Jeditable plugin will display this text to give the user feedback something is happening while it posts the edited text to the server.
• tooltip – Jeditable will display this text as a tooltip when the user hovers their mouse over the div.
• submit – Provides the text for a submit button.
• cancel – Provides the text for a cancel button.

Holy crap that was easy. Now all we need to do is provide those 2 view functions. One to receive and save the edited text, and one that is called to retrieve the original shout. First, here is the /shout/view view function that retrieves the original text.

shout_id_re = re.compile(r'shout-(\d+)')
def text(request):
    """This view function retrieves the text of a shout; it is used in the in-place
    editing of shouts on the shoutbox history view."""
    if request.user.is_authenticated():
        m = shout_id_re.match(request.GET.get('id', ''))
        if m is None:
            return HttpResponse(u'')
        try:
            shout = Shout.objects.get(pk=m.group(1))
        except Shout.DoesNotExist:
            return HttpResponse(u'')
        return HttpResponse(shout.shout)

    return HttpResponse(u'')

Jeditable is expecting that this function return the raw shout, not XHTML markup. It will pass the id of the div the user wants to edit as a GET parameter. First we check to see if the user is authenticated as a minimal check. Note that we don’t use the login_required decorator, because that would redirect the Jeditable request to the login page if the user wasn’t logged in. We then use a regular expression to pull the numeric part out of the div’s id (recall that it comes in the form shout-xx). With the id in hand we simply query the shout object using the Django ORM. We then return the shout text as an HttpResponse.

Finally here is the view function that Jeditable posts the edited data to.

def edit(request):
    """This view accepts a shoutbox edit from the shoutbox history view."""
    if request.user.is_authenticated():
        m = shout_id_re.match(request.POST.get('id', ''))
        if m is None:
            return HttpResponse(u'')
        try:
            shout = Shout.objects.get(pk=m.group(1))
        except Shout.DoesNotExist:
            return HttpResponse(u'')
        if request.user != shout.user:
            return HttpResponse(u'')
        new_shout = request.POST.get('value', '').strip()
        if new_shout == '':
            return HttpResponse(u'')
        shout.shout = new_shout
        shout.save()
        return render_to_response('shoutbox/render_shout.html', {
            'shout': shout,
            },
            context_instance = RequestContext(request))

    return HttpResponse(u'')

This function does do a lot of error checking, so it looks more complicated than it really is. This time Jeditable is expecting us to return XHTML markup, and it passes 2 things to us as POST parameters: the div id appears as “id” and the new text appears as “value”.

In short, this function checks to make sure the user posting the new shout text is the same user that created the shout in the first place. If this is the case, it simply updates the shout text and saves it back to the database. We then render a template to return the new XHTML markup for the div. Remember that we have to smilify the text, so our template looks like this:

{% load smiley_tags %}
{{ shout.shout|smilify|urlize }}

We load our smiley tags discussed in part 4, and filter the shout through our smilify filter and the Django urlize filter.

One thing that is very useful to add at this point is some CSS for our editable div tags. I added a :hover rule that changed the background color and mouse cursor. This provides additional visual cues to the user that the text can edited when the mouse is hovered over it.

And that is basically it! Here is a screen shot of a user editing a shout in-place on the shout history page.

Edit-in-place in action

I plan on adding one more blog post about the shoutbox. All we have left to do is an in-place delete of a shout on the shout history page. Stay tuned for part 6.

In case you missed the earlier parts, here they are: part 1, part 2, part 3.

One of the “fun” features of the shoutbox is the smilies, or emoticons. In a nutshell, certain character sequences are translated into small images in the “shout” text. Furthermore, all of the images are displayed below the shoutbox, and by clicking on them they get added to the shout the user is typing via some simple javascript.

I can see myself using this smiley function in lots of places: shoutbox, user comments, photo of the day, forums, etc. So I created a new application for it, separate from the shoutbox application.

I read up on django’s custom filter documentation, and spent a fair amount of time scratching my head over the auto-escaping feature. It suddenly occured to me that what I need is similar to the django urlize filter: go through some text and replace certain phrases with HTML. In the urlize case this is an <a> tag. In my case this is an <img> tag. I then studied the urlize filter source to steer me. Mine turned out a bit simpler as you will see below.

First let’s start with the model. I wanted to be able to easily edit and add smilies via the admin interface. The legacy shoutbox allowed many “phrases” to map to a single smiley, but it did this in a redundant way. I decided to keep things simple and only allow one phrase per smiley. Part of this was driven by the fact that if the user clicks on a smiley I need to add the phrase to the text they are typing. If there are multiple phrases, which do I use? I suppose I could have picked the first one, but this was going against my “let’s keep this simple for now” philosophy. Here is the model I came up with:

class Smiley(models.Model):
    image = models.ImageField(upload_to='smiley/images/')
    title = models.CharField(max_length=32)
    code = models.CharField(max_length=32)

    objects = SmileyManager()

    class Meta:
        verbose_name_plural = 'Smilies'
        ordering = ('title', )

    def __unicode__(self):
        return self.title

    def get_absolute_url(self):
        return self.image.url

    def html(self):
        if self.image:
            return u'<img src="%s" alt="%s" title="%s" />' % \
                    (self.get_absolute_url(), self.title, self.title)
        return u''
    html.allow_tags = True

This is pretty straightforward. I’ll explain the custom manager in a bit. I wanted to be able to show the smiley image in the admin section, so I added a html() member function to the Smiley class. This would be useful in templates also. In order to get the HTML to display correctly in the admin, I needed to add an “allow_tags” attribute set to True to the html() function. I can then use the html() function in the admin class in my admin.py file:

from django.contrib import admin
from smiley.models import Smiley

class SmileyAdmin(admin.ModelAdmin):
    list_display = ('title', 'code', 'html')

admin.site.register(Smiley, SmileyAdmin)

And with just that little bit of code I now have a nice admin interface to add smilies.

Admin View of Smilies

I then turned my attention to creating a custom filter for “smilifying” text. Again, I studied the urlize filter to see what was being done there (splitting the text into words), but steered my code towards the example in the documentation on how to handle auto-escaping. I realized that I could be hitting the database a lot to read the smiley definitions trying to smilify text, so I decided to cache the smiley information. A convenient way to do this was to add a custom Smiley model manager. I knew I needed a dictionary that mapped smiley code phrases to <img> HTML. And I probably would need to cache the smiley objects themselves. I handled this in a custom model manager (in models.py):

class SmileyManager(models.Manager):
    smiley_map = None
    smilies = None

    def get_smiley_map(self):
        if self.smiley_map is None:
            smilies = self.all()
            self.smiley_map = {}
            for s in smilies:
                self.smiley_map[s.code] = s.html()
        return self.smiley_map

    def get_smilies(self):
        if self.smilies is None:
            self.smilies = self.all()
        return self.smilies

    def clear_cache(self):
        self.smiley_map = None
        self.smilies = None

The get_smiley_map() and get_smilies() use caching techniques to minimize database hits. I added a clear_cache() function to force a re-read of the database. I envision that if I ever need to add or delete a smiley from the admin interface I will need to add a custom admin view that calls clear_cache(). We’ll leave that as a hook for now and cross that bridge later. Now my filter code can simply call the Smiley objects manager to get the “smiley map”.

Here is my new filter called, of course, “smilify”. I put this in the templatetags directory in a file called smiley_tags.py:

import re
from django import template
from django.template.defaultfilters import stringfilter
from django.utils.html import conditional_escape
from django.utils.safestring import mark_safe

from smiley.models import Smiley

register = template.Library()

word_split_re = re.compile(r'(\s+)')

@register.filter
@stringfilter
def smilify(value, autoescape=False):
    """A filter to "smilify" text by replacing text with HTML img tags of smilies."""
    if autoescape:
        esc = conditional_escape
    else:
        esc = lambda x: x

    smiley_map = Smiley.objects.get_smiley_map()

    words = word_split_re.split(value)
    for i, word in enumerate(words):
        if word in smiley_map:
            words[i] = smiley_map[word]
        else:
            words[i] = esc(words[i])
    return mark_safe(u''.join(words))
smilify.needs_autoescape = True

The basic idea is to split the text into words. If a word is in our smiley map, substitute it with the corresponding <img> tag. Otherwise we need to escape the word. At the end we join the words together and mark the resulting string safe.

I then updated my shoutbox template to use this new filter and voila we had smilies!

Smilies

Finally I needed a way to present all of the smileys to the user. These smilies would be clickable, and doing so would add the code for that smiley to whatever input box the comment or shout would be using. I created an inclusion tag called smiley_farm in my smiley_tags.py file to handle this. It uses the Smiley manager’s get_smilies functions, which caches the smiley objects:

@register.inclusion_tag('smiley/smiley_farm.html')
def smiley_farm():
    """An inclusion tag that displays all of the smilies in clickable form."""
    return {'smilies': Smiley.objects.get_smilies(), }

The template smiley_farm.html looks like this:

<div class="smiley_farm">
{% for s in smilies %}
    <img src="{{ s.image.url }}" alt="{{ s.code }}" title="{{ s.title }} {{ s.code }}"
        onclick="sb_smiley_click(' {{ s.code }} ');" />
{% endfor %}
</div>

I enclose the smilies in a div so I can easily style them with CSS. In particular I added a cursor: pointer style to the images so that the mouse pointer will indicate to the user that the smilies can be clicked. When you click on a smiley, the sb_smiley_click() javascript function will run, which simply adds the smiley code phrase to an input text with a certain id:

function sb_smiley_click(code)
{
    var txt = document.getElementById("shoutbox-smiley-input");
    txt.value += code;
    txt.focus();
}

As I learn more about jQuery I hope to revisit this code and add the onclick function to the images after the page has loaded.

Finally, I added a bit of javascript to hide the smiley farm until the user clicks a button labeled “Smilies” to reveal them to conserve screen real estate. This idea and behavior is copied from the legacy shoutbox.

Shoutbox with Smiley Farm

That was a long post but with these pretty simple pieces in place I now have smilies for the shoutbox and other applications to use!

In the next post I’ll show how I got the edit-in-place functionality working.

After getting the model and admin parts working (discussed in part 2), I turned to the view and template. I decided to create an inclusion tag for the shoutbox. My site’s base template will then use the tag to display the shoutbox on every page of the site.

Writing the inclusion tag itself was pretty easy. All I need to do is retrieve the last 10 shouts and render a template with the results. So, after studying the Django docs, I created my templatetags sub-directory, the obligatory empty __init__.py file, and my shoutbox_tags.py file, which contained this code:

from django import template
from shoutbox.models import Shout

register = template.Library()

@register.inclusion_tag('shoutbox/shoutbox.html', takes_context=True)
def shoutbox(context):
   shouts = Shout.objects.all()[:10]
   return {
      'shouts': shouts,
      'user': context['user'],
   }

I’m using the newer Python decorator syntax here. The first argument to the inclusion_tag decorator function is the name of the template I am going to render. The needs_context argument set to True says that I will want to access the context. The reason for this is I want to display a form for authenticated users, so I will need to query the user variable from the context for that.

All I do here is retrieve the last 10 shouts, then return a dictionary that will be fed to my template.

Now to write the actual template itself. I wrote this template in a series of “baby-steps”, which is my usual mode of operation. My steps were as follows:

1. Write code that only displays the shouts as paragraphs inside a div tag.
2. Played with the styles and wrote css to make it look decent.
3. Got the form post working with the view function.
4. Got the thing to scroll by leveraging some 3rd party javascript.

I should show you the template at each step, but I’m writing this after the fact, and it really didn’t change that much from beginning to end. I’ll present the final version here and discuss it.

{% extends 'side_block.html' %}
{% block block_title %}Shoutbox{% endblock %}
{% block block_content %}
{% if shouts %}
<div id="marqueecontainer" onmouseover="copyspeed=pausespeed" onmouseout="copyspeed=marqueespeed">
<div id="vmarquee" style="position: absolute; width: 98%;">
   {% for shout in shouts reversed %}
      <p>
      <span class="shoutbox-user">{{ shout.user.username }}:</span>
      <span class="shoutbox-shout">{{ shout.shout|urlizetrunc:15 }}</span>
      <span class="shoutbox-date">{{ shout.shout_date|date:"D M d Y H:i:s" }}</span>
      </p>
   {% endfor %}
</div>
</div>
{% endif %}
<center><a href="{% url shoutbox-view page=1 %}">Shout History</a></center>
{% if user.is_authenticated %}
<center>
<form action="{% url shoutbox-shout %}" method="post">
   <input type="text" maxlength="2048" size="20" name="msg" value="" />
   <br />
   <input type="submit" value="Shout" />
</form>
</center>
{% else %}
<p>Please login or register to shout.</p>
{% endif %}
{% endblock %}

First of all, this template extends another called side_block.html. I decided that all my “blocks” will have common styling and features, and I will collect that information there. This template will provide values for the block title and block content.

Lines 4-16 display the 10 latest shouts. The two divs are needed for the javascript scrolling, which I’ll explain in a minute, so you can ignore them for now. The for loop is the real action here. I simply loop over the shouts, producing a paragraph for each one. The ordering we setup for the shouts in the model is reverse chronological order. On the current SG101 site, the legacy shoutbox scrolls up, displaying the oldest of the 10 shouts first. To achieve this, we use the nifty reversed keyword on the for loop, which gives me exactly what I want.

The other interesting thing in the loop is the use of the urlizetrunc filter. As you may recall from part 1, one of my requirements is to minimize or truncate URL’s. I headed down the path of writing my own function to do this, and spent about half hour on it, trying to come to terms with Django’s escaping protocol, when it suddenly occurred to me that I can’t be the first person who had a use-case for this. So I quickly scanned the Django filter documentation, and sure enough, a function close enough to what I wanted was already in the can! The legacy shoutbox shortens URLs by simply displaying them as the text [URL]. The urlize filter doesn’t do this, but urlizetrunc is close enough to what I need that I used it as-is. It simply truncates URLs after a certain length.

The last half of the template decides whether to display a shout form to the user, depending on whether she is authenticated or not. If not authenticated, I simply display a reminder to login or register (hmm, I need to make those links to the appropriate pages). If authenticated, I display the shout form. I could have used a Django form here; perhaps the inclusion tag could have passed it to the template. However, the form is so simple I didn’t even bother. All I need is one text input and a submit button, which I would have had to write anyway.

I will now show you the view function that this form posts to. It is quite simple.

@login_required
def shout(request):
    if request.method == 'POST':
        msg = request.POST.get('msg', '')
        if msg != '':
            shout = Shout(user=request.user, shout=msg)
            shout.save()

    return HttpResponseRedirect(request.META.get('HTTP_REFERER', '/'))

The first thing to notice is I have decorated my view function with the login_required decorator. This ensures only registered users can shout. Sure, we only display the form to registered users, but that doesn’t stop someone from crafting their own form and posting to the same URL. I then pull the msg out of the POST Querydict, and let it default to the empty string if it isn’t there. If the msg isn’t empty, I create and save a new Shout object, recording the user that made it and the msg value. As you may recall, the shout_date field will be automatically initialized to the current date and time by Django when I save the new shout. I then redirect to the same page the user was looking at (recall that the shoutbox will appear on every page of the site). If this can’t be determined (which normally should not happen) I simply go to the site root.

With this machinery in place, I was able to submit shouts just like the current (legacy) shoutbox on SG101. Sweet! This was fun, but now it gets even better. How to make it scroll?

I had no interest in writing the scrolling code, so I spent a little while googling. I did not consider reusing the legacy shoutbox javascript, as it required the javascript to be sent with the page (it was dynamic), and the code wasn’t properly escaped and broke XHTML compliance. I really want to learn more about the jQuery library, and I did look for a jQuery plugin for this task. However I decided to save jQuery for another day, and found some nice code on the venerable Dynamic Drive website. This code was similar to the legacy shoutbox code, so I was comfortable with it. I liked it because it simply scrolled a div upwards, and required no inline javascript. I think the legacy shoutbox script must have used an earlier version of this same script because it was so similar. To integrate this with my template code, I simply had to wrap my shouts inside 2 divs, and include the javascript in my site’s base template. And wow it worked on the first try, much to my surprise. I was smiling at how quickly this came together.

Wow, we have nearly all the functionality that I wanted completed already. All that is left is the ability to review the shout history, and let users edit and delete their shouts. I completed the shout history portion, so I will show that in the next post. For editing and deleting, I think I might want to do something AJAX-y and let the user edit the shout in-place. Hmmm, maybe I will learn some jQuery to make that easier. And maybe then I can rewrite the scrolling with jQuery. More to come!

For the shoutbox app, we need a very simple model. Here is my models.py file:

from django.db import models
from django.contrib.auth.models import User

class Shout(models.Model):
   user = models.ForeignKey(User)
   shout_date = models.DateTimeField(auto_now_add=True)
   shout = models.TextField()

   def __unicode__(self):
      shout = self.shout[:60]
      return u'Shout from %s: %s' % (self.user.username, shout)

   class Meta:
      ordering = ('-shout_date', )

There is nothing too out of the ordinary here. Each shout was made by a registered user, so we need a ForeignKey to the User table. We record the date and time the shout was made (using auto_now_add initializes this field for us when the object is saved), and finally the shout itself is just a TextField.

The __unicode__ function will be used in the admin interface. Here we just show who the shout is from and then a truncated version of the shout. Finally, we can tell Django our default ordering of Shouts is in reverse chronological order via the ordering attribute in the embedded Meta class.

Now we turn to the admin.py file to enable and configure an automatic admin interface for Shouts. Again, this is an amazing feature of Django that really sold me on the idea of trying this framework out.

from django.contrib import admin
from shoutbox.models import Shout

class ShoutAdmin(admin.ModelAdmin):
   list_display = ('shout_date', '__unicode__')
   raw_id_fields = ('user', )

admin.site.register(Shout, ShoutAdmin)

Here we derive a class from Django’s admin.ModelAdmin class to configure our admin interface. Our main display listing should consist of two columns: the shout_date and then the __unicode__ representation of each Shout. This will invoke the __unicode__ member function on each Shout object displayed.

Here I am using the raw_id_fields feature for the first time. Since I have over 2000 users currently on SG101, I do not want to load all that information into a select box everytime I drill into a Shout. The raw_id_field simply displays the raw user id along with the username. If I really want to change the user, the field has a pop-up control to allow me to load all the usernames. I should have done this on a few other applications I previously wrote. This is the constant refactoring I wrote about earlier.

And that’s it! After running syncdb I can now add Shouts to the database via the admin interface, all in less than 25 lines of code from me! In part 3 I will show how I display the shoutbox as a “block” (to borrow the PHP-Nuke term) on the website. To do this, I created one of my first Django template tags and incorporate some 3rd party javascript to accomplish the scrolling of the shouts. Stay tuned.

The current site is using a shoutbox script developed by the now defunct ourscripts.net site. The script was obviously a labor of love by the original developer, but to my taste it is over-engineered and somewhat heavy handed in terms of resources it uses. It is highly configurable; it has admin options for changing the style (theme), user banning, IP banning, a bad word filter, configurable emoticons, etc. After running this script for over two years now I think I really only need the following features.

1. Only registered users can shout.
2. Shouts should scroll (users love this for some reason).
3. Any URLs in the shout should be made clickable (and preferably shortened or truncated).
4. Emoticons (smilies) are absolutely required.
5. Shout history should be displayable.
6. Users should be able to edit or delete their shouts in the history.
7. XHTML compliant (the current script is not).
8. The admin should be able to edit and delete shouts.

And that’s basically it. I may decide to have the thing auto-prune shouts, as Django doesn’t currently have a bulk delete feature in the auto-generated admin interface (but that is coming in Django 1.1).

I’m going to be using emoticons in other comment and forum applications all over the site, so thinking ahead here, it is probably best to create that functionality in a separate Django application that the shoutbox will use.

Okay, in keeping with my limited time and my new attempt to blog more but in more manageable pieces, I’ll stop here. The next few posts will detail the stages of development of this application.