Lots of tidying + documenting of JS

Transaction table header now includes category if appropriate

analyser.js

@@ -1,13 +1,188 @@
 var previousPoint = null;
 var state = {};
 var plots = {};
-var months = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
 
+// -----------------------------------------------------------------------------
+// ------------------ Date handling --------------------------------------------
+// -----------------------------------------------------------------------------
+
+Date.prototype.months = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+
+/**
+ * Formats this date as year and two digit month, separated by a '-'.
+ *
+ * @return This date formatted as a key
+ */
+Date.prototype.getKey = function() {
+ return this.getFullYear() + '-' + (this.getMonth() < 9 ? '0' : '') + (this.getMonth() + 1);
+}
+
+/**
+ * Gets a textual representation of this date's month
+ *
+ * @return This date's month name
+ */
+Date.prototype.getDisplayMonth = function() {
+ return this.months[this.getMonth()];
+}
+
+/**
+ * Gets a textual representation of the range of months between this date and
+ * the specified other. It is assumed that the other date will occur after this.
+ *
+ * @param {Date} other The end date
+ * @return {String} A textual representation of the date range
+ */
+Date.prototype.getRangeText = function(other) {
+ if (this.getFullYear() == other.getFullYear() && this.getMonth() == other.getMonth()) {
+  return this.getDisplayMonth() + ' ' + this.getFullYear();
+ } else if (this.getFullYear() == other.getFullYear()) {
+  return this.getDisplayMonth() + '-' + other.getDisplayMonth() + ' ' + this.getFullYear();
+ } else {
+  return this.getDisplayMonth() + ' ' + this.getFullYear() + ' - ' +  other.getDisplayMonth() + ' ' + other.getFullYear();
+ }
+}
+
+/**
+ * Gets a date object corresponding to the specified timestamp. If advanceToNext
+ * is specified, and the timestamp doesn't already correspond to the first of
+ * the month, the date is forwarded to the first day of the next month.
+ *
+ * @param {int} timestamp The timestamp to convert to a date
+ * @param {bool} advanceToNext Whether to advance to the 1st or not
+ * @return {Date} A corresponding date object
+ */
+function getDate(timestamp, advanceToNext) {
+ var date = new Date(timestamp);
+
+ if (advanceToNext && date.getDate() > 1) {
+  date.setDate(1);
+  date.getMonth() == 11 && date.setYear(date.getFullYear() + 1);
+  date.setMonth(date.getMonth() == 11 ? 0 : date.getMonth() + 1);
+ }
+
+ return date;
+}
+
+// -----------------------------------------------------------------------------
+// ------------------ Data handling --------------------------------------------
+// -----------------------------------------------------------------------------
+
+/**
+ * Calculates the sum of transactions belonging to each category within
+ * the specified data.
+ *
+ * @param data An array of transactions to include
+ * @param {bool} incoming True to tally income, false to tally expenses
+ * @return A mapping of categories to the sum of their transactions
+ */
+function getCategoryTotals(data, incoming) {
+ var catData = {};
+
+ $.each(data, function() {
+  trans = this;
+  var category = trans.Category ? trans.Category : 'Unsorted';
+
+  if (category != '(Ignored)' && incoming == trans.Amount > 0) {
+    if (!catData[category]) { catData[category] = 0; }
+    catData[category] += Math.abs(trans.Amount);
+  }
+ });
+
+ return catData;
+}
+
+/**
+ * Retrieves an array of transactions which occur between the specified two
+ * dates. This has a resolution of a month -- any data in the same month
+ * as the start date will be included, and any data after the month of the
+ * end date will be excluded.
+ *
+ * @param {Date} start The date to start including data at
+ * @param {Date} end The date to stop including data at
+ * @return An array of transactions between the two dates
+ */
+function getDataForRange(start, end) {
+ var include = false;
+ var included = [];
+ $.each(data, function(month, monthData) {
+  include |= month == start.getKey();
+
+  if (include) {
+   $.each(monthData, function(index, trans) {
+    included.push(trans);
+   });
+  }
+
+  include &= month != end.getKey();
+ });
+
+ return included;
+}
+
+// -----------------------------------------------------------------------------
+// ------------------ State handling -------------------------------------------
+// -----------------------------------------------------------------------------
+
+/**
+ * Update the page's state with the specified new state. This causes the state
+ * to be loaded into the user's history so they can use back and forward
+ * functionality in their browser. New state is merged with the old state.
+ *
+ * @param newState The new properties to add to the state
+ * @param invalidatedState An array of state keys to remove
+ */
+function setState(newState, invalidatedState) {
+ $.extend(true, state, newState);
+
+ $.each(invalidatedState, function(_, x) { delete state[x]; });
+
+ $.history.load(JSON.stringify(state));
+}
+
+/**
+ * Called when the page state changes (either via a call to $.history.load or
+ * by the user manually changing the fragment or going back or forward).
+ *
+ * @param {string} hash The new page fragment
+ */
+function handleStateChange(hash) {
+ var oldState = $.extend({}, state);
+
+ try {
+  state = JSON.parse(hash);
+ } catch (ex) {
+  state = {};
+ }
+
+ if (state.start && state.end && state.type) {
+  // Update the transaction table and pie charts
+  showSelectedMonths(state.start, state.end, state.type == 'income', state.type == 'expenses', state.categoryFilter, state.expanded);
+
+  // If the selection has changed, update the visual representation
+  (oldState.start != state.start || oldState.end != state.end) && plots.history.setSelection({ xaxis: { from: state.start, to: state.end }});
+ }
+}
+
+// -----------------------------------------------------------------------------
+
+/**
+ * Adds an 'alt' class to every other visible row in the specified table.
+ *
+ * @param table The table to be marked-up
+ */
 function colourTableRows(table) {
  $('tr', table).removeClass('alt');
  $('tr:visible:even', table).addClass('alt');
 }
 
+/**
+ * Shows a tooltip with the specified content at the given co-ordinates.
+ *
+ * @param {int} x The x co-ordinate to show the tooltip at
+ * @param {int} y The y co-ordinate to show the tooltip at
+ * @param contents The content to display in the tooltip element
+ */
 function showTooltip(x, y, contents) {
  $('<div id="tooltip">' + contents + '</div>').css( {
   position: 'absolute',
@@ -20,10 +195,12 @@ function showTooltip(x, y, contents) {
  }).appendTo("body").fadeIn(200);
 }
 
-function getDateKey(date) {
- return date.getFullYear() + '-' + (date.getMonth() < 9 ? '0' : '') + (date.getMonth() + 1);
-}
-
+/**
+ * Called when the user clicks on the expand/contract toggle on a transaction
+ * line where similar entries have been merged.
+ *
+ * @param event The corresponding event
+ */
 function expandLinkHandler(event) {
  var text = $(this).text();
  var expanded = text.substr(0, 2) == '(+';
@@ -44,110 +221,107 @@ function expandLinkHandler(event) {
  return false;
 }
 
-function setState(newState, invalidatedState) {
- $.extend(true, state, newState);
+/**
+ * Determines if the two transactions should be merged together. That is,
+ * whether the transactions have an identical description, type and category.
+ *
+ * @param a The first transaction
+ * @param b The second transaction
+ * @return True if the transactions should be merged, false otherwise
+ */
+function shouldMerge(a, b) {
+ return a.Description == b.Description && a.Type == b.Type && a.Category == b.Category;
+}
 
- $.each(invalidatedState, function(_, x) { delete state[x]; });
+/**
+ * Draws a pie chart of transactions by category.
+ *
+ * @param included An array of transactions to include in the chart
+ * @param incoming True to show income, false to show expenses
+ */
+function drawCategoryPieChart(included, incoming) {
+ var pieData = getCategoryTotals(included, incoming);
+ var seriesData = [];
+ $.each(pieData, function(category, amount) {
+  seriesData.push({ label: category + ' (' + Math.round(amount) + ')', data: amount });
+ });
 
- $.history.load(JSON.stringify(state));
+ seriesData.sort(function(a, b) { return b.data - a.data; });
+
+ plots.expense = $.plot($('#expense'), seriesData, {
+   series: { pie: { show: true, innerRadius: 0.5, highlight: { opacity: 0.5 } } },
+   grid: { clickable: true }
+ });
 }
 
-function showSelectedMonths(start, end, incoming, outgoing, categoryFilter) {
+/**
+ * Displays transactions and draws a category pie chart for the specified
+ * date range. Note that dates have a granularity of a month.
+ *
+ * @param {int} start The timestamp to start including transactions from
+ * @param {int} end The timestamp to stop including transactions at
+ * @param {bool} incoming Whether or not to include incoming transactions (income)
+ * @param {bool} outgoing Whether or not to include outgoing transactions (expenses)
+ * @param {string} categoryFilter The category to filter transactions to (or null)
+ * @param expanded An object containing entries indicating which merged
+ *                 transactions should be shown as expanded
+ */
+function showSelectedMonths(start, end, incoming, outgoing, categoryFilter, expanded) {
  $('#historytable tr.data').remove();
  $('#historytable').show();
 
- var startDate = new Date(start), endDate = new Date(end);
-
- if (startDate.getDate() > 1) {
-  startDate.setDate(1);
-  startDate.getMonth() == 11 && startDate.setYear(startDate.getFullYear() + 1);
-  startDate.setMonth(startDate.getMonth() == 11 ? 0 : startDate.getMonth() + 1);
- }
+ expanded = expanded || [];
 
- var startKey = getDateKey(startDate), endKey = getDateKey(endDate);
+ var startDate = getDate(start, 1), endDate = getDate(end);
 
- if (startKey == endKey) {
-  $('#historytable h3').text('Transactions for ' + months[startDate.getMonth()] + ' ' + startDate.getFullYear());
- } else if (startDate.getFullYear() == endDate.getFullYear()) {
-  $('#historytable h3').text('Transactions for ' + months[startDate.getMonth()] + '-' + months[endDate.getMonth()] + ' ' + startDate.getFullYear());
- } else {
-  $('#historytable h3').text('Transactions for ' + months[startDate.getMonth()] + ' ' + startDate.getFullYear() + ' - ' +  months[endDate.getMonth()] + ' ' + endDate.getFullYear());
- }
+ $('#historytable h3').text((categoryFilter ? categoryFilter + ' t' : 'T') + 'ransactions for ' + startDate.getRangeText(endDate));
 
- var pieData = {};
  var table = $('#historytable table');
- var include = false;
  var lastEntry = {};
  var id = 0;
- $.each(data, function(month, monthData) {
-  if (month == startKey) { include = true; }
+ var included = getDataForRange(startDate, endDate);
 
-  if (include) {
-   $.each(monthData, function(index, trans) {
-    if (incoming != trans.Amount > 0) { return; }
-
-    var category = trans.Category ? trans.Category : 'Unsorted';
- 
-    if (category != '(Ignored)') {
-     if (!pieData[category]) { pieData[category] = 0; }
-     pieData[category] += Math.abs(trans.Amount);
-    }
-
-    if (categoryFilter && categoryFilter != category) { return; }
-
-    var tr = $('<tr/>').addClass('data').addClass('category' + category.replace(/[^a-zA-Z]*/g, '')).appendTo(table);
-
-    if (lastEntry.Description == trans.Description && lastEntry.Type == trans.Type && lastEntry.Category == lastEntry.Category) {
-     tr.hide();
-
-     if (lastEntry.id) {
-      var prefix = '(' + (state.expanded && state.expanded[lastEntry.id] ? '-' : '+');
-      lastEntry.count++;
-      $('span', lastEntry.tr).text(prefix + lastEntry.count + ')');
-     } else {
-      lastEntry.id = ++id;
-      lastEntry.count = 1;
-      var prefix = '(' + (state.expanded && state.expanded[lastEntry.id] ? '-' : '+');
-      var a = $('<span>').addClass('link').text(prefix + '1)').appendTo($('td.desc', lastEntry.tr).append(' '));
-      a.bind('click', { id: lastEntry.id, tr: lastEntry.tr }, expandLinkHandler);
-     }
-
-     lastEntry.Amount = Math.round(100 * (lastEntry.Amount + trans.Amount)) / 100;
-     if (state.expanded && state.expanded[lastEntry.id]) {
-      tr.show();
-     } else {
-      $('.amount', lastEntry.tr).text(lastEntry.Amount);
-     }
-
-     tr.addClass('collapsed hidden' + lastEntry.id);
-
-    } else {
-     lastEntry = $.extend({}, trans, {tr: tr});
-    }
-
-    $('<td/>').text(trans.Date.date.split(' ')[0]).appendTo(tr);
-    $('<td/>').text(trans.Type ? trans.Type : 'Other').appendTo(tr);
-    $('<td/>').text(trans.Category ? trans.Category : '').appendTo(tr);
-    $('<td/>').addClass('desc').text(trans.Description).appendTo(tr);
-    $('<td/>').addClass('amount').text(trans.Amount).appendTo(tr);
-   });
-  }
+ $.each(included, function() {
+  trans = this;
+  if (incoming != trans.Amount > 0) { return; }
 
-  if (month == endKey) { include = false; }
- });
- colourTableRows(table);
+  var category = trans.Category ? trans.Category : 'Unsorted';
 
- var seriesData = [];
- $.each(pieData, function(category, amount) {
-  seriesData.push({ label: category + ' (' + Math.round(amount) + ')', data: amount });
- });
+  if (categoryFilter && categoryFilter != category) { return; }
 
- seriesData.sort(function(a, b) { return b.data - a.data; });
+  var tr = $('<tr/>').addClass('data').addClass('category' + category.replace(/[^a-zA-Z]*/g, '')).appendTo(table);
 
- plots.expense = $.plot($('#expense'), seriesData, {
-   series: { pie: { show: true, innerRadius: 0.5, highlight: { opacity: 0.5 } } },
-   grid: { clickable: true }
+  if (shouldMerge(lastEntry, trans)) {
+   if (lastEntry.id) {
+    var prefix = '(' + (expanded[lastEntry.id] ? '-' : '+');
+    lastEntry.count++;
+    $('span', lastEntry.tr).text(prefix + lastEntry.count + ')');
+   } else {
+    lastEntry.id = ++id;
+    lastEntry.count = 1;
+    var prefix = '(' + (expanded[lastEntry.id] ? '-' : '+');
+    var a = $('<span>').addClass('link').text(prefix + '1)').appendTo($('td.desc', lastEntry.tr).append(' '));
+    a.bind('click', { id: lastEntry.id, tr: lastEntry.tr }, expandLinkHandler);
+   }
+
+   lastEntry.Amount = Math.round(100 * (lastEntry.Amount + trans.Amount)) / 100;
+
+   !expanded[lastEntry.id] && tr.hide() && $('.amount', lastEntry.tr).text(lastEntry.Amount);
+
+   tr.addClass('collapsed hidden' + lastEntry.id);
+  } else {
+    lastEntry = $.extend({}, trans, {tr: tr});
+  }
+
+  $('<td/>').text(trans.Date.date.split(' ')[0]).appendTo(tr);
+  $('<td/>').text(trans.Type ? trans.Type : 'Other').appendTo(tr);
+  $('<td/>').text(trans.Category ? trans.Category : '').appendTo(tr);
+  $('<td/>').addClass('desc').text(trans.Description).appendTo(tr);
+  $('<td/>').addClass('amount').text(trans.Amount).appendTo(tr);
  });
+
+ colourTableRows(table);
+ drawCategoryPieChart(included, incoming);
 }
 
 $(function() {
@@ -178,7 +352,7 @@ $(function() {
   transData[2].data.push([timestamp, sum[0] + sum[1]]);
   min = Math.min(min, timestamp);
   max = Math.max(max, timestamp);
- }); 
+ });
 
  var catData = [];
  $.each(categories, function(category, entries) {
@@ -199,6 +373,7 @@ $(function() {
 
  var markings = [];
 
+ // Add a marking for each year division
  var year = new Date(new Date(max).getFullYear(), 0);
  while (year.getTime() > min) {
   markings.push({ color: '#000', lineWidth: 1, xaxis: { from: year.getTime(), to: year.getTime() } });
@@ -231,7 +406,7 @@ $(function() {
    grid: {
      hoverable: true,
      clickable: true,
-     markings: markings 
+     markings: markings
    },
    selection: { mode : "x" }
  });
@@ -242,11 +417,11 @@ $(function() {
 
    if (previousPoint == null || previousPoint.dataIndex != id.dataIndex || previousPoint.seriesIndex != id.seriesIndex) {
     previousPoint = id;
-             
+
     $("#tooltip").remove();
     var x = item.datapoint[0],
         y = item.datapoint[1].toFixed(2);
-                 
+
     var date = new Date(x);
 
     var seriesTitles = ["Money in", "Money out", "Balance change"];
@@ -254,14 +429,14 @@ $(function() {
    }
   } else {
    $("#tooltip").remove();
-   previousPoint = null;            
+   previousPoint = null;
   }
  });
 
  $('#history').bind('plotselected', function(event, ranges) {
   var startDate = parseInt(ranges.xaxis.from.toFixed());
   var endDate = parseInt(ranges.xaxis.to.toFixed());
- 
+
   if (state.start != startDate || state.end != endDate || state.type != 'expenses') {
    setState({ start: startDate, end: endDate, type: 'expenses' }, ['categoryFilter', 'expanded']);
   }
@@ -277,20 +452,5 @@ $(function() {
   setState({ categoryFilter: item.series.label.replace(/ \([0-9]+\)$/, '') }, ['expanded']);
  });
 
- $.history.init(function(hash) {
-  var oldState = $.extend({}, state);
-
-  try {
-   state = JSON.parse(hash);
-  } catch (ex) {
-   state = {};
-  }
-
-  var match = /start:([0-9]+);end:([0-9]+);type:(income|expenses)/.exec(hash);
-
-  if (state.start && state.end && state.type) {
-   showSelectedMonths(state.start, state.end, state.type == 'income', state.type == 'expenses', state.categoryFilter);
-   (oldState.start != state.start || oldState.end != state.end) && plots.history.setSelection({ xaxis: { from: state.start, to: state.end }});
-  }
- });
+ $.history.init(handleStateChange);
 });