theoleschool - 7.x

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.

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.

Templating the Commerce Order Completion Pane

rho — Sun, 12 Aug 2012 18:25:26 +0000

I recently found myself working on a fairly simple Drupal Commerce site. There weren't a lot of tricks to it, just a few items and an "express" checkout. So I fired up the Commerce Kickstart profile and after a few small tweaks, had it just about right. As we approached the theme, it became obvious that the commerce completion pane was going to take a lot of love. The designers had given us a unique layout for how this page should appear, complete with order specific information displayed in a kaleidoscope of containers. This was going to take some markup, and my first thought was, "it sure would be nice to template this."

Turns out that's a fairly simple task thanks to hook_commerce_checkout_pane_info_alter. The function passes the variable $checkout_panes by reference which contains an array of checkout pane arrays. This function is going to allow us to redefine the function that the checkout completion pane is looking to for output. This will look something like:

function my_module_commerce_checkout_pane_info_alter(&$checkout_panes) {

  if(isset($checkout_panes['checkout_completion_message'])) {

    // forget the original include file                     

    unset($checkout_panes['checkout_completion_message']['file']);

    // point at this module

    $checkout_panes['checkout_completion_message']['module'] = 'my_module';

    // register the new output function

    $checkout_panes['checkout_completion_message']['base'] = 'my_module_completion_message_pane';

  }
}

The function name we passed above will have _checkout_form appended. We will need to declare a function to satisfy this and return our output.

function my_module_completion_message_pane_checkout_form($form, &$form_state, $checkout_pane, $order) {

  $pane_form = array();

  $pane_form['message'] = array('#markup' => /*markup*/);

  return $pane_form;
}

From here, we're basically home free. We simply need to replace /*markup*/ with the output we desire. Since we are looking to template this, we will need to register a theme implementation for it. The important thing to note is the $order variable passed to this function. We'll need that order information in our template, so we pass it along while laying out our hook_theme call.

function my_module_theme($existing, $type, $theme, $path) {

  return array(

    'my_module_completion' => array(

      // the template filename, .tpl.php will be appended

      'template' => 'my_module_completion',

      // include order as a variable in the template

      'variables' => array('order' => NULL),

    ),

  );
}

Now that we have a theme implementation that is expecting an order variable, all that remains is to call it as the value for '#markup' in our output function above.

$pane_form['message'] = array('#markup' => theme('my_module_completion', array('order' => $order)));

From here simply create the my_module_completion.tpl.php file and theme away! The template will have our order information exposed as the php variable $order allowing us to output whatever order information we would like. This is probably a good time to note, that the $order variable very well may not be sufficient (it wasn't for us). It contains mostly keys to fetch other bits of data about the order. In our actual implementation we wound up loading the line item (our implementation only allowed one), and some customer information. This can easily be done from the output function you define in hook_commerce_checkout_pane_info_alter and passed to the template exactly as we did the order variable in this example.

I admit that this is bordering on being somewhat hackish. I don't think I would take this approach if the Commerce implementation was more complex. If that were the case a better approach may be to create a custom checkout pane with the output you would like, assign it to the appropriate checkout pages, and leave the poor checkout completion pane alone. However, in the interest of time and ease in satisfying a theme requirement for a relatively small site, this method worked like a charm. Further, I don't believe that anything has been obfuscated. With some light commenting it should be apparent to anyone who reviews this code, exactly what is going on. With that in mind, take this method as a handy trick if you need to quickly and drastically rework how the checkout completion pane is displayed.

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 )