The DataActor logical diagram

You can install this plugin to your WordPress by unzipping the directory and uploading the resulting directory to your WordPress plugin directory (in the “wp-content/plugins” directory off your wordpress root dir).

Let’s browse the code of the plugin to understand how it is built.

The PHP program that hosts the code of the plugin has to reflect a standard structure.

The first thing which we will write in the plugin is a header section containing some content which WordPress uses to identify the plugin and its information.

/*
Plugin Name: dataactor
Plugin URI: http://rwr.artisopensource.net/
Description: the DataActor plugin allows to capture twits in realtime and turn them into WordPress content and into AR content for the NeoReality platform
Version: 0.0.1
Author: RWR participants
Author URI: http://rwr.artisopensource.net/
License: GPL3
*/

As you can see this information defines the plugin’s name, description, authors and things like that.

A licensing is also defined. We used the GPL3 License and the text immediately follows this initial content.

Let’s focus on how it is possible to create a custom post type in WordPress.

THis process is done in the section of the code found between the line that reads

// ARTWITS START

and the line that reads

/* ARTWITS END */

Almost all of the actions performed by WordPress plugins are executed in what are calledActions and FIlters. An Action is basically the indication of something do be done at a certain point of the standard life cycle of a WordPress website (e.g.: “execute task X when you start loading the administration interface”, or “execute task Y when you print the title of a certain post”). A Filter is basically a way to perform some actions to transform content (e.g..: “perform function X to transform the content in a certain way when saving it to the database”).

What you do is to instruct (in the code of your plugin) WordPress to perform these actions in the way you want them: you provide functions for this which the WordPress system will automatically call and execute at the specified moments and events.

To create a new content type in WordPress we have to use a couple of these features.

This is configured in the following lines of code:

add_action( 'admin_init', 'dataactor_artwit_add_custom_box', 1 );
add_action( 'save_post', 'dataactor_artwit_save_postdata' );
add_action('init', 'dataactor_custom_init');
add_filter('post_updated_messages', 'dataactor_artwit_updated_messages');
add_action( 'contextual_help', 'dataactor_add_help_text', 10, 3 );

That is: 4 actions and a filter.

These actions and filters configurations have practically the same structure: first we indicate a parameter that describes “when” to execute our code (the “event” described above, for example “save_post” in the second statement means “do it when i save a post”) and the name of a function to be called accordingly.

When, What: at the occurrence of this event, call this function.

The functions take care of defining the elements which compose a Custom Post for the WordPress platform, at the correct time.

Specifically:

• during the “admin_init” event (initialization of the administration interface) we will define the interface elements that will be used to edit our AR Twits)
• during the “init” event (initialization of the WordPress system) we will define the structure of the new content type
• during the “save_post” event (called when a content is saved to the database) we will describe the logic according to which the AR Twits are saved to database
• during the “post_updated_messages” we will make sure that the content is correctly stored even when it is automatically updated for any reason (for example on auto-save)
• during the “contextual_help” event (called when it is needed to visualize contextual help information) we will create a contextual help menu for our content type, for maximum accessibility

If for example we look at the PHP function dataactor_artwit_add_custom_box() defined in the plugin file, we will see how it uses the add_meta_box functionality to add the editing interface for our AR Twits by setting up the call to thedataactor_artwit_inner_custom_box  which, basically, sets up the extended information which characterizes the AR Twits compared to  the other standard WordPress Posts.

Here we can clearly see how this information is stored in the database.

WordPress allows you to define “custom fields” for your posts, allowing you to describe additional information that might characterize your post. A custom post type is just that: a post with additional information attached to it. In this case we decided to add information for:

• the coordinates (latitude, longitude and elevation)
• the URL of the avatar image of the person who made the twit
• the text of the twit

if ( 'artwit' == $post->post_type)

if(!empty($post_id) ){

Then the function update_custom_meta is called to store the info on the database.

In the main function which serves as the entry point for the plugin (thedataactor_custom_init ) we put all of this together. We first set up the $labels array, which contains a basic set of labels to be used with our new content type, and then the$args array, which is used to configure the content’s basic behaviour (for example the var “show_in_menu” defines if the content is to be visualized in the WordPress administration dashboard, and configurations like that).

The command register_post_type puts all this together and effectively creates the new post type.

Ok, perfect! Now we have a new WordPress Post Type that can store the twits, the image URL of the user who posted it and the coordinates where it was originated. Now we can setup the harvester software component to actually capture the twits.

To do this we will use the Phirehose API.

Twitter allows developer to use the content generated on its system bu providing an API.

There are multiple forms of Twitter APIs and multiple ways of using them. But, mostly, there is a main distinction to be made. Twitter offers basically two kinds of APIs:

• the REST API
• the Streaming API

class FilterTrackConsumer extends Phirehose

starts the definition of the class we need.

This class implements a single function ( called enqueueStatus ) which is automatically called by the Phirehose API whenever a new twit is provided by Twitter through the streaming API.

To configure the types of Twits  we would like to receive, we will use the other functions provided by the Phirehose API.

When we instance the class:

$sc = new FilterTrackConsumer('twitter_login', 'twitter_password', Phirehose::METHOD_FILTER);

we specify a username and password to access twitter (use your login and password replacing the placeholders, and be careful of not overusing the functionalities, to avoid being banned… please read thoroughly the twitter api docs for this) and we specify that we wish to provide filtering mechanisms (METHOD_FILTER) to choose only the twits we want.

We do this by applying some logics to the filtering. For example, we want to obtain only the twits which have been created in the geographical area of the AR Movie, and so we add a location based filter, like this:

	$sc->setLocations(array(
      	 array(13.711655, 39.701369, 15.711655, 41.701369)
	));

there are plenty of other filtering techniques available and described at the Phirehose documentation pages and on the Twitter API docs pages.

In the example we establish a bounding box of the interesting area by listing the latitude/longitude coordinates of its corners.

Then we start the capture service like this:

$sc->consume();

From this moment onward whenever the Twitter streaming API will send in some new twit which conforms to our filtering logic, the Phirehose API will call our enqueueStatus message.

Here we used the technique described HERE to programmatically create a post of type AR Twit on our wordpress CMS.

First we setup its basic structure:

$new_post = array(
		'post_title' => $username . " said...",
		'post_content' => $twittertext,
		'post_excerpt' => $twittertext,
		'post_status' => 'publish',
		'post_date' => date('Y-m-d H:i:s'),
		'post_author' => 1,
		'post_type' => 'artwit'
		);

Then we use the wp_insert_post function to insert a new post

$post_id = wp_insert_post($new_post);

And then we use a series of add_post_meta commands to enter the AR Twit’s related information (coordinates, height, text, avatar image url), like this, for the avatar image URL:

if(!update_post_meta($post_id,'dataactor_artwit_img_url', $image_url )){
			add_post_meta($post_id,'dataactor_artwit_img_url', $image_url );
		}

That’s it! our content is created!

Now we need a way to periodically call our function, so that the process is triggered often enough to achieve the “realtime” part of the functionality (that is: we want to call the function fast enough so that there is a short delay between when twits are generated and when they are captured, but not so fast as to overload our server).

We figured that calling this function each minute or so would be enough for our purposes.

To call the function we need something to be called! We decided that we would create a special page on the website that would contain a special content that would trigger the call to this harvesting functionality.

The idea is to create a WordPress shortcode that we could place on a page whose purpose was not to be displayed on the website (and, thus, we won’t add it to the menus and site navigation interface) but to be called periodically.

Ad described in the WordPress documentation page about the Shortcode API, shortcodes are special tags delimited by square brackets which act as placeholders for specific custom functionalities. There are shortcodes for image galleries, social network integration and all sorts of things.

To create our shortcode will need to do the following steps:

• create the shortcode definition
• create the shortcode handler function

add_shortcode( 'dataactor', 'dataactor_func' );

Here we define the “dataactor” shortcode and we tell WordPress that it will be handled by the “dataactor_func” PHP function.

Thus WordPress will call this function whenever it finds a “dataactor” shortcode inside a post or page:

function dataactor_func( $atts ) {

...

}

[dataactor]

Our DataActor is ready.

One more thing: the version of the NeoReality plugin which is available for download at the RWR Software page is already configured to also download and visualize the AR Twits created by the DataActor. The one currently on the GitHub page is not. So watch out on what you install on your WordPress.