theoleschool - drupal

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.

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 )

Using hook_views_alter to Add a GROUP BY Statement

rho — Mon, 12 Mar 2012 15:09:21 +0000

I should note this post deals with Views 2.x on Drupal 6.x

When Views doesn't quite spit out the query we are looking for we can turn to hook_views_query_alter(&$view, &$query) to nudge it in the right direction. This is by no means news, and there are many a blog post detailing various ways to alter the query using this function. However, recently, I ran into an odd issue when attempting to add a GROUP BY statement.

The issue can be observed when attempting to use the add_groupby function to a field in the query. As an example, say we have a node view with a few fields (node id, node title, and user id). This will give a simple query:

SELECT node.nid AS nid, 

       node.title AS node_title, 

       users.uid AS users_uid 
FROM node node  
INNER JOIN users users ON node.uid = users.uid

Now, say we want to do something silly and get this query to group by user id. A node view does not allow for this, so we turn to hook_views_query_alter.

function my_module_views_query_alter(&$view, &$query) {

  switch($view->name) {

    case 'my_view_name':

      //add the group by  on the user id field 

      $query->add_groupby('users_uid');

      break;

  }
}

We expect to see a nice GROUP BY users_uid tacked on to the end of our query, but instead there is a disturbing GROUP BY nid, node_title, users_uid. What gives? Merlinofchaos clarifies for us:

"When using GROUP BY items that appear in the SELECT must either use aggregate functions OR appear in the GROUP BY. This is enforced by postgres, therefore Views must enforce this."

It is good that Views is looking out for the rules of postgres; it's what helps make it the powerful and flexible tool it is. In this application though, I am not worried about postgres and simply want to alter a single Views query on an sql database. I know that I can pass an 'aggregate' flag to the fields in the query object to denote that they use an aggregate function, even if they do not. Worth a try...

function dsic_judging_views_query_alter(&$view, &$query) {

  switch($view->name) {

    case 'dsic_judge_incomplete':

      //loop through the fields and add the aggregate indicator

      foreach($query->fields as $key => $field) {

        $query->fields[$key]['aggregate'] = TRUE;

      }

      $query->add_groupby('users_uid');

      break;

  }
}

Turns out this works! Jumping back to our view we see the query we are after:

SELECT node.nid AS nid, 

       node.title AS node_title, 

       users.uid AS users_uid 
FROM node node  
INNER JOIN users users ON node.uid = users.uid
GROUP BY users_uid

If it looks like a hack, and quacks like a hack, then it's probably a... well ya know. However, I don't have big qualms with implementing this. Views behavior is in place to accommodate a database that, in this instance, is not being used. Further, I am already using a hook function to modify a view beyond what that view is capable of spitting out on its own. Lastly, I am able to accomplish this without modifying Views core. All of that adds up to a valid use case and helps me to sleep at night.

Viewing Users Who Have Not Submitted a Webform

rho — Sun, 04 Mar 2012 18:25:05 +0000

On a recent Drupal 6 site, I received a request to build a view displaying a list of users who had not submitted a specific webform. Webform of course, has some very nice reporting as well as decent views integration for submissions. However, to view users that have yet to make a submission takes some creative views argument handling.

I began by building a basic user view. I then set the style and fields to my liking, and filtered on the specific role I was looking for. So now we have views pulling a list of users that we wish to check against. To find out who has not submitted the webform, we first have to take a look at who has.

webform_get_submissions($filters = array(), $header = NULL, $pager_count = 0);

Webform has the above function in the webform.submission.inc file that does just this. You can pass a node id to $filters and the function will return a nice array of submission objects, detailing who has submitted the form. We can then add an argument of type "User: UID" to our view, select "Provide default argument" below "Action to take if argument is not present," and select "PHP Code" under "Default argument type." Here we can provide a code snippet to return a list of User ids of users that have submitted the form.

module_load_include('inc', 'webform', 'includes/webform.submissions');
$submission_array = webform_get_submissions(/*node id of webform we are checking for*/);
$uids = array();
foreach($submission_array as $submission) {

  $uids[] = $submission->uid;
}
return implode(',', $uids);

This will gives us a comma separated string of user ids. The default "Validator options" are fine but be sure to check "Allow multiple terms per argument" and "Exclude the argument." After updating, your view now filters down to users that have not submitted the webform! To double check that this is happening, you can look at the query below the preview. Near the end of the query in the WHERE clause, you should see something like users.uid NOT IN (110, 13028, 210, 107, 35329, 35330, 35331). The list of numbers are the user ids that are being filtered. If no one has submitted the form, then this of course will be empty.

Now I admit, this is kinda gross. I shudder any time I include php in configuration. It is, however, a very straight forward way to get the results requested while staying in views, therefore leaving the output in the hands of a site builder/administrator. There may be some clever ways to achieve the same thing using something like Webform Report, or even a different views configuration, but nothing jumped out at me. However, if you have solved this in a different way I would love to hear about it.

Using the Data Module's "Relate to Node" Functionality

rho — Sun, 04 Mar 2012 03:44:18 +0000

While I'm on the topic of the Data module, I'd like to share my thoughts on some of the confusion surrounding use of the Data Node module included with the package. (see issues 976292 and 898562)

It's my opinion that the bulk of the functionality in the Data Node module has been intentionally "left undone." Instead, the module is giving us the tools to allow us to implement node relationships as needed, ourselves (think API). My thinking is that this was done to allow the maximum amount of flexibility in relating other data to nodes by minimizing assumptions about what the relationship should be. I have in no way validated this with any of the module maintainers, nor is it denoted in any documentation that I am aware of. What follows is my "average" use case for this module, and some thoughts on more advanced implementations.

When enabled, this functionality is apparent in Drupal's admin UI at admin/build/data/edit/%table_name/node by clicking on the edit link next to a table at admin/build/data/overview then clicking the "Relate to Nodes" tab. This page presents a form asking you which content type you would like the table related to, and the column name of the id key in the table you are referencing. Simple right? Well sorta... When you submit this form and happily skip over to views to reference the node table, it quickly becomes apparent that nothing has happened. Checking the data_table_node table in the database will reveal it to be empty. So what's up here? Is this just an unfinished piece?

After taking a look in the data_node.module things start to make a bit more sense. At first glance we see some tantalizing functions, especially:

/**

 * Add a relationship between a data table and a node.

 */
function data_node_add($table, $id, $nid) {

  $save = array(

    'data_table_name' => $table->get('name'),

    'id' => $id,

    'nid' => $nid,

  );

  return drupal_write_record('data_table_node', $save);
}
/**

 * Remove a relationship between a data table and a node.

 */
function data_node_remove($table, $id, $nid) {

  db_query("DELETE FROM {data_table_node} WHERE data_table_name = '%s' AND id = %d AND nid = %d", $table->get('name'), $id, $nid);
}

Typically I'll stop right here. I really only use the Data module for custom reporting, and when doing so I handle the CRUD functions for the new data type myself. My data type's row reference to nodes are nearly always a 1 to 1 mapping. To further simplify things for myself, the $id I use in my custom data type is often the node id of it's intended reference. This makes my calls to these functions look something like:

  //insert my_table with a nid key

  ...

  //inform Data Node of the reference

  $my_table_object = data_get_table('my_table');

  data_node_add($my_table_object, $nid, $nid);

This will populate the data_table_node table so that when we use the relationship in out data type view it will return results. Of course deletion will be handled similarly.

This is admittedly a somewhat basal interaction with this module, though it is often enough to satisfy my needs. However Data Node allows for much more complexity and has a certain level of user interaction built in just below the surface.

It's not until we start thinking about the data structures involved that the scope of the allowed complexity becomes apparent. It is easy to assume that referencing a data type to a node is always going to be 1 to 1 (much like the typical use of CCK's Node Reference.) However, this may not always be the case. It is not required that the data table's id be the nid of the node it is referencing. It only has to be unique within the table. Because of this, a large field of possibilities emerge. You may have data type rows referencing many nodes each (1 to many), many data type rows referencing a single node (many to 1), or, of course, any number of data type rows referencing any number of nodes (many to many). The data_table_node table along with the provided CRUD functions, like the ones mentioned above, will allow for this. I think that this flexibility is a big reason that the module has been left so open.

Lastly, a closer look at the Data Node module will reveal some rather fancy display functions for the underlying relationship CRUD.

/**

 * Render an add link for a given item..

 */
function data_node_render_add_link($table, $id, $nid) {

  drupal_add_css(drupal_get_path('module', 'data_node') . '/data_node.css');

  drupal_add_js(drupal_get_path('module', 'data_node') . '/data_node.js');

  $title = _data_node_get_title($nid);

  $table_name = $table->get('name');

  $class = "data_node_link-{$table_name}-{$id}-{$nid}";

  return l(t('Add to !title', array('!title' => $title)), data_node_add_path($table, $id, $nid), array('attributes' => array('class' => "data-node-add $class"), 'query' => drupal_get_destination()));
}

/**

 * Render a remove link for a given item.

 */
function data_node_render_remove_link($table, $id, $nid) {

  drupal_add_css(drupal_get_path('module', 'data_node') . '/data_node.css');

  drupal_add_js(drupal_get_path('module', 'data_node') . '/data_node.js');

  $title = _data_node_get_title($nid);

  $table_name = $table->get('name');

  $class = "data_node_link-{$table_name}-{$id}-{$nid}";

  return l(t('Remove from !title', array('!title' => $title)), data_node_remove_path($table, $id, $nid), array('attributes' => array('class' => "data-node-remove $class"), 'query' => drupal_get_destination()));
}

These are the two pertinent functions. They both return a link that will hit a page callback to do just what you would expect. Add or remove a node relationship. This allows you "expose" the functionality to the user. The link could be placed on a view or node page to allow users to add or remove the relation to a specific data type themselves, "on the fly". This, in combination with the flexibility of the relationship itself, lends to a huge variety of possible use cases with relatively few function calls.

So wrapping this up. Data Node module is best thought of as an API. It doesn't do so much right out of the box, but with minimal implementation it becomes a fairly powerful tool.

Adopting a Table with Schema using Data Module

rho — Sat, 03 Mar 2012 20:19:36 +0000

When working with medium to larger sized web applications, inevitably the requirement comes up for some advanced data reporting. The spectrum of requests here can obviously be pretty broad and is often beyond what you can accomplish with the default tables provided by Drupal and the installed modules. This tends to lead us to creating custom tables to track and manage the requested reports. Along with writing all of the necessary CRUD functions to make sure our new table is managing data appropriately, we also have to provide some sort of display or an export. Views can handle this latter requirement quite nicely. So it is here that we can turn to modules like Data or the now depricated Table Wizard to bring our new table under views "control." This gives us the added bonus of taking the display configuration out of the hands of the developer and placing it into the site builder/administrator's domain.

In a recent project just such a reporting request came up. The report was fairly complex and was to be visible to a larger subset of users. I wound up managing this report with a custom table and I turned to Data module to allow views to handle the output. After installing my custom module which created the custom table, I navigated to admin/build/data/adopt. Expecting to see my table in the list of "adoptable" tables, I was a bit confused when it was nowhere to be found. After a bit of digging I realized that tables declared using Schema API were considered "owned" by the module and not included in the list of adoptable tables. This makes some sense as you don't want just any table adopted by Data. Just imagine when an admin who's not quite sure what he or she is doing, decides to adopt and then drop the node table. I'd rather not...

So this leaves us with the question, "How do I get Data module to adopt my table?" From what I can tell, the creators of the data module expect us to use the Data API to handle table creation and CRUD. Personally I don't like the idea of this. I already understand and like working with Drupal's core Schema API, and don't want to adopt another layer of abstraction. I only want to utilize Data module to throw my table up to views. So after looking through how adoption is handled in the module, I found that really there is nothing preventing Data from adopting these schema declared tables. They are simply being made unavailable to the form at admin/build/data/adopt. This lead me to attempt to adopt my table right after it is generated in my module's .install file. This wound up working quite nicely and is implemented as follows:

function my_module_install() {

  //install schema as normal

  drupal_install_schema('my_table');

  //make sure we have the data module

  include_once(drupal_get_path('module', 'data') .'/data.module');

  data_include('DataTable');

  //instanciate the table we just created with the DataTable class

  $my_table_object = DataTable::instance('my_table');

  //tell Data module to adopt the table

  $my_table_object->adopt();

  DataTable::clearCaches();
}

After installing the module you should be able to see your custom table at admin/build/data. Data module is now obviously a dependency so be sure that it is installed and enabled before installing your custom module.

I realize that I could write my own views handlers for the custom table data I am providing, but I have found that to be a fairly time consuming (and often esoteric) task. When all we are after is a single, somewhat unique report, I feel that integration with the Data module and it's corresponding integration with views is simple, quick, and more than adequate.

Quick Stock Quote on Page Refresh

rho — Fri, 16 Sep 2011 04:28:56 +0000

I thought I would throw a post up, demonstrating a "quick and easy" use case of the Stock API module, and simultaneously, give this site's GeSHi filter a quick test run.

A few days ago I encountered a site requirement asking for a simple informative stock quote block on a Drupal 6.x installation. The format required was something like:
NFLX 208.75 -1.30 Sep 13 7:30 EST
My initial thought was to enable the Stock module and simply configure and theme the built in block. The stock module will allow the management of multiple stocks on a per-user basis, and provides a block that displays this information in a table. There is no doubt that stock module is useful but in this instance it is overkill. All we are after is a simple quote from a single unchanging stock symbol displayed in a single line of text.

So let's take a short step back to the stock API module. There is really one "go to" function when grabbing a quote from the stock api and that is stockapi_load($symbol). This function is defined like so:

function stockapi_load($symbol) {

  if (!empty($symbol)) {

    $stock = db_fetch_array(db_query("SELECT * FROM {stockapi} WHERE symbol = '%s'", $symbol));

    if (!$stock) {

      $stock = stockapi_fetch($symbol);

      if ($stock) {

        if ($stock[8] != 'N/A') {

          // Date is 'N/A' means an invalid stock symbol

          stockapi_save($stock);

          // Load again so it can show for the first time

          $stock = stockapi_load($symbol);

        }

      }

    }

  }

  return $stock;
}

As you can see the stock API module is wanting to store stock information in the database to be updated on cron runs. It does this as a type of database caching. This way if a site is pulling information on many stocks, potentially every page load, compounded by many users the API can retrieve the information with a simple query to the local database. Not only is this method much faster than hitting the third party service (yahoo) every time, it is able to serve saved information (especially handy if that service happens to be down or a connection cannot be established). This feature along with returning a nice keyed array of stock information is reason enough to love this function. However, I think we could go a bit simpler still. We only need information on one stock site wide, and in this instance that information should be as current as possible. Furthermore, I would like to avoid setting up a cron job to run every half hour just to keep stock information current. Rather, we look further into the Stock API and make a more basal call to stockapi_fetch($symbol);. This function is a direct call to the 3rd party service, in this case yahoo:

/**

 * Fetch the stock info for a given ticker symbol from Yahoo!

 */
function stockapi_fetch($symbol) {

  if (empty($symbol)) {

    return FALSE;

  }

  $fields = 'snl1c1ohgvd1t1';

  /*

    "s"  => "Symbol",

    "n"  => "Name",

    "l1" => "Last",

    "c1" => "Change",

    "o"  => "Opening",

    "h"  => "High",

    "g"  => "Low",

    "v"  => "Volume",

    "d1" => "Date",

    "t1" => "Time"

   */

  $host = 'http://download.finance.yahoo.com';

  $url = $host .'/d/quotes.csv?s='. urlencode($symbol) .'&f='.$fields.'&e=.csv';

  $result = drupal_http_request($url);

  ...

This ensures fresh data, without a cron run to update the database. This function is not quite as nice as the stockapi_load() function in that the array it returns is not keyed. The commented section above (from the module) comes to the rescue. It is in the same sequence as the array returned so it can be used as a reference. So to return something like our requirement example above:
NFLX 208.75 -1.30 Sep 13 7:30 EST
We would write something like:

$output = '';
$my_stock = stockapi_fetch('NFLX');
if($my_stock) {

  $output .= '<span class="my-stock-quote">'.$my_stock[0].' '.$my_stock[2].' '.$my_stock[3].' '.$my_stock[8].' '.$my_stock[9].' EST</span>';
}
return $output;

I wound up throwing a variant of the snippet above into a block created in my module, allowing me to then jump to panels and throw the output wherever I wanted.

Now I know... the example is somewhat contrived. There is no "secret" here. Everything outlined in this post would quickly be revealed by only a few minutes of looking through the Stock API module. I wanted to demonstrate that by making a simple call to the Stock API I was able to save significant time in themeing, as well as gain flexibility in function. The alternative would be wrangling the output of the Stock module's block, and making concessions for it's functional behavior. It is easy to fall into the thinking that Drupal site building is just finding a module that is a closest fit and wrestling with what it gives us. Indeed sometimes that may be the case (Organic Groups comes to mind), but to follow that line of thinking blindly is most certainly a mistake.