IntenseDebate Comment System

Introduction

This page provides documentation of the API (Application Programming Interface) hooks available to IntenseDebate plugin developers, and how to use them. This plugin API is very much inspired by the WordPress Plugin API, so if you’re already familiar with that you should feel right at home. If not, no worries, we provide full documentation here.

If you haven’t already, we suggest reading the section on Writing a Plugin first.

This document is a work in progress and constantly evolving. Please be sure to check back regularly for updates and contact us about any suggestions you might have.

Hooks, Filters, and Actions↑ Table of Contents ↑

IntenseDebate provides several hooks that allow your plugin to ‘hook into’ the IntenseDebate comment system; that is, to call functions in your plugin at specific times, and thereby set your plugin in motion. There are two kinds of hooks:

1. Actions: Actions are the hooks that the IntenseDebate comment system launches at specific points during execution, or when specific events occur. Your plugin can specify that one or more of its JavaScript functions are executed at these points, using the Action API.
2. Filters: Filters are the hooks that IntenseDebate uses to modify text of various types before sending it on it’s way (either to our system or to the output). Your plugin can specify that one or more of its JavaScript functions is executed to modify specific types of text at these times, using the Filter API.

Actions

Actions are fired by specific events that take place in IntenseDebate, such as posting a comment, voting on a comment, or initialization of the comment system itself. Your plugin can respond to the event by executing a JavaScript function, which can in turn execute whatever code you desire.

The basic steps to make this happen (described in more detail below) are:

1. Create the JavaScript function that should execute when the event occurs, in your plugin file.
2. Hook into the IntenseDebate action by calling id_add_action
3. Add your plugin to your blog (more detail below).

Create an Action Function↑ Table of Contents ↑

The first step in creating an action in your plugin is to create a JavaScript function with the action functionality of your plugin, and put it in your plugin (your plugin must be included on the blog – more details below). For example, if you want to thank your users for posting a comment by displaying a message in a popup box, you might define the following function:
function thanks_for_posting(args) {
alert("Thanks for your comment! Please come back again.");
}

For most actions, your function should accept a single parameter (usually an array of two or more parameters, depending on the action). Some actions don’t pass any parameters — check the documentation for the action for details. Besides the one parameter, you can also access the global variables of IntenseDebate, and call other IntenseDebate functions (or functions in your plugin file).

NOTE: Keep in mind that other plugins, IntenseDebate itself, or other JavaScript on the site may already be using the function name you have thought of. See Plugin Development Suggestions for more information.

Hook into IntenseDebate↑ Table of Contents ↑

After your function is defined, the next step is to “hook” or register it with IntenseDebate. To do this, call id_add_action() in the global execution space of your plugin file:
id_add_action ( 'hook_name', your_function, [priority] );

where:

• hook_name is the name of an action hook provided by IntenseDebate that tells what event your function should be associated with.
• your_function is a reference to the function that you want to be executed following the event specified by hook_name. This can be a standard JavaScript function, a function present in the IntenseDebate system, a function defined in your plugin, or even a function defined in another JavaScript file on the site.
• priority is an optional integer argument that can be used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.

In the example above, we would put the following line in the plugin:
id_add_action('comment_post', thanks_for_posting);


Add the code to your blog↑ Table of Contents ↑

In order to test / debug your plugin we’ve provided the Plugin Editor. This allows you to add arbitrary JavaScript to one of your blogs in the same place we load plugin code. Using this tool you can develop and test your plugin before submitting it to the Plugin Directory to be shared with others. See Submitting a plugin for more information on adding your plugin to the IntenseDebate plugins directory.

Current Hooks For Actions↑ Table of Contents ↑

See Plugin API/Action Reference for a current list of action hooks in IntenseDebate.

Filters

Filters are functions that IntenseDebate passes data through, at certain points in execution, just before taking some action with the data (such as posting a comment or displaying a comment). Filters sit between the database and the browser (when IntenseDebate is rendering output), and between the browser and the database (when IntenseDebate is adding new comments to the database).

The basic steps to adding your own filters to IntenseDebate (described in more detail below) are:

1. Create the JavaScript function that filters the data in your plugin.
2. Hook into the IntenseDebate filter by calling id_add_filter
3. Add your plugin to your blog (more detail below).

Create a Filter Function↑ Table of Contents ↑

A filter function takes as input the unmodified data, and returns modified data (or in some cases, a null value to indicate the data should be deleted or disregarded). If the data is not modified by your filter, then the original data must be returned so that subsequent plugins can continue to modify the value if necessary.

So, the first step in creating a filter in your plugin is to create a JavaScript function to do the filtering, and put it in your plugin file. For example, if you want to make sure that your comments don’t contain a given word (maybe you hate the word ‘cheese’ for example) then create the following JavaScript function:
function filter_cheese(content) {
return content.replace(/cheese/ig, 'BLOCKED');
}

NOTE: Keep in mind that other plugins, IntenseDebate, or other widgets on the site may already be using the function name you have thought of. See Plugin Development Suggestions for more information.

Hook in your Filter↑ Table of Contents ↑

After your function is defined, the next step is to “hook” or register it with IntenseDebate. To do this, call id_add_filter in your plugin:

id_add_filter('filter_name', your_filter, [priority]);

where:

• hook_name is the name of a filter hook provided by IntenseDebate, which defines when your filter should be applied.
• your_filter is the function that you want to use for filtering. This can be a standard JavaScript function, a function used in IntenseDebate, a function from another JavaScript widget on the page, or a function defined by you in your plugin.
• priority is an optional integer argument that can be used to specify the order in which the functions associated with a particular filter are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.

In the example above, we would put the following in the main executing section of the plugin to tell IntenseDebate to filter new comments (when posted) for the word ‘cheese’:

id_add_filter('pre_comment_text',filter_cheese);

Add the code to your blog↑ Table of Contents ↑

In order to test / debug your plugin we’ve provided the Plugin Editor. This allows you to add arbitrary JavaScript to one of your blogs in the same place we load plugin code. Using this tool you can develop and test your plugin before submitting it to the Plugin Directory to be shared with others. See Submitting a plugin for more information on adding your plugin to the IntenseDebate plugins directory.

Current Hooks for Filters↑ Table of Contents ↑

See Plugin API/Filter Reference for a current list of filter hooks in IntenseDebate.

Tags: Plugins API — Can't find your answer here? Let us know.

Last modified: July 27, 2010 by Michael