From 2012 DJFacet development has moved to http://bitbucket.org/magicrebirth/djfacet/

Please check there for the latest version of the code. This gCode site will continue to be used for community management, support and downloads.

Summary

Django Faceted Browser is a django application that allows you to navigate your data using an approach based on 'dynamic taxonomies', also called 'facets'. Faceted navigation is arguably the most significant search innovation of the past decade, and it's being used by many sites like Amazon or Ebay in order to allow users to quickly get a feeling for the type of objects available in a datastore (check out this article on AlistApart if you don't know what this is all about).

Django's model layer is already doing a great job in abstracting away unnecessary complexity when you develop a web app; so I thought it'd be nice to have a generic faceted browser app for django that took advantage of this feature. Other faceted browsers exist out there, but after some analysis I realized that all of them were not easy to reuse, and most importantly, not compatible with Django: so here we go, DJFacet!

Current version: 0.9.1

In the making: 0.9.2

Documentation and Demo

The official sphinx-generated documentation can be found here. Also, here is a demo application that lets you browse a sample dataset about religions and associated countries.

Installation

Prerequisite libraries

Obvioulsy, you need to have Django installed. DJFacet 0.9 is compatible with Django 1.1+; future versions will be tested only on Django 1.3 only.

Also, the Picklefield library needs to be installed (or anyway, locatable via your PYTHONPATH setting)

1. Download and unpack the application

Download the latest version of DJFacet from the 'download' section of this site.

Expand the package just downloaded and put it in a suitable location. This can be the same folder as the django project you're working on, or any other location, as long as it is in your PYTHONPATH:

$ tar xfz djfacet-VERSION.tar.gz
$ cp -r djfacet /path/to/my/project/

2. Set up the templates directory

DJFacets includes some default templates, which need to be made accessible by putting them where Django can find them. To this purpose, you must copy the folder named djfacet inside your project's templates directory (usually defined via Django's TEMPLATE_DIRS setting)::

$ cd /path/to/my/project/djfacet
$ cp -r templates/djfacet /path/to/my/project-templates/

Alternatively, you can just create a symlink:

$ ln -s templates/djfacet /path/to/my/project-templates/

3. Set up the media directory

Do the same operation as above with DJFacet's built-in static files (css, js). Copy the folder named `djfacet, located inside the static of DJFacet distribution, to your project's media folder (usually defined via Django's MEDIA_ROOT` setting), or create a symlink:

$ cd /path/to/my/project/djfacet
$ cp -r static/djfacet /path/to/my/project-media-files/

Alternatively, create a symlink::

$ ln -s static/djfacet /path/to/my/project-media-files/

4. Add the application to your project

Add the DJFacet app to your project's settings.py:

INSTALLED_APPS += (	
	'picklefield',      # REQUIRED
	'djfacet',          # REQUIRED
)

Now run the syncdb command. DJFacet will create 3 new tables, which are used by the caching system::

$ python manage.py syncdb
Creating table djfacet_cachedfacetquery
Creating table djfacet_cachedfacetvalue
Creating table djfacet_cachedfacetedmanager

5. Wire up the application

Add the DJFacet app to your urls definitions in urls.py:

urlpatterns += patterns('',
	(r'^browser/', 'djfacet.urls'), # change "browser" to whatever you like!
)

Once that works, congratulations! You’ve successfully installed DJFacet. Now it's time to proceed to its configuration.

Example of facet configuration

The configuration file is a standard python module, whose location is defined by the DJ_SPECS_MODULE setting (by default, DJFacet will look for a file called facetspecs.py at the root of your django project).

For example, the facet definition for the 'Region name' facet in the demo application looks like this:

	facetslist = [  
			{'appearance' : {	
					'label' : 'Region name' , 
					'uniquename' : 'regionname',
					'model' : Region , 
					'dbfield' : "name", 
					'displayfield' : "name", 
					'explanation': "no explanation yet",
					'grouping'	: ['countrygroup'],
					'ordering' : 'extended_name',
						} ,
			'behaviour' :  [{
					'resulttype' : 'religions',
					'querypath' : 'country__inregion__name', 

						},
					{
					'resulttype' : 'country',
					'querypath' : 'inregion__name', 

						},
					]},  
				]

Easy uh? Please check the official documentation to find out all that you need to know to configure your facets and information space!

If you're familiar with the models in your application, configuring DJFacet won't take you a long time. However you'll see that each facet you add requires a bit of thinking (and testing too), in order to make sure the queries it produces are what you want. Finally, remember that Django's interactive shell is perfect for testing things out!