Pushing the envelope with Display Suite: leveraging Views.

In the first article of our series, we introduced Display Suite and showed how it allows you to easily visualize nodes and fields without writing any code. Just like Panels, Display Suite is one of those indispensable tools for Drupalistas who are fed up with hacking templates to do stuff which shouldn't be that complicated. If you haven't heard of Display Suite already, check out the project page!

We demonstrated how you could use Display Suite to show lists of referenced nodes within a build mode. However, you don't get a lot of control over how and what Display Suite shows. Display Suite should be able to do more, right? Let's find out.

We'll return to our cookbook example. Our Cook nodes show lists of referencing Recipe nodes. This results in a neat list of recipes for a particular chef. But what if our top chef stars in a regular TV show and we want to display in which show he'll be featured next?

First, create a new content type called 'Show' with two extra fields. First, a node reference field called 'Cook' which - obviously - references available cook nodes. Second, you'll need to install the Date module and add a Datetime field called 'Transmission'. This field indicates when a show will be or has been aired.

Now, if you'd try the solution outlined in our previous article, you'll notice it will show all transmissions while we are interested in showing only the next upcoming show in which a chef will star. Backstage, Display Suite runs a basic SELECT query which fetches all the shows with a reference to a particular cook. You don't get any control over the conditional behavior of the query. This makes perfect sense because DS is not intended to handle complicated queries. If you want to get anything done in Drupal, you'll let Views handle it. And of course, the authors of Display Suite have provided a way to integrate views.

The basic idea here is to pass the node id (nid) of the active cook node as an argument to a block View turned into a Display Suite field. Within Views, we are free to use filters, relationships, row style and list style plugins,... Display Suite will integrate the output of the view transparently into the active build mode.

Start by creating a new block View. Add a new argument (not a filter) to your View. This should be the node reference field you've added to your 'Show' content type. Configure the argument to provide a 'default argument'. Set the argument type to 'fixed entry'. Leave the 'default argument' textfield empty. Now add a few fields to your View. The node title and the transmission time will do the job.

Let's move over to the DS Fields manager at 'admin/ds/nd/fields'. This panel allows you to manage how Display Suite handles fields. Even better: it allows you to turn blocks into fields which can be used within any build mode. Sweet!

Click on the collapsed 'add new block field' fieldset. This form allows you to turn a block into a field. Just provide a name (i.e. Transmissions) and a machine field key (i.e. transmissions). Select the block you want to display in your field. You'll notice your Views block will be available too. Click 'save block field'. Make a note of the field key you've just entered. We'll need it later.

Switch to the DS Layout manager at 'admin/ds/layout' and select the 'Full node' build mode for your Cook type. You'll find your new 'Transmissions' field between the disabled fields. Just drag and drop it in a region.

Let's take a peek at how things look front end. Create a cook node, a few recipes and a few transmissions which reference your cook. You'll see how the referenced recipes will show up nicely. But the transmissions are missing in action. Remember how we provided a default argument to the view with a fixed, empty entry? Well, that's our culprit.

At this point, you're probably wondering why on earth I made you add an argument to your block view. If you want to filter out nodes based on a node reference dynamically, you'll need an argument. If we've been taught anything when it comes to Views, passing arguments to block Views is near impossible. Then again, we still need a block view to turn into a Display Suite field.

Actually, the question here is: how do we pass the node id of our active cook to a block view?

We'll need to dive into a bit of code to do that. We're going to bridge the gap between the node and the View with the magic of hook_ds_fields_alter(). In a nutshell: we'll override the way Display Suite handles the field with our own custom implementation.

Create a new custom module and add this implementation of hook_ds_fields_alter().

/**
 * Implementation of hook_ds_fields_alter(&$fields)  
 */ 
function dsexample_ds_fields_alter(&$fields) {
  if (isset($fields['transmissions'])) {
    // 1. We change the type of the field to function instead of block
    $fields['transmissions']['type'] = DS_FIELD_TYPE_FUNCTION;
 
    // 2. Defines a nice formatter callback method: render_view_block_arguments
    $fields['transmissions']['properties']['formatters']['render_view_block_arguments'] = t('Default');
 
    // 3. Add some extra properties which we can use in the function later on.
    $fields['transmissions']['properties']['arguments'] = array(
      'field_cook_nid' => array(
        'key' => 'default_argument_fixed',
        'field_object_value' => 'nid'
       )
    );
  }
} 

Remember the DS field key you had to keep in the back of your head? We'll need it here. $fields is an array of all the available fields for any given node and build mode. You'll need to single out the transmissions field since that's the one we are going to alter. So change the key of the $fields array to match with your own field key.

Now, let's skim through the code.

1. Every field has it's own type which is defined as a constant. The transmissions field is a DS_FIELD_TYPE_BLOCK constant. We'll change that to a DS_FIELD_TYPE_FUNCTION. That's how we let DS know that it has to run a custom formatter function instead of a block when it's parsing the field.

2. We'll need to let DS know which function to execute. You'll do that by setting a new key/value pair in $fields['transmissions]['properties]['formatters]. The key is the function name (i.e. render_view_block_arguments) and the value is the label which will be shown on the lay out manager when you select a formatter.

3. Finally, we'll need to define which field we are going to pass to the view as an argument. We'll do that in $fields['transmissions]['properties]['arguments]. This is actually a good place to add all sorts of extra data to our field to be used further down the road. Recall the empty fixed entry argument we've set in our block View? We're going to fill the 'arguments' property with the node id of the active cook node. Change 'field_cook_nid' with the machine name of your Views argument. Exporting your View in code allows you to retrieve the correct name.

The 'key' property is set to 'default_argument_fixed' which is just fine. The 'field_object_value' property should match with the name of the property of the active node you want to pass to the View as an argument. Obviously, we want to pass the node id of the active node.

We're not done yet. We still need to define our render_view_block_arguments() formatter function. Just copy and paste the code below.

 
/**
 * Render a ds field which was originally a block through this function.
 */
function render_view_block_arguments($field) {
  $data = '';
  list($module, $delta) = explode('|', $field['properties']['block']);
  list($name, $display_id) = explode('-', $delta);
 
  // Load the view.
  if ($view = views_get_view($name)) {
    if ($view->access($display_id)) {
      if (isset($field['properties']['arguments'])) {
        // let's pass all arguments we got from our parent and pass it to our embedded view.
        foreach ($field['properties']['arguments'] as $argument => $value) {
          $view->display[$display_id]->handler->options['arguments'][$argument][$value['key']] = $field['object']->{$value['field_object_value']};
        }
      }
      $output = $view->execute_display($display_id);
      if (!empty($output['content'])) {
        $data = theme('block', (object) $output);
      }
    }
 
    $view->destroy();
  }
 
  return $data;
}

Let's take a moment to review this function. It will be run when our transmissions DS field is parsed. First it will retrieve our View, then it will sink the properties we've set in our hook_ds_fields_alter() implementation and finally it will execute and display the View.

Check and double check your code for any mistakes. Let's take a peek at our cook node. Will it display the upcoming feature of our star chef? Well, not yet. Display Suite caches field settings to keep things running smoothly. hook_ds_fields_alter() is only run when a field hasn't been cached yet. Clearing your cache should do the trick. Remember, you have to do this every time you make a substantial change to hook_ds_fields_alter().

And... there you have it:

This is how things should be looking. A nice list of transmissions featuring your star chef

Mission accomplished!

Tips

Since we're using Views now to control our list, we can use it's entire toolset of filters, sorting options, relationships and what-not. We can push things a bit further. Display Suite also provides a row style plugin for Views. Which actually means you can define a build mode for your nodes in Views and control it through the DS lay out manager

Caveats

This technique has a few caveats though which can discourage the intrepid developer.

First and foremost, you'll need to clear your cache if you update hook_ds_fields_alter(). It's the first thing you should try in case of trouble.

The dreaded 'error on line 294 in ds.module' error. If you've made a typo in $fields[]['properties']['formatters'], DS will break because it tries to execute an unexisting function. Fix the error and try clearing your cache. If the problem persist, you should delete your field in 'admin/ds/nd/fields', clear your cache, then create it again and clear your cache once more.

Your View might not get executed without any apparent reason. Well, actually there is one. If your View name is too long (i.e. carousel_of_images_of_ponies_and_kittens), the Blocks module runs into trouble. Views will return an MD5 hash of your View name instead. Our render_view_block_arguments() can't find the View based on the hash name and break. For good measure, keep those View names short and sweet.

Even then, your View might stubbornly refuses to be executed. Check the block display in your View through 'admin/build/views'. The argument property in your block display is probably inherited from the defaults display. The above code expects the property to be explicitly set on the block display. So, click the 'override' button of the argument, update and save the View.

The perceptive reader will no doubt notice that you'll need to accommodate for every particular View field by hard coding it's name and the arguments. This can result in a lot of code repetition. It also means writing Yet Another Custom Module. Not to mention hard coding parameters against a specific implementation is bad practice.

So, the next step would involve devising a more generic, reusable approach.