08 Dec 08 Anatomy of a Shoutbox; Part 3 – View & Template

And now we continue on with the shoutbox development. If you missed the earlier posts, here they are: part 1, part 2.

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!

Tags: django, sg101, shoutbox

07 Dec 08 Anatomy of a Shoutbox; Part 2 – Model and Admin

One of the things that really attracted me to Django was that it has an ORM. Of course I had never seen an ORM before and didn’t even know that term until later. An ORM (Object-Relational Mapping) allows you to seamlessly create Python objects from database tables, and vice versa. So you never have to code your own SQL unless you really want to do something fancy.

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.

Tags: django, sg101, shoutbox

02 Dec 08 Anatomy of a Shoutbox; Part 1- Requirements

One of the applications from the current SG101 website I want to bring over is the shoutbox. Shoutboxes are very popular in the Nuke community, and I was very surprised at how much my users took to it. It may very well be the 2nd most popular application after the forums. It is kind of a community Twitter for the site (hmmm did the Twitter guys get the idea for Twitter from the lowly shout box?).

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.

Tags: django, sg101, shoutbox