Allow setting properties in context; Document properties and events.

AUTHORS.rst

@@ -1,5 +1,9 @@
-The django-analytical package is was written by `Joost Cassee`_, with
-contributions by `Eric Davis`_.
+The django-analytical package was written by `Joost Cassee`_, with
+contributions from:
+
+`Eric Davis`_
+`Paul Oswald`_
+and others.
 
 Included Javascript code snippets for integration of the analytics
 services were written by the respective service providers.
@@ -13,3 +17,4 @@ The work on Crazy Egg was made possible by `Bateau Knowledge`_.
 .. _`Eric Davis`: https://github.com/edavis
 .. _Analytical: https://github.com/jkrall/analytical
 .. _`Bateau Knowledge`: http://www.bateauknowledge.nl/
+.. _`Paul Oswald`: https://github.com/poswald

analytical/templatetags/kiss_metrics.py

@@ -34,7 +34,10 @@ TRACKING_CODE = """
 """
 IDENTIFY_CODE = "_kmq.push(['identify', '%s']);"
 EVENT_CODE = "_kmq.push(['record', '%(name)s', %(properties)s]);"
+PROPERTY_CODE = "_kmq.push(['set', %(properties)s]);"
+
 EVENT_CONTEXT_KEY = 'kiss_metrics_event'
+PROPERTY_CONTEXT_KEY = 'kiss_metrics_property'
 
 register = Library()
 
@@ -70,6 +73,12 @@ class KissMetricsNode(Node):
                     'properties': simplejson.dumps(properties)})
         except KeyError:
             pass
+        try:
+            properties = context[PROPERTY_CONTEXT_KEY]
+            commands.append(PROPERTY_CODE % {
+                    'properties': simplejson.dumps(properties)})
+        except KeyError:
+            pass
         html = TRACKING_CODE % {'api_key': self.api_key,
                 'commands': " ".join(commands)}
         if is_internal_ip(context, 'KISS_METRICS'):

docs/services/kiss_metrics.rst

@@ -9,7 +9,6 @@ many drop out at each stage.
 
 .. _KISSmetrics: http://www.kissmetrics.com/
 
-
 .. kiss-metrics-installation:
 
 Installation
@@ -108,3 +107,41 @@ a context processor that you add to the
 Just remember that if you set the same context variable in the
 :class:`~django.template.context.RequestContext` constructor and in a
 context processor, the latter clobbers the former.
+
+.. _kiss-metrics-event:
+
+Recording events
+----------------
+
+You may tell KISSmetrics about an event by setting a variable in the context.
+
+For example::
+
+    context = RequestContext({
+        'kiss_metrics_event': ['Signed Up', {'Plan' : 'Pro', 'Amount' : 9.99}],
+    })
+    return some_template.render(context)
+
+The output script tag will then include the corresponding Javascript event:
+
+    _kmq.push(['record', 'Signed Up', {'Plan':'Pro', 'Amount':9.99}]);
+
+
+.. _kiss-metrics-properties:
+
+Recording properties
+--------------------
+
+You may also set KISSmetrics properties without a corresponding event.
+
+For example::
+
+    context = RequestContext({
+        'kiss_metrics_property': {'gender': 'Male'},
+    })
+    return some_template.render(context)
+
+The output script tag will then include the corresponding Javascript event:
+
+    _kmq.push(['set', {'gender':'Male'}]);
+