Update to API based on review of use cases, and addition of a metacla…

…ss to FacetGroup, to make definitions easier. Some storage stuff, unused as yet.

.gitignore

@@ -1,7 +1,7 @@
 *.swp
 *~
 *.pyc
-/project_sample/project_sample.db
 /docs/_build/
 *.DS_Store
-glamkit_eventtools.egg-info
+glamkit_facettools.egg-info
+.idea

README.rst

@@ -6,49 +6,47 @@ A tool for dealing with facets in collections. It is part of the `GLAMkit projec
 
 View a full list of `GLAMkit components <http://docs.glamkit.org/components/>`_.
 
-approach
+Approach
 ==========
 
-Facets present ways of narrowing down an item selection, by showing what the options are, and how many results will be produced.
+Facets present ways of narrowing down an item selection, by showing what the
+options are, and how many results will be produced.
 
-This module does most of the legwork in setting up facets for Django models.
+This module does most of the legwork in setting up facets for collections.
 
-The emphasis is on flexibility and ease of use. There is not much speed optimisation as yet (so cache heavily!)
+The emphasis is on performance, at the occasional expense of memory.
 
 Refer to tests.py for more examples of behaviour.
 
 Overview
 --------
-A facet item contains the information necessary to render a single facet option, as part of a list or drop-down.
+A `FacetGroup` is an ordered set of `FacetField`s on a particular collection.
 
-FacetItems are generated by FacetFactories, of which there are a few different types provided. For more complex facets, you can define your own FacetFactories.
+A `FacetField` is an ordered set of `FacetValue`s, plus a heading.
+
+A `FacetValue` contains the information necessary to render a single facet
+option, as part of a list or drop-down.
 
 Setting up a simple facet
 -------------------------
-Let's say you have an Event model that allows the number of acts to be recorded:
+Let's say you have an Event model that you want to facet on the type of
+event, and whether or not it is free:
 
     class Event(models.Model):
         title = models.CharField(max_length=100)
-        num_acts = models.IntegerField()
-
-To facet on the number of acts, you create an ActsFacet:
+        is_free = models.BooleanField()
+        type = models.ManyToManyField(EventType)
 
-    class NumberFacet(FacetFactory):
-        pool = Event.objects.all()
-        GET_key = "acts"
-        model_field = "num_acts"
+		class EventFacetGroup(FacetGroup):
+				type = facetfields.FacetField()
+				is_free = facetfields.BooleanFacetField()
 
-Where:
-
-    `pool` is the queryset of django objects that the facet operates on. You might want to change this to all 'published' items.
+				def queryset(self):
+						return Event.objects.all()
 
-    `GET_key` is the key of the request's GET dictionary that this facet affects.
+		efg = EventFacetGroup()
 
-    `model_field` is the field of the pool to facet on.
-
-To facet all events by the number of acts, you simply call:
 
-    NumberFacet().get_facets()
 
 Which generates all the FacetItems, starting with "All" items.
 

TODO.txt

@@ -0,0 +1,2 @@
+Generate a sentence based on selected facets
+Allow class hierarchies of FacetGroup, to inherit facets that behave similarly.