September 13, 2013

Hack the Hive-Generating Events - Part Deux

Helix Swarm

Image: albaqir w/Flickr

As a person who loves to tinker and build small, useful tools Swarm is a veritable playground for me. In particular I find the Swarm activity stream is a great place to unify events in my development pipeline in a central place. We've seen how to have external systems create events in the Swarm activity feed, but what if you find yourself needing to create events inside of a Swarm module? Today we'll cover that case.

The honest truth is you likely will not need to create events inside of a Swarm module; most of the time when you're creating events it will make more sense to do it using the activity/add endpoint I described a couple articles ago. However you may find that you want to trigger an action when a particular event occurs, and the result of that action may be a new Swarm event. Let's look at how you can go about creating an event in a Swarm module.

As with the activity filtering plugin, we will be building a Zend Framework 2 module using PHP to extend Swarm. Also as with last time we have some example code to start with. I'll walk through some of the highlights.

In this toy example we are generating a new event anytime there is a checkin. In our module we will attach to the events queue, but we only register for 'task.change' events.

   $events->attach(
            'task.change',   // 'task.change' here attaches us to only new checkins

Inside this handler we will generate a new task and add it to the event queue. At this point we won't put in all the details for the event; we are just telling the system we would like a new event of type 'newdingo'.

      $queue = $services->get('queue');
      $queue->addTask('newdingo', 'newdingo'); 

Our module will also have a handler for "newdingo" tasks. When Swarm processes the task we added previously it will add a new event of type 'task.newdingo'. At this point we can flesh out the event with our content.

First we intercept it:

    $events->attach(
            'task.newdingo',   // 'newdingo' here attaches us to the event we created on commit

And then we create a new Activity record to attach to the event:

    // create an activity object for the event filled with our data
    // see Activity/src/Activity/Model/Activity.php for the list of possible fields
    $activity = new Activity;
    $activity->set(
        array(
                'type'          => 'dingo',
                'user'          => 'Dingo',
                'action'        => 'snuggled',
                'target'        => 'a baby'
        )
    );
    $event->setParam('activity', $activity); 

This will flesh out the 'newdingo' event, and send it on through the rest of the event pipeline where other handlers can react to it.

This example project also shows a nice example of controlling when your listener is called. You will notice there are three arguments to the attach method; the event types to listen for, the function to call when an appropriate event comes into the queue, and a priority for the listener. You can set any value between 100 and -100 for your priority. The higher the value the earlier in the process your listener will be executed. In our example we have the listener for the 'task.change' event fire close to last by setting the priority to '-95'. For the 'task.newdingo' listener we set it to 100 so that it can fill out the event properly before any other listener looks at it.

The code for this sample module can be found in the Public Depot along with a few other examples. So far in these articles I've been focusing on modifying Swarm by creating PHP modules, but next we'll look at how you can extend Swarm using CSS and Javascript. If you build any Swarm extensions stop by the forums and let us know; we'd love to hear what people are building!

Join us for a Swarm Hackathon on the USS Hornet Aircraft Carrier. You'll get to spend 24 hours on a real-life aircraft carrier creating a collection of killer mods. If you demo a hack, you'll get prize--a good prize. Learn More