ds.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Hooks provided by Display Suite module.
   6  */
   7
   8 /**
   9  * @addtogroup hooks
  10  * @{
  11  */
  12
  13 /**
  14  * Implements hook_ctools_plugin_api().
  15  */
  16 function hook_test_ctools_plugin_api($module, $api) {
  17   if (($module == 'ds' && $api == 'ds') || ($module == 'ds_extras' && $api == 'ds_extras')) {
  18     return array('version' => 1);
  19   }
  20 }
  21
  22 /**
  23  * Expose Display suite field settings.
  24  *
  25  * This hook is called by CTools. For this hook to work, you need
  26  * hook_ctools_plugin_api(). The values of this hook can be overridden
  27  * and reverted through the UI.
  28  */
  29 function hook_ds_field_settings_info() {
  30   $dsfieldsettings = array();
  31
  32   $dsfieldsetting = new stdClass;
  33   $dsfieldsetting->disabled = FALSE; /* Edit this to true to make a default dsfieldsetting disabled initially */
  34   $dsfieldsetting->api_version = 1;
  35   $dsfieldsetting->id = 'node|article|default';
  36   $dsfieldsetting->entity_type = 'node';
  37   $dsfieldsetting->bundle = 'article';
  38   $dsfieldsetting->view_mode = 'default';
  39   $dsfieldsetting->settings = array(
  40     'title' => array(
  41       'weight' => '0',
  42       'label' => 'hidden',
  43       'format' => 'default',
  44       'formatter_settings' => array(
  45         'link' => '1',
  46         'wrapper' => 'h3',
  47         'class' => '',
  48       ),
  49     ),
  50     'node_link' => array(
  51       'weight' => '1',
  52       'label' => 'hidden',
  53       'format' => 'default',
  54     ),
  55   );
  56   $dsfieldsettings['node|article|default'] = $dsfieldsetting;
  57
  58   return $dsfieldsettings;
  59 }
  60
  61 /**
  62  * Expose default layout settings info.
  63  *
  64  * This hook is called by CTools. For this hook to work, you need
  65  * hook_ctools_plugin_api(). The values of this hook can be overridden
  66  * and reverted through the UI.
  67  */
  68 function hook_ds_layout_settings_info() {
  69   $dslayouts = array();
  70
  71   $dslayout = new stdClass;
  72   $dslayout->disabled = FALSE; /* Edit this to true to make a default dslayout disabled initially */
  73   $dslayout->api_version = 1;
  74   $dslayout->id = 'node|article|default';
  75   $dslayout->entity_type = 'node';
  76   $dslayout->bundle = 'article';
  77   $dslayout->view_mode = 'default';
  78   $dslayout->layout = 'ds_2col';
  79   $dslayout->settings = array(
  80     'hide_empty_regions' => 0,
  81     'regions' => array(
  82       'left' => array(
  83         0 => 'title',
  84         1 => 'node_link',
  85       ),
  86       'right' => array(
  87         0 => 'body',
  88       ),
  89     ),
  90     'fields' => array(
  91       'title' => 'left',
  92       'node_link' => 'left',
  93       'body' => 'right',
  94     ),
  95     'classes' => array(),
  96   );
  97   $dslayouts['node|article|default'] = $dslayout;
  98
  99   return $dslayouts;
 100 }
 101
 102 /**
 103  * Expose default view modes.
 104  *
 105  * This hook is called by CTools. For this hook to work, you need
 106  * hook_ctools_plugin_api(). The values of this hook can be overridden
 107  * and reverted through the UI.
 108  */
 109 function hook_ds_view_modes_info() {
 110   $ds_view_modes = array();
 111
 112   $ds_view_mode = new stdClass;
 113   $ds_view_mode->disabled = FALSE; /* Edit this to true to make a default ds_view_mode disabled initially */
 114   $ds_view_mode->api_version = 1;
 115   $ds_view_mode->view_mode = 'test_exportables';
 116   $ds_view_mode->label = 'Test exportables';
 117   $ds_view_mode->entities = array(
 118     'node' => 'node',
 119   );
 120   $ds_view_modes['test_exportables'] = $ds_view_mode;
 121
 122   return $ds_view_modes;
 123 }
 124
 125 /**
 126  * Define fields. These fields are not overridable through the interface.
 127  * If you want those, look at hook_ds_custom_fields_info().
 128  *
 129  * @param $entity_type
 130  *   The name of the entity which we are requesting fields for, e.g. 'node'.
 131  *
 132  * @return $fields
 133  *   A collection of fields which keys are the entity type name and values
 134  *   a collection fields.
 135  *
 136  * @see ds_get_fields()
 137  */
 138 function hook_ds_fields_info($entity_type) {
 139   $fields = array();
 140
 141   $fields['title'] = array(
 142
 143     // title: title of the field
 144     'title' => t('Title'),
 145
 146     // type: type of field
 147     // - DS_FIELD_TYPE_THEME      : calls a theming function.
 148     // - DS_FIELD_TYPE_FUNCTION   : calls a custom function.
 149     // - DS_FIELD_TYPE_CODE       : calls ds_render_code_field().
 150     // - DS_FIELD_TYPE_BLOCK      : calls ds_render_block_field().
 151     // - DS_FIELD_TYPE_PREPROCESS : calls nothing, just takes a key from the
 152     //                              variable field that is passed on.
 153     // - DS_FIELD_TYPE_IGNORE     : calls nothing, use this if you simple want
 154     //                              to drag and drop. The field itself will have
 155     //                              a theme function.
 156     'field_type' => DS_FIELD_TYPE_FUNCTION,
 157
 158     // ui_limit : only used for the manage display screen so
 159     // you can limit fields to show based on bundles or view modes
 160     // the values are always in the form of $bundle|$view_mode
 161     // You may use * to select all.
 162     // Make sure you use the machine name.
 163     'ui_limit' => array('article|full', '*|search_index'),
 164
 165     // file: an optional file in which the function resides.
 166     // Only for DS_FIELD_TYPE_FUNCTION.
 167     'file' => 'optional_filename',
 168
 169     // function: only for DS_FIELD_TYPE_FUNCTION.
 170     'function' => 'theme_ds_title_field',
 171
 172     // properties: can have different keys.
 173     'properties' => array(
 174
 175       // formatters: optional if a function is used.
 176       // In case the field_type is DS_FIELD_TYPE_THEME, you also
 177       // need to register these formatters as a theming function
 178       // since the key will be called with theme('function').
 179       // The value is the caption used in the selection config on Field UI.
 180       'formatters' => array(
 181         'node_title_nolink_h1' => t('H1 title'),
 182         'node_title_link_h1' => t('H1 title, linked to node'),
 183       ),
 184
 185       // settings & default: optional if you have a settings form for your field.
 186       'settings' => array(
 187         'wrapper' => array('type' => 'textfield', 'description' => t('Eg: h1, h2, p')),
 188         'link' => array('type' => 'select', 'options' => array('yes', 'no')),
 189       ),
 190       'default' => array('wrapper' => 'h2', 'link' => 0),
 191
 192       // code: optional, only for code field.
 193       'code' => 'my code here',
 194
 195       // use_token: optional, only for code field.
 196       'use_token' => TRUE, // or FALSE,
 197
 198       // block: the module and delta of the block, only for block fields.
 199       'block' => 'user-menu',
 200
 201       // block_render: block render type, only for block fields.
 202       // - DS_BLOCK_CONTENT       : render through block template file.
 203       // - DS_BLOCK_TITLE_CONTENT : render only title and content.
 204       // - DS_BLOCK_CONTENT       : render only content.
 205       'block_render' => DS_BLOCK_CONTENT,
 206     )
 207   );
 208
 209   return array('node' => $fields);
 210
 211 }
 212
 213 /**
 214  * Define custom fields which can be overridden through the UI and which
 215  * are exportable. The keys are almost the same as in hook_ds_fields_info()
 216  * except that field_type is limited and you need an entities key.
 217  *
 218  * This hook is called by CTools. For this hook to work, you need
 219  * hook_ctools_plugin_api(). The values of this hook can be overridden
 220  * and reverted through the UI.
 221  */
 222 function hook_ds_custom_fields_info() {
 223   $ds_fields = array();
 224
 225   $ds_field = new stdClass;
 226   $ds_field->api_version = 1;
 227   $ds_field->field = 'custom_field';
 228   $ds_field->label = 'Custom field';
 229
 230   // Field type: either block or code
 231   // DS_FIELD_TYPE_CODE: 5
 232   // DS_FIELD_TYPE_BLOCK: 6
 233   $ds_field->field_type = 5;
 234
 235   // Collection of entities on which this custom field can work on.
 236   $ds_field->entities = array(
 237     'node' => 'node',
 238   );
 239   $ds_field->properties = array(
 240     'code' => array(
 241       'value' => '<? print "this is a custom field"; ?>',
 242       'format' => 'ds_code',
 243     ),
 244     'use_token' => 0,
 245   );
 246   $ds_fields['custom_field'] = $ds_field;
 247
 248   return $ds_fields;
 249 }
 250
 251 /**
 252  * Expose Views layouts definitions.
 253  *
 254  * This hook is called by CTools. For this hook to work, you need
 255  * hook_ctools_plugin_api(). The values of this hook can be overridden
 256  * and reverted through the UI.
 257  */
 258 function hook_ds_vd_info() {
 259   $ds_vds = array();
 260
 261   $ds_vd = new stdClass;
 262   $ds_vd->api_version = 1;
 263   $ds_vd->vd = 'frontpage-page';
 264   $ds_vd->label = 'Frontpage: Views displays';
 265   $ds_vds['frontpage-page'] = $ds_vd;
 266
 267   return $ds_vds;
 268 }
 269
 270 /**
 271  * Alter fields defined by Display Suite
 272  *
 273  * @param $fields
 274  *   An array with fields which can be altered just before they get cached.
 275  * @param $entity_type
 276  *   The name of the entity type.
 277  */
 278 function hook_ds_fields_info_alter(&$fields, $entity_type) {
 279   if (isset($fields['title'])) {
 280     $fields['title']['title'] = t('My title');
 281   }
 282 }
 283
 284 /**
 285  * Alter fields defined by Display Suite just before they get
 286  * rendered on the Field UI. Use this hook to inject fields
 287  * which you can't alter with hook_ds_fields_info_alter().
 288  *
 289  * Use this in edge cases, see ds_extras_ds_fields_ui_alter()
 290  * which adds fields chosen in Views UI. This also runs
 291  * when a layout has been chosen.
 292  *
 293  * @param $fields
 294  *   An array with fields which can be altered just before they get cached.
 295  * @param $entity_type
 296  *   The name of the entity type.
 297  */
 298 function hook_ds_fields_ui_alter(&$fields, $context) {
 299   $fields['title'] = t('Extra title');
 300 }
 301
 302 /**
 303  * Define theme functions for fields.
 304  *
 305  * This only is necessary when you're using the field settings
 306  * plugin which comes with the DS extras module and you want to
 307  * expose a special field theming function to the interface.
 308  *
 309  * The theme function gets $variables as the only parameter.
 310  * The optional configuration through the UI is in $variables['ds-config'].
 311  *
 312  * Note that 'theme_ds_field_' is always needed, so the suggestions can work.
 313  *
 314  * @return $field_theme_functions
 315  *   A collection of field theming functions.
 316  */
 317 function hook_ds_field_theme_functions_info() {
 318   return array('theme_ds_field_mine' => t('Theme field'));
 319 }
 320
 321 /**
 322  * Return configuration summary for the field format.
 323  *
 324  * As soon as you have hook_ds_fields and one of the fields
 325  * has a settings key, Display Suite will call this hook for the summary.
 326  *
 327  * @param $field
 328  *   The configuration of the field.
 329  *
 330  * @return $summary
 331  *   The summary to show on the Field UI.
 332  */
 333 function hook_ds_field_format_summary($field) {
 334   return 'Field summary';
 335 }
 336
 337 /**
 338  * Return a settings form for a Display Suite field.
 339  *
 340  * As soon as you have hook_ds_fields and one of the fields
 341  * has a settings key, Display Suite will call this hook for field form.
 342  *
 343  * @param $field
 344  *   The configuration of the field.
 345  *
 346  * @return $form
 347  *   A form definition.
 348  */
 349 function hook_ds_field_settings_form($field) {
 350
 351   // Saved formatter settings are on $field['formatter_settings'];
 352   $settings = isset($field['formatter_settings']) ? $field['formatter_settings'] : $field['properties']['default'];
 353
 354   $form['label'] = array(
 355     '#type' => 'textfield',
 356     '#title' => t('Label'),
 357     '#default_value' => $settings['label'],
 358   );
 359 }
 360
 361 /**
 362  * Modify the layout settings just before they get saved.
 363  *
 364  * @param $record
 365  *   The record just before it gets saved into the database.
 366  * @param $form_state
 367  *   The form_state values.
 368  */
 369 function hook_ds_layout_settings_alter($record, $form_state) {
 370   $record->settings['hide_page_title'] = TRUE;
 371 }
 372
 373 /**
 374  * Modify the field settings before they get saved.
 375  *
 376  * @param $field_settings
 377  *   A collection of field settings which keys are fields.
 378  * @param $form
 379  *   The current form which is submitted.
 380  * @param $form_state
 381  *   The form state with all its values.
 382  */
 383 function hook_ds_field_settings_alter(&$field_settings, $form, $form_state) {
 384   $field_settings['title']['region'] = 'left';
 385 }
 386
 387 /**
 388  * Define layouts from code.
 389  *
 390  * @return $layouts
 391  *   A collection of layouts.
 392  */
 393 function hook_ds_layout_info() {
 394   $path = drupal_get_path('module', 'foo');
 395
 396   $layouts = array(
 397     'foo_1col' => array(
 398       'label' => t('Foo one column'),
 399       'path' => $path . '/layouts/foo_1col',
 400       'regions' => array(
 401         'foo_content' => t('Content'),
 402       ),
 403       'css' => TRUE,
 404       // optional, form only applies to node form at this point.
 405       'form' => TRUE,
 406     ),
 407   );
 408
 409   return $layouts;
 410 }
 411
 412 /**
 413  * Alter layouts found by Display Suite.
 414  *
 415  * @param $layouts
 416  *   A array of layouts which keys are the layout and which values are
 417  *   properties of that layout (label, path, regions and css).
 418  */
 419 function hook_ds_layout_info_alter(&$layouts) {
 420   unset($layouts['ds_2col']);
 421 }
 422
 423 /**
 424  * Alter the region options in the field UI screen.
 425  *
 426  * This function is only called when a layout has been chosen.
 427  *
 428  * @param $context
 429  *   A collection of keys for the context. The keys are 'entity_type',
 430  *   'bundle' and 'view_mode'.
 431  * @param $region_info
 432  *   A collection of info for regions. The keys are 'region_options'
 433  *   and 'table_regions'.
 434  */
 435 function hook_ds_layout_region_alter($context, &$region_info) {
 436   $region_info['region_options'][$block_key] = $block['title'];
 437   $region_info['table_regions'][$block_key] = array(
 438     'title' => check_plain($block['title']),
 439     'message' => t('No fields are displayed in this region'),
 440   );
 441 }
 442
 443 /**
 444  * Alter the region layout before the regions are rendered.
 445  *
 446  * This hook is invoked in ds_entity_variables().
 447  *
 448  * @param $layout
 449  *   The region layout.
 450  * @param $entity
 451  *   The entity which is being processed for rendering.
 452  */
 453 function hook_ds_regions_alter(&$layout, $entity) {
 454   // Move the first element of the footer region into the header region on the
 455   // front page.
 456   if ($entity->type == 'blog' && drupal_is_front_page()) {
 457     $element = array_shift($layout['settings']['regions']['footer']);
 458     $layout['settings']['regions']['header'][] = $element;
 459   }
 460 }
 461
 462 /**
 463  * Alter the field label options. Note that you will either
 464  * update the preprocess functions or the field.tpl.php file when
 465  * adding new options.
 466  *
 467  * @param $field_label_options
 468  *   A collection of field label options.
 469  */
 470 function hook_ds_label_options_alter(&$field_label_options) {
 471   $field_label_options['label_after'] = t('Label after field');
 472 }
 473
 474 /**
 475  * Themes can also define extra layouts.
 476  *
 477  * Create a ds_layouts folder and then a folder name that will
 478  * be used as key for the layout. The folder should at least have 2 files:
 479  *
 480  * - key.inc
 481  * - key.tpl.php
 482  *
 483  * The css file is optional.
 484  * - key.css
 485  *
 486  * e.g.
 487  * bartik/ds_layouts/bartik_ds/bartik_ds.inc
 488  *                            /bartik-ds.tpl.php
 489  *                            /bartik_ds.css
 490  *
 491  * bartik_ds.inc must look like this:
 492  *
 493
 494   // Fuction name is ds_LAYOUT_KEY
 495   function ds_bartik_ds() {
 496     return array(
 497       'label' => t('Bartik DS'),
 498       'regions' => array(
 499         // The key of this region name is also the variable used in
 500         // the template to print the content of that region.
 501         'bartik' => t('Bartik DS'),
 502       ),
 503       // Add this if there is a default css file.
 504       'css' => TRUE,
 505       // Add this if this template is for a node form.
 506       'form' => TRUE,
 507     );
 508   }
 509
 510  */
 511
 512 /**
 513  * Return fields to be added when creating a new display with the panels editor.
 514  */
 515 function hook_ds_panels_default_fields($entity_type, $bundle, $view_mode) {
 516   // Get the fields from Field API.
 517   $fields = field_info_instances($entity_type, $bundle);
 518   return $fields;
 519 }
 520
 521 /**
 522  * Alter the view mode just before it's rendered by the DS views entity plugin.
 523  *
 524  * @param $view_mode
 525  *   The name of the view mode.
 526  * @param $context
 527  *   A collection of items which can be used to identify in what
 528  *   context an entity is being rendered. The variable contains 3 keys:
 529  *     - entity: The entity being rendered.
 530  *     - view_name: the name of the view.
 531  *     - display: the name of the display of the view.
 532  */
 533 function hook_ds_views_view_mode_alter(&$view_mode, $context) {
 534   if ($context['view_name'] == 'my_view_name') {
 535     $view_mode = 'new_view_mode';
 536   }
 537 }
 538
 539 /**
 540  * Theme an entity coming from the views entity plugin.
 541  *
 542  * @param $entity
 543  *   The complete entity.
 544  * @param $view_mode
 545  *   The name of the view mode.
 546  */
 547 function ds_views_row_ENTITY_NAME($entity, $view_mode) {
 548   $nid = $vars['row']->{$vars['field_alias']};
 549   $node = node_load($nid);
 550   $element = node_view($node, $view_mode);
 551   return drupal_render($element);
 552 }
 553
 554 /**
 555  * Theme an entity through an advanced function coming from the views entity plugin.
 556  *
 557  * @param $vars
 558  *   An array of variables from the views preprocess functions.
 559  * @param $view_mode
 560  *   The name of the view mode.
 561  */
 562 function ds_views_row_adv_VIEWS_NAME(&$vars, $view_mode) {
 563   // You can do whatever you want to here.
 564   $vars['object'] = 'This is what I want for christmas.';
 565 }
 566
 567 /**
 568  * @} End of "addtogroup hooks".
 569  */