Plugin Development

All plugins are stored in the src/js/plugins directory and are referenced in src/js/plugins/index.js. Plugins are used by the scroblr content-script in order to answer a few simple questions:

1. Should this plugin be active in the current browser window?
2. Is a song being played in the current browser window?
3. If so, give me as much information about the track as you can.

The Big Picture

Whenever the user opens a new browser window, the extension will look at the URL and decide whether to inject the bundle-content-script.js file into the document or not. To determine this, the URL for the page must match one of the URL globs defined in the manifest.json file (i.e. "*://*.beatsmusic.com/*").

Once the content script is loaded, it will cycle through all of the plugins defined in src/plugins/index.js and run their Plugin.test() method. If the test method returns true, the plugin will be activated. During activation, if the plugin has a Plugin.initialize() method, it will be called, and then an interval will be created that will call the Plugin.scrape() method every 5 seconds for as long as the browser window is open.

In Practice

Plugins inherit from the Plugin object which is defined in src/js/modules/Plugin.js, and have the following methods and parameters:

• {String} name - The name of the plugin, preferably lowercase letters only (i.e. 'google')
• {String} displayName - The full name of the plugin that will be displayed to the user (i.e. 'Google Play')
• {Function} init - Init method, used when creating an instance of the Plugin object
• {Function} initialize - A method that will be called once when the plugin is activated (optional)
• {Function} scrape - When the plugin is activated, this method is called every 5 seconds, it's purpose is to scrape the page for track information
• {Function} test - This should return true or false whether the plugin should be activated or not, typically by testing the document location

Below is an example of a simple plugin.

"use strict";

var $      = require("jquery");
var Plugin = require("../modules/Plugin");
var songza = Object.create(Plugin);

songza.init("songza", "Songza"); // name, displayName

songza.test = function () {
    var domainTest = /songza\.com/i.test(document.location.hostname);
    var playerTest = $("#player").length > 0;

    return domainTest && playerTest;
};

songza.scrape = function () {
    var info = {
        artist:  $("#player .szi-artist").text(),
        stopped: $("#player .player-play").css("display") === "none" ? false : true,
        title:   $("#player .szi-title").text()
    };

    return info;
};

module.exports = songza;

The scrape method is expected to return an object with certain parameters. For a track to be recognized it MUST include an artist and a title. All other parameters are optional, but the more information the better. Below is a list of parameters that scroblr expects to receive from the Plugin.scrape() method.

• {String} artist - The name of the artist
• {String} title - The title of the track
• {String} album - The name of the album that the track belongs to
• {Boolean} stopped - Is the song currently stopped/paused? true or false
• {Integer} duration - The duration of the song in milliseconds
• {Integer} elapsed - How much of the song has played in milliseconds
• {Float} percent - A number between 0 and 1, representing how much of the song has elapsed in percentage (i.e. 0.40)

Most sites display duration and elapsed time in a format like "3:27", in order to convert that to milliseconds, you can use a utility function called calculateDuration() by requiring the utilities module that is defined in src/js/modules/Utilities.js.

var Utils = require("./modules/Utilities");
Utils.calculateDuration("1:23"); // 83000

Example

To see an example of a single commit that encompasses all the changes necessary to add support for a new site, see commit 496a459a03143e19207f83458e08de68bc4d12cb