theoleschool - nodejs

Using Drupal Content Channel Tokens with Nodejs

rho — Mon, 28 Apr 2014 17:29:06 +0000

You've decided to add a bit of Node.js functionality to your Drupal site using the Drupal Nodejs Module. After some reading you realize you need to be setting up user message channels using hook_nodejs_user_channels or possibly nodejs_add_user_to_channel. This allows your application to send socket messages to groups of users. Great! But you're writing no simple application. You want to go one step further and manage these channels based not only on some property of the user object, but all users who may be currently viewing a particular Drupal served page. Suddenly the typical user channels no longer cut it. Try as you might, you'll find yourself quickly descending into channel management hell. There has got to be a better way. Thankfully content token channels are here to help.

Send a Message Based on the Content Being Viewed

You can think of content token channels as a per page (or piece of content) channel subscription. This differs from the user channels in that it targets users who are currently viewing a specific page rather than users targeted by some property of the user object (regardless of where they are on the site).

There are two main PHP functions to implement a token channel. nodejs_send_content_channel_token to generate a token channel for a given piece of content, and nodejs_send_content_channel_message to send a message to users subscribed to a given content channel.

To illustrate this lets assume we want to create a channel to send user messages when they are viewing a Drupal node of type page. To begin we will need to setup our content channel for that node type. A good place to do this would be hook_node_view which fires when a user views a node.

function example_node_view($node, $view_mode, $langcode) {

  if($node->type == "page") {

    nodejs_send_content_channel_token('page_node_channel');

  }

}

Now every time a node of type page is viewed the Node.js server is notified of the page_node_channel content channel. Node.js then adds the channel to the user for whom the page was rendered.

From here if we wish to send a message to all of the users viewing a node of type page we make a simple call to nodejs_send_content_channel_message. When and where you choose to fire this message is up to you. Possibly you want to notify users if the page they are viewing has been updated (hook_node_update), a user logs in (hook_user_login), or some new content was added (hook_node_insert).

// Build a message object

$message = new stdClass();

$message->channel = 'page_node_channel';

$message->data['body'] = 'Hello World!';

// Send the message to the channel we created

nodejs_send_content_channel_message($message);

And that's about it! When nodejs_send_content_channel_message fires our message will be broadcast to all users subscribed to the page_node_channel. In this case all users who are currently viewing a node of type page. This message behaves like any other on the Node.js side, so you could send it to a custom callback handler, as mentioned in an earlier post.

Token Messages From an Node.js Extension

If you are writing a Node.js server extension and wish to send a message to a content channel, it is worth noting that there is no immediately exposed functionality to do this. However, Node.js server extensions are aware of what the content channels are via config.tokenChannels. This allows us to mimic the functionality of the Drupal Node.js server with a helper method in our server extension.

function sendMessageToTokenChannel(message, config) {

  if (!message.hasOwnProperty('channel')) {

    console.log('publishMessageToContentChannel: An invalid message object was provided.');

    return;

  }

  if (!config.tokenChannels.hasOwnProperty(message.channel)) {

    console.log('publishMessageToContentChannel: The channel "' + message.channel + '" doesn\'t exist.');

    return;

  }

  for (var socketId in config.tokenChannels[message.channel].sockets) {

    config.publishMessageToClient(socketId, message);

  }

}

Adding this method to your server extension, will allow you to send messages to a content channel, by passing the message and config objects from within your exports.setup function.

Using content token channels has greatly simplified several of the Drupal/Node.js projects I have done. However, it wasn't immediately apparent that this functionality existed. So I hope this helps to further clarify the capabilities of this module.

Hubot Drush me Drupal

rho — Wed, 08 May 2013 04:15:48 +0000

Recently the company I work for shifted the bulk of our instant message communications over to Campfire, and established a series of rooms to discuss our various projects. This transition seemed to go fairly well, once everyone settled on their preferred client interface. I was used to using IRC and found a nice little Ruby gem that piped Campfire through my IRC client. Chatting in this environment quickly had me missing Druplicon, the friendly Drupal fueled chat bot that tirelessly serves the Drupal IRC community. I decided to look for a replacement, and after some searching I stumbled upon Hubot, a Node.js powered chat bot. It was initially built by the folks at GitHub and includes a long list of plugin scripts added by community developers. This was immediately appealing for several reasons:

It is built using Node.js
It is written in Coffeescript (something I have wanted to try my hand at for a while)
Additional scripts appeared easy to write, and plugin simply
It has built in Campfire integration

So I installed Hubot on a small server, with a handful of scripts that I thought would be useful and fun for our team. Adding the bot to our Campfire rooms was fairly painless, and after writing a small init script we were good to go. This sparked some discussion among our team about how the bot was deployed, cool ways it could be extended, and methods of use. A fellow developer, David Fells, mentioned that it would be handy if we could tell Hubot to execute Drush commands. This gave me pause, and after a quick:

"That's a great idea! You mind if I implement that?"
"Sure, go for it."

I found myself firing up my editor, trying a few test methods, and reading up on CoffeeScript. Things moved fairly quickly, once I got going. I realized child_process.spawn()was going to be my friend, a core Node method that I had yet to use. Generally CoffeeScript proved to be the biggest challenge. While writing the initial prototype I actually used a JavaScript to CoffeScript translator and was cursing the whole time. However, by the time I was putting the finishing touches on my methods and objects I found myself smiling as I wrote in this almost comical syntax. Simply put, CoffeeScript is fun! I still find myself favoring the comforting structure of the curly braces and semicolons when working with JavaScript, but now that all seems somewhat gray and drab, knowing there is something much more playful out there.

As you can imagine there were, and are, several security concerns. The early prototype actually had user commands pipe right into Drush which is a security nightmare. Any user with access to the bot could escape or pipe in any old Bash command directly through the bot. Further, any Drupal installation that Drush is aware of would be at the mercy of users who may or may not have the best intentions at heart. Needless to say this approach was quickly abandoned in favor of a hand picked list of commands made available to the bot. This caused the code to be a bit more tedious, and likely less elegant, but I needed to insure that Drush would be executing the allowed commands, and nothing more. After some discussion I also decided to weed the available commands down to a relatively innocuous set (giving information vs. actually changing something). I attempted to structure the code in a way that it would not be difficult for another developer to add commands. Overall, I'm pretty happy with the end result, and the pull request was soon accepted. You can find this script along with all of the other Hubot scripts on GitHub.

tl;dr If you're looking for a fun chatbot for campfire (or otherwise) check out Hubot and enable drush.coffee if you'd like that bot to have cool Drush functionality.

Talking to Drupal with Node.js

rho — Mon, 29 Oct 2012 01:36:31 +0000

As I've mentioned in a previous post sending messages from Drupal to Node is fairly easy to accomplish. However, that is only part of the equation. If we're really wanting to build a larger, more complex Node application, it won't be long before we need the client to talk to the Node server and possibly the Node server to talk to Drupal. At a glance it isn't terribly obvious how to do this with the nodejs integration module, but it turns out there are a few tools tucked in the module code that come to the rescue.

This post will assume some familiarity with the use of the server extension functionality built into the nodejs module. If you are unfamiliar with this, have a look at the example server extension included with the module. In short it does what you might think, allowing other modules to extend the nodejs server setup by the nodejs module. For context I've posted a fully commented example module to GitHub from which the code snippets of this post are taken.

If you are familiar with writing node apps with Socket.io then you are likely already familiar with client side communication back to the node server. Typically you will have a socket.emit on the client side, and a listener to handle the message event on the server side. The same is true when using the nodejs module. In this example I'm building a very simple form with Drupal and displaying it on a page. When the submit button is hit, a bit of client side javascript emits a message through socket.io which is in the Drupal.Nodejs object.

// A simple message.  The listener on the server side does not like us to
// specify 'messageType' so we're calling it 'type' for now.
var message = {

  type: 'nodeToDrupal',

  messageBody: 'Hello from the client side!'
};

Drupal.behaviors.sendDrupalMessage = {

  attach: function(context, settings) {

    // Have our message emitter fire on form submission.

    $("#node-to-drupal-form").submit(function() {

      Drupal.Nodejs.socket.emit('message', message);

      return false;

    });

  }
}

On the server side, in our server extension file, we need to catch our message. This is done in a fairly standard way, the event we are listening for is client-message.

 
exports.setup = function (config) {

  process.on('client-message', function (sessionId, message) {

    // Logging the message to the console.

    console.log('Got a message from the client.  Take a look: ');

    console.log(message);

  });
}

If a client message comes through, we log it to the console. For a lot of node applications our worries are over. We have a way for the client to send a message to the node server. From there we can have the node server do whatever we would like with it. Maybe spit a message back out to the client, to a different session, to a Redis store, or any number of other things. Now the big question. What if we want the node server to send a message to Drupal? There are several reasons we may want to do this, but chief among them would be a database write. The idea of having node write directly to the Drupal database, while possible, would surely harm large baskets full of kittens. It's a bad idea. So we need node to tell Drupal to do its bidding, and for that we need to look at a hook_nodejs_message_callback. This hook allows us to assign handler functions to various message types that being emitted from the node server, and is wonderfully simple.

function node_to_drupal_nodejs_message_callback($type) {

  switch($type) {

    case 'nodeToDrupal':

      return array('node_to_drupal_handler');

  }

  return false;
}

The hook is fired on an sendMessageToBackend call from the node server and passes in messageType from the message. In our case the type is nodeToDrupal (more on this in a bit). The hook is expected to return and array of function names, that will subsequently be called. In this case node_to_drupal_handler.

function node_to_drupal_handler($message, &$responce) {

  // Grab our messageBody from the client message and post it to the watchdog.

  watchdog('node_to_drupal', $message['messageBody'], array(), WATCHDOG_INFO);

  // Tell node we got the message.

  $responce = 'Message logged to Watchdog!';
}

The handler functions called from hook_nodejs_message_callback expect two parameters. The message from node (as an array), and a response passed by reference. In this example we're make a simple watchdog entry of the messageBody, and adding a string to the response stating that Drupal got the message.

Going back to our node server extension, we're going to fire the message we got from the client over to Drupal. To do this were going to use a handy function in our config variable called sendMessageToBackend. Our server extension code is now looking like:

exports.setup = function (config) {

  process.on('client-message', function (sessionId, message) {

    // Logging the message to the console.

    console.log('Got a message from the client.  Take a look: ');

    console.log(message);

    // Insuring that messageType is set before passing along.

    message.messageType = message.type;

    // Send the message to Drupal.

    config.sendMessageToBackend(message, function(error, responce, body) {

      if(error) {

        console.log('Error sending message to backend.', error);

        return;

      }

      // Drupal got it! Output the responce.

      console.log('Response from drupal: ', body);

    });

  })
};

We grab our message from the client and send it to the Drupal backend, then upon success log Drupal's response to the console. Now our little message chain is complete! We have a message coming from the client side to the node server upon a user action. Then node passes that message along to Drupal which records it in the watchdog. This means that not only can we have our node server interacting back and forth with the client, but also have tremendous flexibility over how the node server can interact with Drupal.

Module Development with NodeJS Integration

rho — Sat, 21 Apr 2012 15:49:34 +0000

I've been spending some time experimenting with NodeJS in relation to the Drupal environment. In many of these Node/Drupal interactions the NodeJS Integration module has become a key player. There is a very helpful pdf from a talk that beejeebus gave at Drupal camp New Jersey that gives few great visualizations of the underlying principles of how this module works. In essence it "takes care of the plumbing," leaving you, the developer, free to focus on how you would like to integrate. The module is easy to use, and provides a nice set of functions to quickly get rolling. To that point I would like to give a very simple example demonstrating the use of the nodejs integration module.

It's perhaps easiest to think of this integration as allowing Drupal to send messages (data) to a client via NodeJS "plumbing." I feel that the simplest and most transparent example is to allow the user to control what that message is and when it is sent. In this demonstration we build a simple form. This form allows a user to enter a message into a text field. Then on submit, it sends that message to all connected sockets and replaces a bit of <h3> markup within the form. This is very similar to the "broadcast notifications" form included with the NodeJS integration module, but much simpler.

To help visualize this I've setup an install to show this demo in action. If no one else is viewing the demo page while you are, which very likely will be the case, then I encourage you to open another session (open the page in another browser) and arrange the browser windows so you can see them both at once. This way, when you submit in one session, you can see the text in the header change on the other. I've also checked in the code on github to help fill in the gaps from the snippets I provide here, and hopefully help to make sense of my yammering. So with that, lets get into a bit more detail...

Begin with a few considerations.

When you set out to create your module using NodeJS integration it may help to ask yourself some simple questions.

Who receives the message?
What is the message?
How is the message triggered?
What will be done with the message once it is received?

Who receives the message?

After a user has requested a connection to socket.io, NodeJS sends this authentication token to Drupal. Drupal then sends back a list of channels the user can "listen" on. To manage which channels a user is assigned to we can use function hook_nodejs_user_channels($auth_user). The $auth_user parameter is the user that is being authenticated. Any checks you might need to perform on the user to determine if they should be assigned a channel can be done here.

In our example we're keeping this really simple. We want to send the message to all users so we give everyone who authenticates the 'swapit_demo' channel.

function swapit_demo_nodejs_user_channels($auth_user) {

  $channels = array('swapit_demo');

  return $channels;
}

What is the message and how is it triggered?

The message itself is a small object that contains the data it is intended to send, along with some information on how/where to send it. The trigger could really be anything and will likely be pretty obvious based on your use case. In our example module, we're providing the users a form to allow them to write the message that will then be sent on submit. So all of the magic happens in our submit function.

function swapit_demo_swap_submit($form, &$form_state) {

  $user_msg = check_plain($form_state['values']['user_message']);

  //just doing a quick variable set to store the string.

  variable_set('demo_message', $user_msg);

  //broadcasting the string to our listening javascript in waiting

  $message = new stdClass();

  $message->channel = 'swapit_demo';

  $message->broadcast = TRUE;

  $message->data['body'] = $user_msg;

  $message->callback = 'swapIt';

  nodejs_send_message($message);
}

Here we are grabbing the form data from our textfield, and inserting it into a message object. Note how we are setting the channel to the one we set back in hook_nodejs_user_channels. Passing this object to node_send_message will get NodeJS to broadcast to all connected sockets having the 'swapit_demo' channel. The $message->data array contains our user submitted message. The 'body' key is arbitrary.

What will be done with the message?

Now that we have a message being broadcast we need to have a bit of javascript on the client side that will receive and do something with it. In our case, we simply want to replace the text in our given HTML element.

Drupal.Nodejs.callbacks.swapIt = {

  //grab the message and inject into the header

  callback: function (message) {

    if(message.channel == 'swapit_demo') {

      $('form #nodejs-selector').html(message.data.body);

    }

  }
};

We first define a callback function to receive the message. Note how the callback name is passed to the message object in the submit function in the previous snippet. Our function now verifies the channel on the message object, and uses the message data to replace the text in the #nodejs-selector element. Notice how $message->data['body'] has translated to message.data.body in the javascript. All that remains is to tell the nodejs integration module about the file containing our client side javascript.

function swapit_demo_nodejs_handlers_info() {

  return array(

    drupal_get_path('module', 'swapit_demo').'/swapit_demo.client.js',

  );
}

That about sums it up in the simplest way I knew how. I welcome any questions, and would love to hear of others experience with this useful module

Resources:

NodeJS Integration module ( http://drupal.org/project/nodejs )
beejeebus' talk at Drupalcamp NJ ( http://www.drupalcampnj.org/sessions/drupal-and-nodejs )
Demonstration of this module ( http://demo.theoleschool.com/swap )
This code on github ( https://github.com/rh0/swapit_demo )