My personal fork of django-tumbleweed
Pull request Compare This branch is 9 commits ahead of mcroydon:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Tumbleweed allows you to easily create a tumbleog by taking advantage of data already denormalized in Haystack. Tumbleweed runs quite slowly under Whoosh but is quite quick using Solr.

Getting started

The quickest way to get started with tumbleweed is to download tumbleweed, make sure it is on your PYTHONPATH, and add it to your INSTALLED_APPS:


Once in your INSTALLED_APPS, add the default tumbleweed urlconf to your main urlpatterns in your project's

urlpatterns = patterns('',
    (r'tumble/', include('tumbleweed.urls')),

The main tumble view will now be available at /tumble/. Tumbleweed also includes paginated date-based tumble views:

  • /tumble/2009/
  • /tumble/2009/jan/
  • /tumble/2009/jan/01/

Pagination can either be supplied as part of the URL or as a GET-parameter.

  • /tumble/2009/page/2/
  • /tumble/2009/?page=2

If you have /admin/doc/ enabled in your root urlconf, each of the tumbleweed views is documented.

Tumbleweed philosophy

Tumbleweed is less of a tumblelog app and more of a tumblelog framework. In order to use tumbleweed, you need a collection of Haystack SearchIndexes that share as much common information as possible. For example, most objects that you might want to tumble (blog posts, links, photos, tweets) should have at least a title, a publication date, and a tease/description. If you ensure that each of your SearchIndexes contains at least that much information as fielded data, you can access those fields from your tumble views without having to hit the database at all.

Extending default behavior

Tumbleweed ships with sane defaults but like Django's generic views and Haystack's search view, there are many points for extension.

By default, the tumble view looks for a field on your SearchIndexes called pub_date. If you have called the date field that you would like to tumble by in your view something else, you can pass date_field in either as a dictionary in a urlconf or by calling the view with a date_field argument.

The default template of tumbleweed/tumble.html can also be overridden by overriding template_name.

You can also influence what results are returned by the tumble view by passing a keyword argument called searchqueryset in. For example, if your indexes have an is_public field, you could show public items only by modifying your

from haystack.query import SearchQuerySet
tumble_dict = {'searchqueryset' : SearchQuerySet().filter(is_public__exact=True)}

urlpatterns = patterns('',
    (r'tumble/', include('tumbleweed.urls'), tumble_dict),

You can also influence how many items are tumbled on each page by passing in a paginate_by keyword argument. If paginate_by is not included, tumbleweed will check for TUMBLEWEED_RESULTS_PER_PAGE in your settings file, or will fall back to a default of 20.

If you have a custom Context class, you can also pass that in as context_class.

Finally if you would like to add something to the tumble context, you can do so by passing a dictionary in as extra_context, much like Django's generic views.

Tumbleweed's date-based views are just thin wrappers around the main tumble view and show how to customize the tumble view.

Tumbleweed template tag

Tumbleweed also has a template tag for retrieving latest tumbles:

{% load tumbleweed %}
{% get_latest_tumbles 5 as latest_tumbles %}

{% for tumble in latest_tumbles %}
    {{ tumble.title }}
{% endfor %}

By default the tag will sort the tumbles using the field pub_date, but you can override this with the setting TUMBLEWEED_TEMPLATETAG_DATE_FIELD:


You can filter the query with TUMBLEWEED_TEMPLATETAG_FILTER:

TUMBLEWEED_TEMPLATETAG_FILTER = {'title__exact': 'Hello world!'}


TUMBLEWEED_TEMPLATETAG_EXCLUDE = {'title__exact': 'Hello there.'}


  • Further documentation
  • Tumble template tag
  • Tests


Tumbleweed is released under the new-style BSD license.