fields.inc 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356
  1. <?php
  2. /**
  3. * @file
  4. * Extend core fields with some helper functions to reduce code complexity within views and ctools plugins.
  5. */
  6. /**
  7. * Fake an instance of a field.
  8. *
  9. * @param $field_name
  10. * The unique name for this field no matter what entity/bundle it may be used on.
  11. * @param $view_mode
  12. * We're building a new view mode for this function. Defaults to ctools, but we expect developers to actually name this something meaningful.
  13. * @param $formatter
  14. * The formatter key selected from the options provided by field_ui_formatter_options().
  15. * @param $formatter_settings
  16. * An array of key value pairs. These will be used as #default_value for the form elements generated by a call to hook_field_formatter_settings_form() for this field type.
  17. * Typically we'll pass an empty array to begin with and then pass this information back to ourselves on form submit so that we can set the values for later edit sessions.
  18. */
  19. function ctools_fields_fake_field_instance($field_name, $view_mode = 'ctools', $formatter, $formatter_settings) {
  20. $field = field_read_field($field_name);
  21. $field_type = field_info_field_types($field['type']);
  22. return array(
  23. // Build a fake entity type and bundle.
  24. 'field_name' => $field_name,
  25. 'entity_type' => 'ctools',
  26. 'bundle' => 'ctools',
  27. // Use the default field settings for settings and widget.
  28. 'settings' => field_info_instance_settings($field['type']),
  29. 'widget' => array(
  30. 'type' => $field_type['default_widget'],
  31. 'settings' => array(),
  32. ),
  33. // Build a dummy display mode.
  34. 'display' => array(
  35. $view_mode => array(
  36. 'type' => $formatter,
  37. 'settings' => $formatter_settings,
  38. ),
  39. ),
  40. // Set the other fields to their default values.
  41. // @see _field_write_instance().
  42. 'required' => FALSE,
  43. 'label' => $field_name,
  44. 'description' => '',
  45. 'deleted' => 0,
  46. );
  47. }
  48. /**
  49. * Helper function for calling hook_field_formatter_settings_form() without needing to load an instance of the field.
  50. *
  51. * @param $field
  52. * A fully loaded field.
  53. * @param $formatter_type
  54. * The formatter key selected from the options provided by field_ui_formatter_options().
  55. * @param $form
  56. * The full form from the function that's calling this function.
  57. * @param $form_state
  58. * The full form_state from the function that's calling this function.
  59. * @param $view_mode
  60. * We're passing a view mode from this function to the fake instance we're creating. Defaults to ctools, but we expect developers to actually name this something meaningful.
  61. */
  62. function ctools_fields_get_field_formatter_settings_form($field, $formatter_type, &$form, $form_state, $view_mode = 'ctools') {
  63. $conf = $form_state['conf'];
  64. $formatter = field_info_formatter_types($formatter_type);
  65. if (isset($formatter['settings'])) {
  66. $conf['formatter_settings'] += $formatter['settings'];
  67. }
  68. $function = $formatter['module'] . '_field_formatter_settings_form';
  69. if (function_exists($function)) {
  70. $instance = ctools_fields_fake_field_instance($field['field_name'], $view_mode, $formatter_type, $conf['formatter_settings']);
  71. $settings_form = $function($field, $instance, $view_mode, $form, $form_state);
  72. if ($settings_form) {
  73. // Allow other modules to alter the formatter settings form.
  74. $context = array(
  75. 'module' => $formatter['module'],
  76. 'formatter' => $formatter,
  77. 'field' => $field,
  78. 'instance' => $instance,
  79. 'view_mode' => $view_mode,
  80. 'form' => $form,
  81. 'form_state' => $form_state,
  82. );
  83. drupal_alter('field_formatter_settings_form', $settings_form, $context);
  84. $settings_form['#tree'] = TRUE;
  85. $form['ctools_field_list']['#value'][] = $field;
  86. $form += $settings_form;
  87. }
  88. }
  89. if (isset($field['cardinality']) && $field['cardinality'] != 1) {
  90. list($prefix, $suffix) = explode('@count', t('Skip the first @count item(s)'));
  91. $form['delta_offset'] = array(
  92. '#type' => 'textfield',
  93. '#size' => 5,
  94. '#field_prefix' => $prefix,
  95. '#field_suffix' => $suffix,
  96. '#default_value' => isset($conf['delta_offset']) ? $conf['delta_offset'] : 0,
  97. );
  98. list($prefix, $suffix) = explode('@count', t('Then display at most @count item(s)'));
  99. $form['delta_limit'] = array(
  100. '#type' => 'textfield',
  101. '#size' => 5,
  102. '#field_prefix' => $prefix,
  103. '#field_suffix' => $suffix,
  104. '#description' => t('Enter 0 to display all items.'),
  105. '#default_value' => isset($conf['delta_limit']) ? $conf['delta_limit'] : 0,
  106. );
  107. $form['delta_reversed'] = array(
  108. '#title' => t('Display in reverse order'),
  109. '#type' => 'checkbox',
  110. '#default_value' => !empty($conf['delta_reversed']),
  111. '#description' => t('(start from last values)'),
  112. );
  113. }
  114. }
  115. /**
  116. * Helper function for generating all the formatter information associated with
  117. * any fields.
  118. * Especially useful for determining the fields that will be added to form that
  119. * executes hook_field_formatter_settings_form().
  120. *
  121. * @param $fields
  122. * An array of fully loaded fields.
  123. */
  124. function ctools_fields_get_field_formatter_info($fields) {
  125. $info = array();
  126. $field_info = field_info_formatter_types();
  127. foreach ($fields as $field) {
  128. foreach ($field_info as $format_name => $formatter_info) {
  129. if (in_array($field['type'], $formatter_info['field types'])) {
  130. $info += array($format_name => $formatter_info);
  131. }
  132. }
  133. }
  134. return $info;
  135. }
  136. /**
  137. * Returns the label of a certain field.
  138. *
  139. * Cribbed from Views.
  140. */
  141. function ctools_field_label($field_name) {
  142. $label_counter = array();
  143. // Count the amount of instances per label per field.
  144. $instances = field_info_instances();
  145. foreach ($instances as $entity_type) {
  146. foreach ($entity_type as $bundle) {
  147. if (isset($bundle[$field_name])) {
  148. $label_counter[$bundle[$field_name]['label']] = isset($label_counter[$bundle[$field_name]['label']]) ? ++$label_counter[$bundle[$field_name]['label']] : 1;
  149. }
  150. }
  151. }
  152. if (empty($label_counter)) {
  153. return $field_name;
  154. }
  155. // Sort the field lables by it most used label and return the most used one.
  156. arsort($label_counter);
  157. $label_counter = array_keys($label_counter);
  158. return $label_counter[0];
  159. }
  160. /**
  161. * Replacement for core _field_invoke() to invoke on a single field.
  162. *
  163. * Core only allows invoking field hooks via a private function for all fields
  164. * on an entire entity. However, we very often need to invoke our hooks on
  165. * a single field as we take things apart and only use little bits.
  166. *
  167. * @param $field_name
  168. * Either a field instance object or the name of the field.
  169. * If the 'field' key is populated it will be used as the field
  170. * settings.
  171. * @param $op
  172. * Possible operations include:
  173. * - form
  174. * - validate
  175. * - presave
  176. * - insert
  177. * - update
  178. * - delete
  179. * - delete revision
  180. * - view
  181. * - prepare translation
  182. * @param $entity_type
  183. * The type of $entity; e.g. 'node' or 'user'.
  184. * @param $entity
  185. * The fully formed $entity_type entity.
  186. * @param $a
  187. * - The $form in the 'form' operation.
  188. * - The value of $view_mode in the 'view' operation.
  189. * - Otherwise NULL.
  190. * @param $b
  191. * - The $form_state in the 'submit' operation.
  192. * - Otherwise NULL.
  193. * @param $options
  194. * An associative array of additional options, with the following keys:
  195. * - 'field_name': The name of the field whose operation should be
  196. * invoked. By default, the operation is invoked on all the fields
  197. * in the entity's bundle. NOTE: This option is not compatible with
  198. * the 'deleted' option; the 'field_id' option should be used
  199. * instead.
  200. * - 'field_id': The id of the field whose operation should be
  201. * invoked. By default, the operation is invoked on all the fields
  202. * in the entity's' bundles.
  203. * - 'default': A boolean value, specifying which implementation of
  204. * the operation should be invoked.
  205. * - if FALSE (default), the field types implementation of the operation
  206. * will be invoked (hook_field_[op])
  207. * - If TRUE, the default field implementation of the field operation
  208. * will be invoked (field_default_[op])
  209. * Internal use only. Do not explicitely set to TRUE, but use
  210. * _field_invoke_default() instead.
  211. * - 'deleted': If TRUE, the function will operate on deleted fields
  212. * as well as non-deleted fields. If unset or FALSE, only
  213. * non-deleted fields are operated on.
  214. * - 'language': A language code or an array of language codes keyed by field
  215. * name. It will be used to narrow down to a single value the available
  216. * languages to act on.
  217. *
  218. * @see _field_invoke()
  219. */
  220. function ctools_field_invoke_field($field_name, $op, $entity_type, $entity, &$a = NULL, &$b = NULL, $options = array()) {
  221. if (is_array($field_name)) {
  222. $instance = $field_name;
  223. $field = empty($field_name['field']) ? field_info_field($instance['field_name']) : $field_name['field'];
  224. $field_name = $instance['field_name'];
  225. }
  226. else {
  227. list(, , $bundle) = entity_extract_ids($entity_type, $entity);
  228. $instance = field_info_instance($entity_type, $field_name, $bundle);
  229. }
  230. if (empty($instance)) {
  231. return;
  232. }
  233. // Merge default options.
  234. $default_options = array(
  235. 'default' => FALSE,
  236. 'deleted' => FALSE,
  237. 'language' => NULL,
  238. );
  239. $options += $default_options;
  240. $return = array();
  241. // Everything from here is unmodified code from _field_invoke() formerly
  242. // inside a foreach loop over the instances.
  243. $function = $options['default'] ? 'field_default_' . $op : $field['module'] . '_field_' . $op;
  244. if (function_exists($function)) {
  245. // Determine the list of languages to iterate on.
  246. $available_languages = field_available_languages($entity_type, $field);
  247. $languages = _field_language_suggestion($available_languages, $options['language'], $field_name);
  248. foreach ($languages as $langcode) {
  249. $items = isset($entity->{$field_name}[$langcode]) ? $entity->{$field_name}[$langcode] : array();
  250. $result = $function($entity_type, $entity, $field, $instance, $langcode, $items, $a, $b);
  251. if (isset($result)) {
  252. // For hooks with array results, we merge results together.
  253. // For hooks with scalar results, we collect results in an array.
  254. if (is_array($result)) {
  255. $return = array_merge($return, $result);
  256. }
  257. else {
  258. $return[] = $result;
  259. }
  260. }
  261. // Populate $items back in the field values, but avoid replacing missing
  262. // fields with an empty array (those are not equivalent on update).
  263. if ($items !== array() || isset($entity->{$field_name}[$langcode])) {
  264. $entity->{$field_name}[$langcode] = $items;
  265. }
  266. }
  267. }
  268. return $return;
  269. }
  270. /**
  271. * Replacement for core _field_invoke_default() to invoke on a single field.
  272. *
  273. * @see ctools_field_invoke_field()
  274. * @see _field_invoke_default()
  275. */
  276. function ctools_field_invoke_field_default($field_name, $op, $entity_type, $entity, &$a = NULL, &$b = NULL, $options = array()) {
  277. $options['default'] = TRUE;
  278. return ctools_field_invoke_field($field_name, $op, $entity_type, $entity, $a, $b, $options);
  279. }
  280. /**
  281. * Returns a list of field definitions of a specified type.
  282. *
  283. * @param string $field_type
  284. * A field type name; e.g. 'text' or 'date'.
  285. *
  286. * @return array
  287. * An array of field definitions of the specified type, keyed by field name.
  288. */
  289. function ctools_fields_get_fields_by_type($field_type) {
  290. $fields = array();
  291. foreach (field_info_fields() as $field_name => $field_info) {
  292. if ($field_info['type'] == $field_type) {
  293. $fields[$field_name] = $field_info;
  294. }
  295. }
  296. return $fields;
  297. }
  298. /**
  299. * Derive the foreign keys that a field provides.
  300. *
  301. * @param $field_name
  302. * The name of the field.
  303. *
  304. * @return
  305. * An array of foreign keys according to Schema API.
  306. */
  307. function ctools_field_foreign_keys($field_name) {
  308. $foreign_keys = &drupal_static(__FUNCTION__, array());
  309. if (!isset($foreign_keys[$field_name])) {
  310. $foreign_keys[$field_name] = array();
  311. $field = field_info_field($field_name);
  312. if (!empty($field['foreign keys'])) {
  313. $foreign_keys[$field_name] = $field['foreign keys'];
  314. }
  315. else {
  316. // try to fetch foreign keys from schema, as not everything
  317. // stores foreign keys properly in the field info.
  318. $module = $field['module'];
  319. module_load_install($module);
  320. $schema = module_invoke($module, 'field_schema', $field);
  321. if (!empty($schema['foreign keys'])) {
  322. $foreign_keys[$field_name] = $schema['foreign keys'];
  323. }
  324. }
  325. }
  326. return $foreign_keys[$field_name];
  327. }