Support Center

About Koken

This Help Center provides support for Koken, a free content management system designed for photographers, artists and designers.

Building the Google Analytics plugin

Building the Google Analytics plugin

Last Updated: Jul 25, 2013 04:49PM EDT

The following is a step-by-step guide on how the Google Analytics plugin for Koken was created. It covers many of the basic principles in plugin development and is a great case study for those wanting to begin developing plugins for Koken.

Defining the requirements

The requirements for the Google Analytics plugin are fairly simple.

  1. In order for Google Analytics to track your site, tracking code has to be placed before the closing </head> tag. That can be accomplished by tapping into the before_closing_head hook.

  2. The tracking code contains a unique tracking ID. The plugin will need to ask the user for this piece of information before the tracking code can be added.

plugin.json

To begin, we need to create plugin.json with the initial information about our plugin.

{ 
  "name": "Google Analytics",
  "version": "1.0",
  "description": "Automatically add analytics code to any theme.",
  "demo": "http://koken.me",
  "author": {
    "name": "Koken",
    "link": "http://koken.me"
  }
}

Since we need to get the tracking ID from the user, we’ll add a data object defining that field. Koken will use this information to automatically create the user interface in Settings > Plugins to retrieve this information from the user.

{ 
  "name": "Google Analytics",
  "version": "1.0",
  "description": "Automatically add GA code to any theme.",
  "demo": "http://koken.me",
  "author": {
    "name": "Koken",
    "link": "http://koken.me"
  },

  "data": {
    "tracking_id": {
      "label": "Tracking ID",
      "info": "You can find your tracking info by logging into Google Analytics, clicking Admin, then selecting the Tracking Info tab. Example: UA-1234567-8",
      "type": "string"
    }
  }
}

Each item in the data object defines an input that will be created in Koken for that plugin. In the above example, a text input will be created and assigned to the tracking_id key in your plugin’s data. Additional info about the field has been added via the info attribute, which will be presented in the “More info” drop-down in Koken’s interface.

plugin.php

Now that our plugin is defined and setup to receive data from the user, we can create plugin.php and setup the hook to add tracking code to the published site.

<?php

class KokenGoogleAnalytics extends KokenPlugin {

  function __construct()
  {
    $this->register_hook('before_closing_head', 'render');
  }

  function render()
  {

    echo <<<OUT
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', '{$this->data->tracking_id}']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>
OUT;

  }
}

In the class constructor, we’ve registered our plugin with the before_closing_head hook. When that hook fires, it will call our class’s render function where we can then output the tracking code. Notice how we are accessing the data the user has provided. Any data defined in plugin.json is available in the $this->data object.

Advanced topics

At this point, we have a working plugin. However, there are a few other options available to insure our plugin works reliably and responsibly.

Requiring setup

By default, as soon as plugins are activated in Settings > Plugins, they begin working right away. In our case, our plugin is of no use until the user has entered their tracking ID. We can tell the plugin system to require setup before the plugin begins to work by setting the require_setup class property to true in our class’s constructor. That way, the tracking code will not be unnecessarily added to pages before the plugin is setup.

<?php

class KokenGoogleAnalytics extends KokenPlugin {

  function __construct()
  {
    $this->require_setup = true;
    $this->register_hook('before_closing_head', 'render');
  }

  function render()
  {

    echo <<<OUT
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', '{$this->data->tracking_id}']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>
OUT;
  }
}

Validating input

When defining data in plugin.json, we can also add validation to ensure the data entered by the user is in the correct format. In this example, the tracking ID is in a fairly consistent format that we can check with a regular expression.

{ 
  "name": "Google Analytics",
  "version": "1.0",
  "description": "Automatically add GA code to any theme.",
  "demo": "http://koken.me",
  "author": {
    "name": "Koken",
    "link": "http://koken.me"
  },

  "data": {
    "tracking_id": {
      "label": "Tracking ID",
      "info": "You can find your tracking info by logging into Google Analytics, clicking Admin, then selecting the Tracking Info tab. Example: UA-1234567-8",
      "type": "string",
      "validation": {
        "type": "regex",
        "rule": "^UA\\-[0-9]{4,10}\\-\\d{1,2}$",
        "error_message": "Not a valid tracking ID. It should be in this format: UA-XXXXXXXX-X"
      }
    }
  }
}

Available validation types include regex, not_empty and email. Koken will automatically validate data and prevent setup until it is provided in the correct format.

support@koken.me
http://assets2.desk.com/
false
koken
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete