Retrieve activity granularity

DOCS.md

@@ -119,7 +119,8 @@ groucho.config = {
   ]
 }
 ```
-To write your own features, grab browsing history and work with it like this...
+
+To write your own features, grab browsing history and work with it. You'll need to use a little structure to define the condition, in this case: the name of the tracking group...
 
 ```javascript
 $.each(groucho.getActivities('browsing'), function (key, record) {
@@ -270,45 +271,65 @@ var favCategoryTerms = groucho.getFavoriteTerms('*', false, 7);
 You can register your own tracking activities like this...
 
 ```javascript
-// Track your own activities.
-$('.my-special-links').bind('click', function (e) {
-  myObj.linkText = $(this).text()
-  myObj.myProperty = $(this).attr('data-property');
-  groucho.createActivity('my_activity', myObj);
+$('.videos a.play').bind('click', function() {
+  groucho.createActivity('watch', {
+    'videoId' : $(this).data('videoId'),
+    'category' : $(this).data('category'),
+    'videoTitle' : $(this).text()
+  });
 });
 ```
-They will be stored as key/value in jStorage. But can be returned as an array, filtered down to the group specified.
+They will be stored as key/value in jStorage. But can be returned as an array, filtered down to the group specified. Remember to structure the condition.
 
 ```javascript
-var myActivities = groucho.getActivities('my_activity');
+var myActivities = groucho.getActivities('watch');
 ```
+
 ```json
 [{
-  "_key" : "track.my_activity.398649600",
-  "linkText" : "Link text from page",
-  "myProperty" : "the-property-value"
+  "_key" : "track.watch.398649600",
+  "videoId" : 456,
+  "category" : "tutorial",
+  "videoTitle" : "Learn About Something"
 }, {
-  "_key" : "track.my_activity.398649999",
-  "linkText" : "Other link text",
-  "myProperty" : "this-property-value"
+  "_key" : "track.watch.398649999",
+  "videoId" : 789,
+  "category" : "fun",
+  "videoTitle" : "Be Entertained"
 }]
 ```
-You can work directly with tracking activites and create your own smart functions...
+You can work directly with tracking activites and create your own smart functions. This example finds tutorial videos watched in the last week...
+
 
 ```javascript
-function myActivitySmarts () {
-  var myActivities = groucho.getActivities('my_activity'),
-      record;
-
-  for (i in myActivities) {
-    record = myActivities[i];
-    if (myComparison(record.property, record.url, record._key.split('.')[2])) {
-      count++;
+function recentVideos(timeframe, category) {
+  var conditions = [{'type' : [category]}],
+      activityList = groucho.getActivities('watch', conditions),
+      now = new Date().getTime(),
+      recentList = [],
+      timestamp;
+
+  for (var i in activityList) {
+    timestamp = activityList[i]._key.split('.')[2]);
+    if (timestamp > (now - timeframe)) {
+      recentList.push({
+        'videoTitle' : activityList[i].videoTitle,
+        'url' : activityList[i].url
+      });
     }
   }
-  return count;
+
+  return recentList;
 }
+
+$.each(recentVideos(604800, 'tutorial'), function() {
+  newItem = '<li><a href="' + this.url + '">' + this.videoTitle + '</a></li>';
+  $('ul.recentlyWatched').append(newItem);
+});
 ```
+_...but you shouldn't insert HTML this way._
+
+
 
 ### Local Storage
 This library uses in-browser key/value localStorage with the convenient jStorage abstraction library. If you're new to localStorage, it's no big deal and is a new tool we should all be using.

README.md

@@ -100,11 +100,11 @@ if (groucho.favoriteTerms.hasOwnProperty(taxonomy)) {
 ### Pageview Tracking
 
 Use page view activity tracking to dig through history and alter UX.
-
 ```javascript
 var history = groucho.getActivities('browsing'),
     links = $('a.promoted'),
     count = 0;
+
 for (var i in history) {
   // Determine if they've seen a page with a specific property.
   if (history[i].hasOwnProperty('myProperty') count++;
@@ -114,37 +114,32 @@ if (count < 2) links.addClass('featured');
 else if (count >= 2 && count < 7) links.addClass('reduced');
 else links.addClass('hidden');
 ```
-Show the last viewed item of a given type. Example is last watched video...
-
-```javascript
-var history = groucho.getActivities('watch');
-if (history.length) {
-  $.get("videos.json?id=" + history[0].videoId, function(data) {
-    $('.recent').html(displayVideo(data));
-  });
-}
-```
 
 ## Custom Activies
 
 Register your own tracking activities like this...
+```javascript
+$('.videos a.play').bind('click', function() {
+  groucho.createActivity('watch', {'videoId' : 789});
+});
+```
 
+Retrieve activities later to personalize pages. Example swaps in the last watched video...
 ```javascript
-// Track your own activities.
-$('.my-special-links').bind('click', function (e) {
-  groucho.createActivity('my_activity', {
-    'linkText' : $(this).text(),
-    'myProperty' : $(this).attr('data-property')
+var history = groucho.getActivities('watch');
+
+if (history.length) {
+  $.get("videos.json?id=" + history[0].videoId, function(data) {
+    $('.recent').find('.title').text(data.title)
+      .find('.graphic').text(data.graphic)
+      .find('a').attr('href', data.url);
   });
-});
-// Later...
-myActivites = groucho.getActivities('my_activity');
+}
 ```
 
 ### Basic User Info
 
 Wait for data availability and user basic user info.
-
 ```javascript
 (function ($) {
   $(document).ready(function(){

groucho.json

@@ -2,7 +2,7 @@
   "name": "groucho",
   "title": "Groucho",
   "description": "Know more about your anonymous users. In-browser storage tracking tool.",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "homepage": "https://github.com/tableau-mkt/groucho",
   "author": {
     "name": "Josh Lind",

src/groucho.js

@@ -117,35 +117,106 @@ var groucho = window.groucho || {};
    * Access records of a specific tracking group.
    *
    * @param {string} group
-   *   Name of the tracking group to return values for.
+   *   Strucutured conditions for activity lookup: {type, [conditionList]}.
+   * @param {array} conditions
+   *   List of acceptable property [key/[values]] objects.
    *
    * return {array}
    *   List of tracking localStorage entries.
    */
-  groucho.getActivities = function getActivities(group) {
+  groucho.getActivities = function getActivities(type, conditionList) {
 
-    var results = $.jStorage.index(),
+    // Optional params.
+    var group = type || false,
+        conditions = conditionList || false,
+        groupMatch = new RegExp("^track." + group + ".", "g"),
+        results = $.jStorage.index(),
         returnVals = [],
-        matchable = new RegExp("^track." + group + ".", "g"),
         record;
 
+    /**
+     * Confirm properties are of desired values.
+     * NOTE: String comparisons only!
+     *
+     * @param  {array} conditions
+     *   List of acceptable property [key/[values]] objects.
+     * @param  {string} record
+     *   History record to check against.
+     *
+     * @return {boolean}
+     *   Result of match check.
+     */
+    function checkProperties(conditions, record) {
+      // Check all conditions, be picky about type.
+      if (conditions && conditions instanceof Array) {
+        for (var i in conditions) {
+          // Confirm an acceptable value.
+          if (checkValues(i, conditions[i], record)) {
+            addRecord(record);
+          }
+
+        }
+      }
+      else {
+        // No conditions, or wrong type-- add everything.
+        addRecord(record);
+      }
+    }
+
+    /**
+     * Confirm one of values matches the record.
+     * NOTE: String comparisons only!
+     *
+     * @param  {string} property
+     *   Property to check.
+     * @param {array} values
+     *   List of acceptable values.
+     * @param  {string} record
+     *   History record to check against.
+     *
+     * @return {boolean}
+     *   Result of match check.
+     */
+    function checkValues(property, values, record) {
+      // Check all values, be picky about type.
+      if (values instanceof Array) {
+        for (var i in values) {
+          // Confirm an acceptable value.
+          if (record.hasOwnProperty(property) && record.property === values[i]) {
+            addRecord(record);
+            // Only need one match per value set.
+            break;
+          }
+        }
+      }
+    }
+
+    /**
+     * Grab record from storage, add to returns.
+     *
+     * @param string key
+     *   Browser storage lookup key.
+     */
+    function addRecord(key) {
+      record = $.jStorage.get(key);
+      // Move key to special property.
+      record._key = key;
+      returnVals.push(record);
+    }
+
+
+    // Look through storage index.
     for (var i in results) {
       // Remove unwanted types and return records.
       if (group) {
-        if (results[i].match(matchable) !== null) {
-          // Collect relevant.
-          record = $.jStorage.get(results[i]);
-          // Move key to property.
-          record._key = results[i];
-          returnVals.push(record);
+        if (results[i].match(groupMatch) !== null) {
+          // Move on to checking conditions (potentially just add it).
+          checkProperties(conditions, results[i]);
         }
       }
       else {
-        // Collect and return all.
-        record = $.jStorage.get(results[i]);
-        // Move key to property.
-        record._key = results[i];
-        returnVals.push(record);
+        // Just check property or just add.
+        checkProperties(conditions, results[i]);
       }
     }