Advertising sustains the DA. Ads are hidden for members. Join today

On this page

API (D6)

Last updated on
30 April 2025


This the API page for the Drupal 6 version of Display Suite. Information regarding Drupal 7 is available here.

Hooks

This is a list of hooks you can implement in your custom module

DS API

This is a list of API functions you can also use in your own implementations.

Views support

Telling Display Suite about your objects and fields

hook_ds_api

By implementing this function, you will tell Display suite that there is a new
object available. You'll automatically get the interface for build modes, fields, info and plugins. For inspiration, take a look at nd.module in Node displays.

/**
 * Implementation of hook_ds_api().
 */
function hook_ds_api() {

  return array(
    'title' => 'Title in display suite',
    'module' => 'nd',
    'object' => 'node',
    'views_base' => 'node', // can be either a string or an array.
    'types' => 'node_get_types',
    'extra' => array('has_body'),
    'plugins_exclude' => array(NODE_BUILD_RSS),
    'regions_single' => array(NODE_BUILD_RSS),
    'help' => array('Node displays help'),
    'no_new_build_modes' => TRUE, // Disable creating new build modes. Omit the key if you want it
  );
}

Back to top

hook_ds_info_alter

Alter the information. Only happens on the info screen.


/**
 * Implementation of hook_ds_info_alter().
 */
function hook_ds_info_alter(&$help, $module) {
  if ($module == 'nd') {
    $help[] = t('<h3>Node displays CCK</h3><p>In the nd_cck folder you can find nd_cck.tpl.php which is optimized for CCK fields. You can copy this to your themes directory if you want to use your own version. It\'s a replacement for the default CCK content-field.tpl.php file. If Node reference is enabled, additional formatters will be available to render the node through the Display suite.</p>');
  }
}

Back to top

hook_ds_default_settings

You can use this hook to put default dislay settings in code. You can grab this code by using the export tab in the tools menu item. This hook is also used by features.

function hook_ds_default_settings() {
 $data = array(
    'nd' => array(
      'full' => array(
        'list' => array(
          'fields' => array(
            'title' => array(
              'weight' => '-23',
              'format' => '',
              'region' => 'disabled',
              'labelformat' => 'hidden',
            ),
          ),
        ),
      ),
    ),
  );
  return $data;
}

hook_ds_fields

Returns fields from code. Depending on the type key, keys can be different you need to define. For inspiration take a look at nd.module in Node displays. keys:

  • title: name of the field
  • type: type of the field. You can choose between 6 constants:
    1. DS_FIELD_TYPE_THEME: uses a theming function.
    2. DS_FIELD_TYPE_FUNCTION: uses a custom function. The object, key and the complete field is passed to this function
    3. DS_FIELD_TYPE_PREPROCESS: the field will be available as a variable already
    4. DS_FIELD_TYPE_IGNORE: the field will be available in the object content array
    5. DS_FIELD_TYPE_CODE: PHP code field
    6. DS_FIELD_TYPE_BLOCK: block field
    7. DS_FIELD_TYPE_GROUP: fieldgroup
  • status: status of the field. You can choose between 2 constants in code.
    1. DS_FIELD_STATUS_STATIC: static field, not overridable by the UI
    2. DS_FIELD_STATUS_DEFAULT: default field, overridable by the UI.
  • file: path of the file where the function is, only applicable for DS_FIELD_TYPE_FUNCTION
  • properties: array of keys
    1. formatters: an array of theming functions
    2. code: php code or tokens for DS_FIELD_TYPE_CODE
    3. token: whether this field must be evaluated by token for DS_FIELD_TYPE_CODE
    4. block: a string which defineds the block and delta: eg views|story_list-block_1.
    5. render: how to render the block. You may choose between 3 constants:
      1. DS_BLOCK_TEMPLATE: render block through template
      2. DS_BLOCK_TITLE_CONTENT: render only title and content
      3. DS_BLOCK_CONTENT: render only content
/**
 * Implementation of hook_ds_fields().
 */
function hook_ds_fields($type_name, $build_mode, $extra) {

  $fields = array(
    'title' => array(
      'title' => t('Title'),
      'type' => DS_FIELD_TYPE_THEME,
      'status' => DS_FIELD_STATUS_STATIC,
      'properties' => array(
        'formatters' => array(
          'nd_title_h1_nolink' => t('H1 title'),
          'nd_title_h1_link' => t('H1 title, linked to node'),
        ),
      ),
    ),
  );

  // Taxonomy support.
  if (module_exists('taxonomy')) {
    $fields['terms'] = array(
      'title' => t('Taxonomy'),
      'type' => DS_FIELD_TYPE_PREPROCESS,
      'status' => DS_FIELD_STATUS_STATIC,
    );
  );

  return array('nd' => $fields);
}

Every theming function gets one parameter with following keys.

  • title: label
  • type: one of the type constants
  • status: one of the status constants
  • properties: an array of properties, which kan be, code, formatters, block, render etc
  • key: key of the field
  • module: the name of module (eg nd, ud, cd, or hds)
  • object: the complete object (eg, node, user or comment)
  • object_type: name of object (eg, node, user or comment)
  • formatter: the theming function
function theme_nd_bodyfield($field) {
  return $field['object']->content['body']['#value'];
}

The return array of hook_ds_fields can take a sixth parameter, in which you can exclude the content types you don't want your field to appear in. In the following example this means that the field will show up in the layout for page, but not for event.

<?php
**
 * Implementation of hook_ds_fields().
 */
function hook_ds_fields($type_name, $build_mode, $extra) {

  $fields = array(
    'custom_field' => array(
      'title' => t('Title'),
      'type' => DS_FIELD_TYPE_THEME,
      'status' => DS_FIELD_STATUS_STATIC,
      'properties' => array(
        'formatters' => array(
          'nd_title_h1_nolink' => t('H1 title'),
          'nd_title_h1_link' => t('H1 title, linked to node'),
        ),
      ),
      'exclude' => array('page' => 0, 'event' => 'event'),
    ),
  );

  return array('nd' => $fields);
?>

Back to top

hook_ds_fields_alter

Alter fields.


/**
 * Implementation of hook_ds_fields_alter().
 */
function hook_ds_fields_alter(&$fields) {
  if (isset($fields['title'])) {
    $fields['title']['title'] = 'My new title';
  }
}

Back to top

hook_content_build_modes

This hook is actually a hook from CCK, which we're also are using. If you are defining content build modes for something else than nodes, you should also add the module key.

/**
 * Implementation of hook_content_build_modes().
 */
function hook_content_build_modes() {
  $build_modes = array(
    'module' => array(
      'title' => t('module displays'),
      'build modes' => array(
        'full' => array(
          'title' => t('Full node'),
          'weight' => -1,
          'module' => 'module',
        ),
        'teaser' => array(
          'title' => t('Teaser'),
          'weight' => 1,
          'module' => 'module',
        ),
      )
    )
  );

  return $build_modes;
}

Back to top

hook_ds_buildmodes_alter

Alter build modes.


/**
 * Implementation of hook_ds_buildmodes_alter().
 */
function hook_ds_buildmodes_alter(&$build_modes) {
  unset($build_modes['nd']['full'];
}

Back to top

hook_ds_plugins and hook_ds_plugins_alter

You can write your own DS plugins. If you want inspiration, take a look at the plugins which come with the display suite module.

Back to top

Rendering Display Suite displays

Display Suite calls two key functions to assemble and render a display. To see this in action, look at nd_nodeapi() in the Node Displays module.

ds_build_fields_and_regions

Assembles field and region data for a display, but does not render it.

/**
 * Get fields and regions for an object.
 *
 * @param stdClass $object The object to manipulate.
 * @param string $module The module that is requesting.
 */
function ds_build_fields_and_regions(&$object, $module);

Back to top

ds_render

Given data assembled by ds_build_fields_and_regions(), this function will return the fully-built region. This function is statically cached, so displays built more than once will not cause an extra load.

/**
 * Return rendered content for an item
 *
 * @param string $key
 *  A key for the object, e.g. an NID
 * @param stdClass $object 
 *  The object to manipulate, e.g. a $node object
 * @param string $module 
 *  The name of the module requesting the render
 * @param array $vars 
 *  The variables required for rendering
 *
 * @since 6.x-2.0
 *
 * @return 
 *  a string containing the fully rendered display
 */
function ds_render($key, $object, $module, $vars);

Back to top

ds_render_content

This function does the heavy lifting for rendering a display, but since 2.0 is deprecated in favour of ds_render() instead, which will ensure that already rendered displays are statically cached.

/**
 * Render content for an object.
 *
 * @param stdClass $object The object to manipulate.
 * @param string $module The module that is requesting.
 * @param array $vars The variables need for rendering.
 * @param string $theme_function The theming function for a field.
 */
function ds_render_content($object, $module, $vars, $theme_function = 'ds_field');

Returning information about Display Suite settings

Back to top

ds_default_value

/**
 * Return a value or return the default if empty.
 *
 * @param array $settings The settings loaded for a type.
 * @param string $build_mode The name of the build mode.
 * @param string $type The name of the type to search (ie fields, regions)
 * @param string $key The name of the key to search in $type.
 * @param string $search_key The name of the key to search in $key.
 * @param string $default The default value.
 * @param mixed default value.
 */
function ds_default_value($settings, $build_mode, $type, $key = NULL, $search_key = NULL, $default = NULL);

Back to top

ds_get_fields

/**
 * API function to get fields.
 *
 * @param string $module The name of the module.
 * @param string $type_name The name of object (ie, page or story for node types, profile for users)
 * @param string $build_mode The build mode.
 * @param array $extra Extra properties we might want to check on (ie has_body property).
 * @param boolean $reset Whether we need to reset the fields cache or not.
 * @param boolean $cache Whether we need to cache the the fields or not.
 * @return array of fields.
 */
function ds_get_fields($module, $type_name, $build_mode, $extra = array(), $reset = FALSE, $cache = TRUE);

Back to top

/**
 * Function to check if the $links field is set for a type and build mode.
 *
 * @param string $module The module to get the settings for.
 * @param string $type_name The name of the object type.
 * @param string $build_mode The key of the build mode
 * @param string $field The name of the field to check for.
 */
function ds_show_links($module, $type_name, $build_mode, $field);

Back to top

ds_api_info

/**
 * Return API info about a module and type.
 *
 * @param string $module The module to get the API info from.
 * @param string $type_name The object type name.
 */
function ds_api_info($module, $type_name = 'all');

Back to top

ds_get_build_modes

/**
 * Api function to return all build modes.
 *
 * @param string $module Return build modes for a module.
 * @param boolean $reset Whether to reset the build modes.
 * @return array Collection of build modes.
 */
function ds_get_build_modes($module = NULL, $reset = FALSE);

Working with Views

Back to top

ds_views_row_VIEWS_BASE_TABLE

If you are create a new object and want it rendered through the DS views plugin, you must create a function with the views base name of your object. See nd.module of node displays.

/**
 * Render the node object through the DS views plugin.
 *
 * @param array $vars The variables to manipulate.
 * @param string $build_mode The build mode to use on this object.
 */
function ds_views_row_node(&$vars, $build_mode) {
  $nid = $vars['row']->nid;
  if (!is_numeric($nid)) {
    return;
  }

  $node = node_load($nid);
  if (empty($node)) {
    return;
  }

  $node->build_mode = $build_mode;

  // Check the teaser flag and show_links flag.
  $teaser = ($node->build_mode != 'full') ? TRUE : FALSE;
  $show_links = ds_show_links('nd', $node->type, $build_mode);

  // Build object.
  $vars['object'] = node_view($node, $teaser, FALSE, $show_links);
}

Back to top

ds_views_row_adv_VIEWSNAME

It's also possible to select the advanced views selector in the Display Suite plugin. Again, you'll have to create a function with the prefix which equals the views name. The code underneath has some custom code to alter the build mode based on a counter on a view called 'story_list'.
In the future, we might add some of these implementation in DS itself.

function ds_views_row_adv_story_list(&$vars) {

 $nid = $vars['row']->nid;
 if (!is_numeric($nid)) {
   return;
 }

 $node = node_load($nid);
 if (empty($node)) {
   return;
 }

 // Custom build mode selection
 static $i = 0;
 if ($i < 1) {
   $node->build_mode = 'sticky';
 }
 elseif ($i < 2) {
   $node->build_mode = 'teaser';
 }
 else {
   $node->build_mode = 'title_list';
 }
 $i++;

 // Check on page.
 if (isset($_GET['page'])) {
   $node->build_mode = 'title_list'; // From page 1, only use this build mode.
 }

 // Check the teaser flag and show_links flag.
 $teaser = ($node->build_mode != 'full') ? TRUE : FALSE;
 $show_links = ds_show_links('nd', $node->type, $node->build_mode);

 // Build object.
 $vars['data_object'] = node_view($node, $teaser, FALSE, $show_links);
}

Back to top

Help improve this page

Page status: Not set

You can: