the Data Actor

To highlight the idea of a movie built using a multiplicity of points of views, during the workshop we created the DataActor.

The Data Actor is intended as a peculiar actor in the movie, representing and giving expression to all the voices of social network users expressing themselves in realtime on the themes of the movie.

The Data Actor has been developed as a WordPress Plugin with specific integration features with the NeoReality Platform.

If installed alone, the Data Actor can be configured to be sensible to specific keywords on social networks such as Twitter, Facebook and FourSquare: as soon as the users of these social networks contribute their posts using these keywords, the content is immediately captured by the plugin. If this information includes geographic information (such as the geolocalized Twitter messages or the Facebook updates including Places information) they are placed on a map as geo-referenced content.

If installed on a WordPress CMS in which the NeoReality Plugin is also installed, the content created by DataActor is automatically included in the AR visualizations of NeoReality’s mobile app.

The DataActor, thus:

  • automatically creates content on WordPress by capturing the public expressions of social network users on a series of keyworkds and phrases
  • if this content can be geo-referenced, it includes it in the NeoReality AR experience

This possibility has been proven really successful with all workshop participants, who were imagining a series of scenarios in which User Generated Content could be automatically used to enrich our experience of cities and of physical spaces, including commerce, knowledge, education, activism, politics, art and communication. 

One very interesting concept emerged while collaboratively creating the DataActor plugin during the workshop: the possibility to use our visual space as a digital interface. The scenario we developed together with participants engaged our visual space in defining novel usage grammars for it. As an example, the scenario we developed involved placing content for kids in the lower part of our visual space, between 70cm from ground to 1.2 meters from ground, all the AR Movie content between 1.2 meters and 5 meters from ground, and the content produced by the DataActor above the 5meters limit. This concept has proven to be really interesting in the idea of developing accessible, usable AR content, and will be further explored in the near future.

Let’s see how the DataActor is created.

The idea is represented in the following diagram:

The DataActor logical diagram
The DataActor logical diagram

The main idea revolves around the possibility to creating new Content Types in the WordPress CMS. In the NeoReality platform we have used this possibility to enable the WordPress CMS to host our AR content. This is what you see when you access the “AR Content” sections of your WordPress Dashboard: some new Custom Post Types.

The idea is to create a further type of custom posts: we will call it AR TWit.

We will use this custom post type for our purpose: to host in the wordpress CMS the geo-referenced content coming from Twitter that should be displayed in realtime on our Augmented Reality App.

To do this, we will need to create a Harvester, a small piece of software that is able to monitor Twitter to capture the relevant twits as soon as they are posted.

We will need to periodically call the Harvester component, so that the update takes place fast enough. To do this we will use the crontab functions available directly within WordPress, which will allow us to schedule function calls.

We will wrap all this in a new WordPress Plugin.

Let’s begin.

How do you make a new WordPress Plugin?

To learn how to code a new WordPress plugin is very simple: just follow the instructions found here.

It turns out that creating a WordPress plugin is really simple. To do it:

  • create a PHP file with the name of the plugin or
  • create a directory with the name of the plugin, add to it a PHP file with the name of the plugin and all supporting files
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:
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:
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
and the line that reads
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.
  • 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
Each section, basically, configures some associations between some parameters which WordPress uses to map an information it requires to its value. For example, the parameter “singular_name” exists to describe the label that WordPress should use to describe a single item of a certain type of content. Giving a value to it will let WordPress know how to behave (and in our plugin, for example, we gave it the value “AR Twit”).
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
This becomes even more clear in the dataactor_artwit_save_postdata() function of the plugin, which is used, as we saw above, to store the content of the AR twit to the database.
This function, we said, is called when a “save” function is called on the WordPress system.
The first thing it does is to check if we are actually saving a post of the correct type:
if ( 'artwit' == $post->post_type)
If this is the case, the function checks wether the content already exists (such as in the case of an “update” function) or not (such as when we are saving the content for the first time):
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
REST means Representational State Transfer and it describes a content and information distribution and access pattern. According to this pattern you are able to format requests (queries) by using a standard web protocol (for example the HTTP GET or POST formalisms) and to receive back a representation of the resource or information you asked for (usually using formats which are standards of the web as well, for example XML orJSON).
REST APIs are, thus, based on the idea that you place a certain request and you get back a certain related response.
Streaming APIs, on the other hand, have a completely different approach: you configure a continuous communication channel with your information provider and you can connect to it to continuously capture the information you need.
Both approaches have pros and cons, and have completely different usage scenarios. Streaming API is most often used in server-to-server communication, as it requires the possibility to create processes which run in the background to connect to the Stream and gather content from it. The agile and quick REST queries are more suitable, instead, to implement custom search engines and the like.
With our approach we need to use the Streaming API, as it is the only one which guarantees a continuous capture of all the Twits we are interested in.
To access the Streaming API offered by Twitter, a pretty complex procedure is needed (involving authentication, encryption, and other things).
The Phirehose API linked above gives acces to a lot of these functionalities already implemented, and will allow us to focus on the logic of the application. Please check out the documentation of the Phirehose API to know more about it. We have included in this project only the resources needed for this specific activity.
To use this API we will have to create a PHP class which uses the functionalities offered by the API itself.
Our implementation is derived directly from the examples provided in the Phirehose documentation page.
In the plugin file the statement
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:

      	 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:


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
The shortcode definition looks something like this:
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 ) {

This function is the one containing the lines of code which we already analyzed when understanding how to configure the Phirehose API! Bingo! We’re done! We just need to add the shortcode to a hidden page and make it be called periodically.

To do the first step is easy: simply add


to a new WordPress page and save it (remember to make it invisible by not adding it to menus and to navigation interfaces).

To do the second thing we can install one of the many WP-cron based plugins for wordpress, allowing us to configure periodic tasks to be executed. For example we can download and install this plugin and use it to configure a periodic call to our hidden page URL.

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.