{"id":615,"date":"2010-08-07T11:40:47","date_gmt":"2010-08-07T19:40:47","guid":{"rendered":"http:\/\/www.zackgrossbart.com\/hackito\/?p=615"},"modified":"2013-03-26T03:29:56","modified_gmt":"2013-03-26T11:29:56","slug":"edcal_stats","status":"publish","type":"post","link":"http:\/\/www.zackgrossbart.com\/hackito\/edcal_stats\/","title":{"rendered":"Collecting Statistics for The WordPress Editorial Calendar Plugin"},"content":{"rendered":"

\"Fork<\/a><\/p>\n

Writing a WordPress plugin is inspiration, perspiration, testing, guess work, and frustration. You spend hours making your plugin just right, but you never know if it is just right. You hear from some of the happy users and none of the unhappy ones. This guess work leads to assumptions we can’t back up.<\/p>\n

\"\"<\/a><\/p>\n

The team from Stresslimit Design<\/a> and I have been working on the WordPress Editorial Calendar<\/a> for months, but we have no real idea how people use it. How many weeks are people looking at in the calendar? How big are there screens? How many posts do they have per day? We need the answers to design the plugin, but we’re just fumbling through the dark.<\/p>\n

With version 0.9 of the calendar we’re trying to turn on the light. <\/p>\n

Why we’re collecting data<\/h2>\n

WordPress plugins go out into the wild and don’t phone home. You get a simple plugin statistics page<\/a>, but never find out who’s using your plugin, how they’re using it, or even if they installed it after downloading. As a privacy nut I like that, but it makes my life as a designer difficult. <\/p>\n

\"\"<\/p>\n

The editorial calendar is getting close to version 1.0 and we’re trying to refine our interface. Make those little tweaks that take it from good to great. We started with a simple question, how many weeks should we show on the calendar by default? I rarely post more than once a day and my 24-inch monitor stretches on like the Montana prairie so I want as many weeks as possible. I could even go up to eight or nine. <\/p>\n

Nine weeks is the perfect answer for me, but it isn’t the right answer. Most users are stuck in Manhattan apartment sized screens and can’t see nine weeks with a magnifying glass. Well… that’s what I think, but I don’t really know. If I had real data on people’s window sizes I could make the right choice and make the calendar that much better. <\/p>\n

That’s why we’re tracking data with this plugin. To make it work better. That’s most of the reason. We also want to know how many people are really using it. <\/p>\n

Always make it opt-in<\/h2>\n

WordPress plugins have a gigantic amount of power. They can delete your data, steal your passwords, and hack your blog. When you install a plugin you’re saying I trust this plugin to not be evil<\/i>. That’s a lot of trust and the Editorial Calendar has to earn it. <\/p>\n

We could collect data automatically, but that’s evil. Instead we make all data collection opt-in. Users can very clearly see everything we collect and have to click the button before we collect anything. <\/p>\n

\"\"<\/p>\n

How it works<\/h2>\n

The data collection is based on Mint<\/a>. I already used Mint to track statistics for my own site<\/a>. Mint is a more configurable and better looking competitor to Google Analytics<\/a>. It also lets me hold onto my data instead of sending it to Google. <\/p>\n

Normally Mint is part of your website with a simple declaration like <script src=\"\/mint\/?js\" type=\"text\/javascript\"><\/script><\/code>. This causes the Mint JavaScript to get downloaded, collect information about the browser, and call back to the server without visitors ever knowing. <\/p>\n

\nGet the
Source Code<\/a>\n<\/div>\n

This type of website data collection is ubiquitous. Every major site does it and the total volume of personal information they collect is a little scary. My privacy rant is coming up in a little while.<\/p>\n

Mint made collecting data from the Editorial Calendar pretty easy. It just takes a few lines of JavaScript to get Mint onto the Calendar page:<\/p>\n\n\n
\n
jQuery.getScript('http:\/\/www.zackgrossbart.com\/edcal\/mint\/?js'<\/span>, function() {\r\n    edcal.saveFeedbackPref();\r\n});\r\n<\/pre>\n<\/td>\n<\/tr>\n<\/table>\n
Now I can dynamically load the mint JavaScript files and save the preference of that when it’s done.  The dynamic loading is important because I don’t want to collect data every time and automatic data collection is way too scary.  Right now we prompt the user to let us collect data after they’ve loaded the calendar three times, and we never collect any data until we get permission.<\/p>\n
Peppers<\/h2>\n
Mint collects data about how people came to your site like who they were referred by and what terms they searched for to get there.  It also collects information about the environment like what browser they’re running and if they have Flash.  I needed data more specific to the calendar like how many weeks are people seeing and how many posts do they have per day.  For that I needed to write a Pepper<\/a>.<\/p>\n
Peppers are the way you extend the capabilities of Mint.  I love puns.  They’re written in PHP and JavaScript and collect or display extra data.  There are Peppers to tell you how big someone’s browser window is or who has a secret crush on your website.  My Pepper collects data about the calendar.<\/p>\n
This Pepper is open source and like the rest of the code on this blog it is released under the Apache License, Version 2.0<\/a>.  That means you can copy it, change it, or use it for free.<\/p>\n
Setting up our Pepper<\/h3>\n
The Editorial Calendar Stats Pepper starts with a PHP file called class.php and a big comment.<\/p>\n\n\n
\n
<?php\r\n\/**************************************************\r\n Pepper\r\n \r\n Developer      : Zack Grossbart\r\n Plug-in Name   : Edcal Stats\r\n \r\n **************************************************\/\r\n<\/span>\r\n \r\n$installPepper = \"SI_EdcalStats\"<\/span>;\r\n    \r\nclass SI_EdcalStats extends Pepper\r\n{\r\n    var $version    = 1; \/\/ Displays as 0.01<\/span>\r\n    var $info       = array\r\n    (\r\n        'pepperName'<\/span>    => 'Editorial Calendar Stats'<\/span>,\r\n        'pepperUrl'<\/span>     => 'http:\/\/www.zackgrossbart.com'<\/span>,\r\n        'pepperDesc'<\/span>    => 'Editorial Calendar Pepper'<\/span>,\r\n        'developerName'<\/span> => 'Zack Grossbart'<\/span>,\r\n        'developerUrl'<\/span>  => 'http:\/\/www.zackgrossbart.com'<\/span>\r\n    );\r\n\r\n<\/pre>\n<\/td>\n<\/tr>\n<\/table>\n
The $info<\/code> array sets up our Pepper and gives us the basics; a title and description.  With this class we define the functionality and feel of the Pepper using a special set of variables.  We start by defining the panes we’ll show on the statistics page<\/a>.<\/p>\n
Defining our panes<\/h3>\n\n\n
\n
var $panes = array\r\n(\r\n    'Editorial Calendar Stats'<\/span> => array\r\n    (\r\n        'Stats'<\/span>\r\n    )\r\n);\r\n\r\n<\/pre>\n<\/td>\n<\/tr>\n<\/table>\n
The Editorial Calendar Stats Pepper just has one pane where it shows the Stats<\/i> for the calendar plugin.  This makes our $panes<\/code> array very simple.  <\/p>\n
Collecting data<\/h3>\n
The next step is to define the data we want to collect and where we’ll store it in the database.<\/p>\n\n\n
\n
var $manifest = array1<\/a><\/span>\r\n(\r\n    'visit'<\/span>    => array\r\n    (\r\n        'edcal_weeks'<\/span> => \"SMALLINT(5) NOT NULL DEFAULT '-1'\"<\/span>,\r\n        'edcal_posts'<\/span> => \"SMALLINT(5) NOT NULL DEFAULT '-1'\"<\/span>,\r\n        'edcal_author'<\/span> => \"TINYINT\"<\/span>\r\n    )\r\n);\r\n    \r\nfunction onRecord() \r\n{\r\n    $edcalWeeks =  $this->Mint->escapeSQL($_GET['edcal_weeks'<\/span>]);2<\/a><\/span>\r\n    $edcalPosts =  $this->Mint->escapeSQL($_GET['edcal_posts'<\/span>]);\r\n    $edcalAuthor =  $this->Mint->escapeSQL($_GET['edcal_author'<\/span>]);\r\n    \r\n    return array\r\n    (\r\n        'edcal_weeks'<\/span> => (float) $edcalWeeks,\r\n        'edcal_posts'<\/span> => (float) $edcalPosts,\r\n        'edcal_author'<\/span> => (boolean) $edcalAuthor\r\n    );\r\n}\r\n\r\n<\/pre>\n<\/td>\n<\/tr>\n<\/table>\n
The $manifest<\/code> array1<\/a><\/span> defines the database columns we need.  Mint will create these database columns when this Pepper is installed.  We need columns for the number of visible weeks, the number of posts, and if they are showing authors.  <\/p>\n
We populate these fields with the onRecord<\/code> function.  The values come on the URL so we access the data using the PHP $_GET<\/code> function2<\/a><\/span>.  <\/p>\n
Querying the calendar with JavaScript<\/h3>\n\n\n
\n
function onJavaScript() \r\n{\r\n    $js = \"pepper\/zackgrossbart\/edcalstats\/script.js\"<\/span>1<\/a><\/span>;\r\n    if (file_exists($js))\r\n    {\r\n        include_once($js);\r\n    }\r\n}\r\n\r\n<\/pre>\n<\/td>\n<\/tr>\n<\/table>\n
We access configuration values in the calendar using JavaScript.  We tell Mint about our JavaScript file with the onJavaScript<\/code> function1<\/a><\/span>.  This adds the script.js<\/code> file to our Mint request.  <\/p>\n\n\n
\n
Mint.SI.EdcalStats = \r\n{\r\n    onsave  : function() \r\n    {\r\n        if (edcal) {\r\n            \r\n            \/*\r\n             * Collect the number of weeks they are showing\r\n             *\/<\/span>\r\n            var val = '&edcal_weeks=' + edcal.weeksPref;1<\/a><\/span>\r\n            \r\n            \r\n            \/*\r\n             * If they are showing authors\r\n             *\/<\/span>\r\n            if (edcal.authorPref) {2<\/a><\/span>\r\n                val += '&edcal_author=1'<\/span>;\r\n            } else {\r\n                val += '&edcal_author=0'<\/span>;\r\n            }\r\n            \r\n            \/*\r\n             * Get the average number of posts they have\r\n             * per day\r\n             *\/<\/span>\r\n            var dayCounts = [];\r\n            \r\n            jQuery(\"#cal_cont .dayobj > .postlist\").each(function() {\r\n                \/*\r\n                 * Don't consider days with zero posts\r\n                 *\/<\/span>\r\n                if (jQuery(this).children().length > 0) {\r\n                    dayCounts.push(jQuery(this).children().length);3<\/a><\/span>\r\n                }\r\n            });\r\n            \r\n            var total = 0;\r\n            for (var i = 0; i < dayCounts.length; i++) {\r\n                total += dayCounts[i];\r\n            }\r\n            \r\n            if (dayCounts.length > 0) {\r\n                val += '&edcal_posts='<\/span> + Math.round(total \/ dayCounts.length);\r\n            } else {\r\n                val += '&edcal_posts=0'<\/span>;\r\n            }\r\n            \r\n            return val;\r\n                \r\n        }\r\n    }\r\n};\r\n\r\n<\/pre>\n<\/td>\n<\/tr>\n<\/table>\n
The Editorial Calendar is already running in our JavaScript memory space so calling it from script.js<\/code> is ideal.  We can call the existing functions to collect the data we need.  The current number of weeks1<\/a><\/span>, the authors preference2<\/a><\/span>, and the average number of posts per day3<\/a><\/span>.  JQuery makes it easy to iterate over the DOM.<\/p>\n
Showing the data<\/h3>\n
Now that we’ve collected all of this data we need to show it on the Editorial Calendar Statistics<\/a> page.  For that we’ll implement the onDisplay<\/code> function<\/p>\n\n\n
\n
function onDisplay($pane, $tab, $column = '', $sort = '')\r\n{\r\n$html = '';\r\n    switch($pane) \r\n    {\r\n        case 'Editorial Calendar Stats'<\/span>:\r\n        $html  = '<table cellspacing=\"0\" class=\"two-edcal-columns\">'<\/span>;\r\n        $html .= \"\\r\\t<tr>\\r\"<\/span>;\r\n        $html .= \"\\t\\t<td style=\\\"padding-right: 4px;\\\" class=\\\"left\\\">\\r\"<\/span>;\r\n        $html .= $this->getHTML_EdcalWeeks();\r\n        $html .= \"\\t\\t<\/td>\"<\/span>;\r\n        $html .= \"\\t\\t<td class=\\\"right\\\">\\r\"<\/span>;\r\n        $html .= $this->getHTML_EdcalPosts();\r\n        $html .= \"<br \/>\"<\/span>;\r\n        $html .= $this->getHTML_EdcalAuthor();\r\n        $html .= \"\\t\\t<\/td><\/span>\";\r\n        $html .= \"\\r\\t<\/tr>\\r<\/span>\";\r\n        $html .= \"<\/table>\\r<\/span>\";\r\n        break;\r\n    }\r\n    \r\n    return $html;\r\n}\r\n<\/pre>\n<\/td>\n<\/tr>\n<\/table>\n
We show a little table for each piece of data we’ve collected and define the contents of that table in separate functions.  <\/p>\n
What about privacy?<\/h2>\n
\nView the
Stats Page<\/a>\n<\/div>\n
There is a constant tension between collecting data and preserving privacy.  I know we’re only using this data to improve the plugin, but would I trust a group of strangers to use the data?  Maybe.  <\/p>\n
This article is a how to, but it’s also about transparency.  I want to make it clear what data we’re collecting and how we’re using it.  <\/p>\n
We went out of our way to make sure the data collected by the calendar is innocuous and non-commercial.  We don’t sell the data.  Honestly, nobody would want to buy it.  <\/p>\n
The whole point is to make the calendar better.  The more we understand how it’s being used the better we can make the design.  The calendar should be simple and easy to use, but simple isn’t so simple.  Making something that feels good means we have to know how people use it and what feels good to them.  These statistics help us do just that.<\/p>\n","protected":false},"excerpt":{"rendered":"
Writing a WordPress plugin is inspiration, perspiration, testing, guess work, and frustration.  You spend hours making your plugin just right, but you never know if it is just right.  This post shows you the details of the new process we added to collect remote data about the WordPress Editorial Calendar Plugin<\/a>.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[24,20,23,15],"tags":[],"_links":{"self":[{"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/posts\/615"}],"collection":[{"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/comments?post=615"}],"version-history":[{"count":50,"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/posts\/615\/revisions"}],"predecessor-version":[{"id":666,"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/posts\/615\/revisions\/666"}],"wp:attachment":[{"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/media?parent=615"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/categories?post=615"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.zackgrossbart.com\/hackito\/wp-json\/wp\/v2\/tags?post=615"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}