Issue #2072019 by a.milkovsky: Fixed Warning: htmlspecialchars() expects parameter...
[project/ds.git] / 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 */