Table of contents for Django Development with Djblets

1. Django Development with Djblets
2. Django Development with Djblets: Custom Tag Helpers
3. Django Development with Djblets: Unrooting your URLs

Typically, Django sites are designed with the assumption that they’ll have a domain or subdomain to themselves. Often times this is fine, but if you’re developing a web application designed for redistribution, sometimes you can’t make that assumption.

During development of Review Board, many of our users wanted the ability to install Review Board into a subdirectory of one of their domains, rather than a subdomain.

There’s a few rules that are important when making your site relocatable:

• Always use MEDIA_URL when referring to your media directory, so that people can customize where they put their media files.
• Don’t hard-code URLs in templates. Use the {% url %} tag or get_absolute_url() when possible.

These solve some of the issues, but doesn’t address relocating a Django site to a subdirectory.

Djblets fills in this gap by providing a special URL handler designed to act as a prefix for all your projects’ URLs. To make use of this, you need to modify your settings.py file as follows:

settings.py

TEMPLATE_CONTEXT_PROCESSORS = (
    ...
    'djblets.util.context_processors.siteRoot',
)
 
SITE_ROOT_URLCONF = 'yourproject.urls'
ROOT_URLCONF = 'djblets.util.rooturl'
 
SITE_ROOT = '/'

SITE_ROOT specifies where the site is located. By default, this should be “/”, but this can be changed to point to any path. For example, “/myproject/”. Note that it should always have a leading and a trailing slash.

The custom template context processor (djblets.util.context_processors.siteRoot) will make SITE_ROOT accessible to templates.

SITE_ROOT should be used in templates when you need to refer to URLs that aren’t designed to respect SITE_ROOT (such as User.get_absolute_url). Your own custom applications should always respect SITE_ROOT whenever providing a URL.

ROOT_URLCONF is typically what you would set to point to your project’s URL. However, in this case, you’ll be pointing it to djblets.util.rooturl. This in turn will forward all URLs to your project’s handler, defined in SITE_ROOT_URLCONF.

This is all you need to have a fully relocatable Django site!

To sum up:

1. Add djblets.util.context_processors.siteRoot to your TEMPLATE_CONTEXT_PROCESSORS.
2. Set SITE_ROOT_URLCONF to your project’s URL handler.
3. Set ROOT_URLCONF to ‘djblets.util.rooturl’
4. Prefix any URLs with SITE_ROOT in your templates, unless the URL would already take SITE_ROOT into account.

This is functionality that will hopefully make its way into Django at some point. For now, you have an easy way of unrooting your Django project.

Table of contents for Django Development with Djblets

1. Django Development with Djblets
2. Django Development with Djblets: Custom Tag Helpers
3. Django Development with Djblets: Unrooting your URLs

I’m planning to cover all of what Django can do, but for now, let’s start simple with something most Django developers spend way too much time creating: Custom tags.

Django’s nice enough to provide a @register.simple_tag decorator for creating very basic tags that don’t take a context but do take parameters. This is great, but what if you want more? Many Django applications use the same boilerplate time and time again to create their tags, but we make it much easier.

Introducing @basictag and @blocktag.

@basictag

Ever wanted to use Django’s @register.simple_tag but needed access to the context? I’ve found far too many cases where this would be useful, but Django doesn’t make this easy. Your tag code would end up looking like this:

class MyTagNode(template.Node):
    def __init__(self, arg1, arg2):
        self.arg1 = arg1
        self.arg2 = arg2
 
    def render(self, context):
        arg1 = Variable(self.arg1).resolve(context)
        arg2 = Variable(self.arg2).resolve(context)
 
        return context['user']
 
@register.tag
def mytag(parser, token):
    bits = token.split_contents()
    return MyTagNode(bits[1], bits[2])

Do this a few times and it’s bound to drive you nuts. How about this instead?

from djblets.util.decorators import basictag
 
@register.tag
@basictag(takes_context=True)
def mytag(context, arg1, arg2):
    return context['user']

Far less code and increased readability. Hooray!

@blocktag

@blocktag aims to do the same thing @basictag does but for block tags. A block tag is a tag that contains nested content, like @spaceless or @for. This usually requires even more boilerplate than the above code fragment, except with the added complexity of having to grab the contents of the block.

We’ve condensed it down to this:

from djblets.util.decorators import blocktag
 
@register.tag
@blocktag
def blinkblock(context, nodelist, arg1, arg2):
    return "<blink>%s</blink>" % nodelist.render(context)

If you’ve built block tags in the past, you’ll appreciate how simple that was.

Table of contents for Django Development with Djblets

1. Django Development with Djblets
2. Django Development with Djblets: Custom Tag Helpers
3. Django Development with Djblets: Unrooting your URLs

Django is an awesome development platform for web applications. With such features as database abstraction, template/view/url separation, built-in authentication with interchangeable backends, it’s made web development much more enjoyable.

We use Django in Review Board with much success. Over time, as we’ve come to develop new features, we realized that much of our codebase was useful outside of Review Board and, bit by bit, moved pieces into a library we call Djblets.

What does Djblets do?

A bit of everything, really. Any time we have useful functionality that isn’t tied to Review Board, we put it here.

Djblet’s feature list currently consists of:

• Authentication improvements, making it easy to register and login in one step, seamlessly, handle password recovery, and more.
• Flexible datagrids for displaying data in a paginated list with user-specific column customization, ordering and sorting.
• Decorators to drastically simplify creation of simple and block template tags.
• Caching functions for calling a function and caching the result if the data isn’t already in the cache, and a special URL pattern matcher that prevents caching of any contained URLs.
• Unit testing utility classes.

And of course more little things here and there.

Downloading Djblets

Djblets is not a released app, but it’s pretty stable and well tested. You can check out a copy from our SVN repository, or automatically include it in your own repository through an svn:externals entry.

Djblets is licensed under the MIT license, making it usable in most projects.

Using Djblets

Over time I’ll be writing articles on using the many features of Djblets. See the other posts in the series, or dig around the Djblets source code.

• Total bugs open: 25
• Total bugs fixed: 186
• Feature requests open: 43
• Companies known to be using Review Board: at least 23

Review Board has matured in recent months and has a very nice feature set. More and more we’re seeing and hearing about companies using it in one or more teams. I was even lucky enough to talk about it in the official Django Book.

Development shows no sign of stalling. Our feature request list is a mile long, and our personal TODO lists are longer still. We’ve implemented so many new features and fixed so many bugs that I can’t even list them all, but let’s take a look at the highlights.

New Top-Level Features

• iPhone support. Basic read-only iPhone support was added. It’s more of a proof of concept and to make sure our codebase handles different UIs on top of it, but if your Review Board server is accessible from your iPhone, point Safari to /iphone/ for some fun.
• Status Reports. Basic support for status reports have been added. While we don’t have a fleshed out UI in place, the /reports/ URL will give you simple reports showing which review requests you’ve reviewed, and other bits of information. This can even be presented in Wiki format!

Revision Control Systems Integration

• Mercurial support. One of our contributors has written support for doing review requests against Mercurial repositories. This supports local and remote repositories.
• Git support. Basic Git support was written as well. It only works with local Git repositories (as it has to have access to .git directories).

Diff Viewer

• Improved diff parser. We no longer require third party tools in order to parse diff files. We can do it ourselves faster and with greater flexibility. This has given us some speed advantages, reduced the hacks needed, and improved diff compatibility.
• Interdiffs. Review Board can now display the differences between two revisions of a diff. This makes it much easier to review several iterations of large changes spanning many files.
• Fixed diff line numbers. Line numbers in the diff viewer used to be artificial. They were essentially table row numbers. Now line numbers on the left-hand side of the diff viewer represent the actual line numbers in the original file, and line numbers on the right represent the new file.
• “Review” link. Added a “Review” link on the diff viewer and screenshot page for bringing up the Review dialog. Previously users had to click a link on the diff viewer regardless of whether they were leaving a comment on the diff.

Reviews

• Show commented screenshots on reviews. Portions of a screenshot that the user has commented on will appear in the review body, much like diff fragments do. This greatly improves the review process when it comes to screenshots.
• Updated diffs create a new draft. Newly updated diffs used to instantly appear and send out an e-mail, which was annoying if you realized you needed to change and re-upload the diff again. Now updating the diff just creates a draft, if one doesn’t already exist. The diff won’t show up or spam users until you’re ready for it to.
• Auto-completion for reviewers. The reviewer lists now have support for auto-completion of group names and usernames. As you’re typing, a list of choices based on the current text will appear. Navigating with the arrow keys or hitting Tab will auto-complete the selected entry.
• Default reviewers. Administrators can now specify default reviewers for file paths (as defined by a regular expression). This allows certain groups to “own” files or paths and to be included on the reviewers list any time a diff touching those is uploaded.
• Improved page banners. The draft banner at the top of the review request page has been improved and is now more clear. No longer do you have to save a draft and then publish it. It’s now one single button on the banner. We also added “discarded” and “submitted” banners.
• Alpha-numeric bug numbers. Not all bug trackers use numeric-only bug identifiers. We now support alpha-numeric bug numbers.

Dashboard and Review Request Lists

• Starred review requests and groups. Users can now “star” a review request they wish to keep track of in their dashboard. They’ll be placed on the CC list and see changes in the dashboard. Users can also star a group in order to add it to their “Watched Groups” list in the dashboard.
• Toggle display of submitted review requests. The “All Review Requests” page can now filter out submitted review requests via a toggleable “Show/Hide Review Requests” link.
• Customizable columns. The various lists pages and the dashboard now support customizable columns. There are non-default columns that can be added to the view to show extra data, and existing columns can be removed. If you prefer all dates to be relative or absolute, just add the right columns. Furthermore, columns can be reordered simply by dragging them into the desired order.
• New dashboard column types:
  • New Updates. This column shows a speech bubble icon when new discussions have taken place on a review request since the user last visited it.
  • Ship It. This column makes it easy to see if anybody has marked the review request as “Ship It!”
  • Absolute/relative timestamps. Users wishing to see only relative or absolute timestamps in the dashboard can add the Last Updated/Posted Absolute or Relative timestamp columns.
  • Number of Reviews. Sometimes it’s handy to see how many reviews have been made to a review request. This column provides that number.
  • Starred. Allows users to star/unstar a review request or group. This is like adding yourself to a CC list.

post-review

• Upload diffs from a revision range. –revision-range has been added to allow for uploading diffs from a range of revisions on the server. This is currently only implemented for SVN.
• Specify a default summary. –summary has been added to provide a default summary for the review request.
• Open a browser after uploading. –open has been added to open a browser to the new review request.

Distribution/Installation

• make install. It’s now trivial to create a Review Board tarball or to install it on your system. We integrate with autoconf/automake to generate the Makefiles and sample/default configuration files. This brings us a giant step closer to putting out releases.

What’s Next?

We have several things in the works. A couple of the major highlights would be a search interface and support for 3rd party extensions to Review Board. Stay tuned!