field.api.php 95 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686
  1. <?php
  2. /**
  3. * @addtogroup hooks
  4. * @{
  5. */
  6. /**
  7. * Exposes "pseudo-field" components on fieldable entities.
  8. *
  9. * Field UI's "Manage fields" and "Manage display" pages let users re-order
  10. * fields, but also non-field components. For nodes, these include the title,
  11. * poll choices, and other elements exposed by modules through hook_form() or
  12. * hook_form_alter().
  13. *
  14. * Fieldable entities or modules that want to have their components supported
  15. * should expose them using this hook. The user-defined settings (weight,
  16. * visible) are automatically applied on rendered forms and displayed
  17. * entities in a #pre_render callback added by field_attach_form() and
  18. * field_attach_view().
  19. *
  20. * @see _field_extra_fields_pre_render()
  21. * @see hook_field_extra_fields_alter()
  22. *
  23. * @return
  24. * A nested array of 'pseudo-field' components. Each list is nested within
  25. * the following keys: entity type, bundle name, context (either 'form' or
  26. * 'display'). The keys are the name of the elements as appearing in the
  27. * renderable array (either the entity form or the displayed entity). The
  28. * value is an associative array:
  29. * - label: The human readable name of the component.
  30. * - description: A short description of the component contents.
  31. * - weight: The default weight of the element.
  32. */
  33. function hook_field_extra_fields() {
  34. $extra['node']['poll'] = array(
  35. 'form' => array(
  36. 'choice_wrapper' => array(
  37. 'label' => t('Poll choices'),
  38. 'description' => t('Poll choices'),
  39. 'weight' => -4,
  40. ),
  41. 'settings' => array(
  42. 'label' => t('Poll settings'),
  43. 'description' => t('Poll module settings'),
  44. 'weight' => -3,
  45. ),
  46. ),
  47. 'display' => array(
  48. 'poll_view_voting' => array(
  49. 'label' => t('Poll vote'),
  50. 'description' => t('Poll vote'),
  51. 'weight' => 0,
  52. ),
  53. 'poll_view_results' => array(
  54. 'label' => t('Poll results'),
  55. 'description' => t('Poll results'),
  56. 'weight' => 0,
  57. ),
  58. )
  59. );
  60. return $extra;
  61. }
  62. /**
  63. * Alter "pseudo-field" components on fieldable entities.
  64. *
  65. * @param $info
  66. * The associative array of 'pseudo-field' components.
  67. *
  68. * @see hook_field_extra_fields()
  69. */
  70. function hook_field_extra_fields_alter(&$info) {
  71. // Force node title to always be at the top of the list by default.
  72. foreach (node_type_get_types() as $bundle) {
  73. if (isset($info['node'][$bundle->type]['form']['title'])) {
  74. $info['node'][$bundle->type]['form']['title']['weight'] = -20;
  75. }
  76. }
  77. }
  78. /**
  79. * @defgroup field_types Field Types API
  80. * @{
  81. * Define field types.
  82. *
  83. * In the Field API, each field has a type, which determines what kind of data
  84. * (integer, string, date, etc.) the field can hold, which settings it provides,
  85. * and so on. The data type(s) accepted by a field are defined in
  86. * hook_field_schema(); other basic properties of a field are defined in
  87. * hook_field_info(). The other hooks below are called by the Field Attach API
  88. * to perform field-type-specific actions.
  89. *
  90. * The Field Types API also defines two kinds of pluggable handlers: widgets
  91. * and formatters. @link field_widget Widgets @endlink specify how the field
  92. * appears in edit forms, while @link field_formatter formatters @endlink
  93. * specify how the field appears in displayed entities.
  94. *
  95. * A third kind of pluggable handlers, storage backends, is defined by the
  96. * @link field_storage Field Storage API @endlink.
  97. *
  98. * See @link field Field API @endlink for information about the other parts of
  99. * the Field API.
  100. */
  101. /**
  102. * Define Field API field types.
  103. *
  104. * @return
  105. * An array whose keys are field type names and whose values are arrays
  106. * describing the field type, with the following key/value pairs:
  107. * - label: The human-readable name of the field type.
  108. * - description: A short description for the field type.
  109. * - settings: An array whose keys are the names of the settings available
  110. * for the field type, and whose values are the default values for those
  111. * settings.
  112. * - instance_settings: An array whose keys are the names of the settings
  113. * available for instances of the field type, and whose values are the
  114. * default values for those settings. Instance-level settings can have
  115. * different values on each field instance, and thus allow greater
  116. * flexibility than field-level settings. It is recommended to put settings
  117. * at the instance level whenever possible. Notable exceptions: settings
  118. * acting on the schema definition, or settings that Views needs to use
  119. * across field instances (for example, the list of allowed values).
  120. * - default_widget: The machine name of the default widget to be used by
  121. * instances of this field type, when no widget is specified in the
  122. * instance definition. This widget must be available whenever the field
  123. * type is available (i.e. provided by the field type module, or by a module
  124. * the field type module depends on).
  125. * - default_formatter: The machine name of the default formatter to be used
  126. * by instances of this field type, when no formatter is specified in the
  127. * instance definition. This formatter must be available whenever the field
  128. * type is available (i.e. provided by the field type module, or by a module
  129. * the field type module depends on).
  130. * - no_ui: (optional) A boolean specifying that users should not be allowed
  131. * to create fields and instances of this field type through the UI. Such
  132. * fields can only be created programmatically with field_create_field()
  133. * and field_create_instance(). Defaults to FALSE.
  134. *
  135. * @see hook_field_info_alter()
  136. */
  137. function hook_field_info() {
  138. return array(
  139. 'text' => array(
  140. 'label' => t('Text'),
  141. 'description' => t('This field stores varchar text in the database.'),
  142. 'settings' => array('max_length' => 255),
  143. 'instance_settings' => array('text_processing' => 0),
  144. 'default_widget' => 'text_textfield',
  145. 'default_formatter' => 'text_default',
  146. ),
  147. 'text_long' => array(
  148. 'label' => t('Long text'),
  149. 'description' => t('This field stores long text in the database.'),
  150. 'settings' => array('max_length' => ''),
  151. 'instance_settings' => array('text_processing' => 0),
  152. 'default_widget' => 'text_textarea',
  153. 'default_formatter' => 'text_default',
  154. ),
  155. 'text_with_summary' => array(
  156. 'label' => t('Long text and summary'),
  157. 'description' => t('This field stores long text in the database along with optional summary text.'),
  158. 'settings' => array('max_length' => ''),
  159. 'instance_settings' => array('text_processing' => 1, 'display_summary' => 0),
  160. 'default_widget' => 'text_textarea_with_summary',
  161. 'default_formatter' => 'text_summary_or_trimmed',
  162. ),
  163. );
  164. }
  165. /**
  166. * Perform alterations on Field API field types.
  167. *
  168. * @param $info
  169. * Array of information on field types exposed by hook_field_info()
  170. * implementations.
  171. */
  172. function hook_field_info_alter(&$info) {
  173. // Add a setting to all field types.
  174. foreach ($info as $field_type => $field_type_info) {
  175. $info[$field_type]['settings'] += array(
  176. 'mymodule_additional_setting' => 'default value',
  177. );
  178. }
  179. // Change the default widget for fields of type 'foo'.
  180. if (isset($info['foo'])) {
  181. $info['foo']['default widget'] = 'mymodule_widget';
  182. }
  183. }
  184. /**
  185. * Define the Field API schema for a field structure.
  186. *
  187. * This hook MUST be defined in .install for it to be detected during
  188. * installation and upgrade.
  189. *
  190. * @param $field
  191. * A field structure.
  192. *
  193. * @return
  194. * An associative array with the following keys:
  195. * - columns: An array of Schema API column specifications, keyed by column
  196. * name. This specifies what comprises a value for a given field. For
  197. * example, a value for a number field is simply 'value', while a value for
  198. * a formatted text field is the combination of 'value' and 'format'. It is
  199. * recommended to avoid having the column definitions depend on field
  200. * settings when possible. No assumptions should be made on how storage
  201. * engines internally use the original column name to structure their
  202. * storage.
  203. * - indexes: (optional) An array of Schema API indexes definitions. Only
  204. * columns that appear in the 'columns' array are allowed. Those indexes
  205. * will be used as default indexes. Callers of field_create_field() can
  206. * specify additional indexes, or, at their own risk, modify the default
  207. * indexes specified by the field-type module. Some storage engines might
  208. * not support indexes.
  209. * - foreign keys: (optional) An array of Schema API foreign keys
  210. * definitions.
  211. */
  212. function hook_field_schema($field) {
  213. if ($field['type'] == 'text_long') {
  214. $columns = array(
  215. 'value' => array(
  216. 'type' => 'text',
  217. 'size' => 'big',
  218. 'not null' => FALSE,
  219. ),
  220. );
  221. }
  222. else {
  223. $columns = array(
  224. 'value' => array(
  225. 'type' => 'varchar',
  226. 'length' => $field['settings']['max_length'],
  227. 'not null' => FALSE,
  228. ),
  229. );
  230. }
  231. $columns += array(
  232. 'format' => array(
  233. 'type' => 'varchar',
  234. 'length' => 255,
  235. 'not null' => FALSE,
  236. ),
  237. );
  238. return array(
  239. 'columns' => $columns,
  240. 'indexes' => array(
  241. 'format' => array('format'),
  242. ),
  243. 'foreign keys' => array(
  244. 'format' => array(
  245. 'table' => 'filter_format',
  246. 'columns' => array('format' => 'format'),
  247. ),
  248. ),
  249. );
  250. }
  251. /**
  252. * Define custom load behavior for this module's field types.
  253. *
  254. * Unlike most other field hooks, this hook operates on multiple entities. The
  255. * $entities, $instances and $items parameters are arrays keyed by entity ID.
  256. * For performance reasons, information for all available entity should be
  257. * loaded in a single query where possible.
  258. *
  259. * Note that the changes made to the field values get cached by the field cache
  260. * for subsequent loads. You should never use this hook to load fieldable
  261. * entities, since this is likely to cause infinite recursions when
  262. * hook_field_load() is run on those as well. Use
  263. * hook_field_formatter_prepare_view() instead.
  264. *
  265. * Make changes or additions to field values by altering the $items parameter by
  266. * reference. There is no return value.
  267. *
  268. * @param $entity_type
  269. * The type of $entity.
  270. * @param $entities
  271. * Array of entities being loaded, keyed by entity ID.
  272. * @param $field
  273. * The field structure for the operation.
  274. * @param $instances
  275. * Array of instance structures for $field for each entity, keyed by entity
  276. * ID.
  277. * @param $langcode
  278. * The language code associated with $items.
  279. * @param $items
  280. * Array of field values already loaded for the entities, keyed by entity ID.
  281. * Store your changes in this parameter (passed by reference).
  282. * @param $age
  283. * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
  284. * FIELD_LOAD_REVISION to load the version indicated by each entity.
  285. */
  286. function hook_field_load($entity_type, $entities, $field, $instances, $langcode, &$items, $age) {
  287. // Sample code from text.module: precompute sanitized strings so they are
  288. // stored in the field cache.
  289. foreach ($entities as $id => $entity) {
  290. foreach ($items[$id] as $delta => $item) {
  291. // Only process items with a cacheable format, the rest will be handled
  292. // by formatters if needed.
  293. if (empty($instances[$id]['settings']['text_processing']) || filter_format_allowcache($item['format'])) {
  294. $items[$id][$delta]['safe_value'] = isset($item['value']) ? _text_sanitize($instances[$id], $langcode, $item, 'value') : '';
  295. if ($field['type'] == 'text_with_summary') {
  296. $items[$id][$delta]['safe_summary'] = isset($item['summary']) ? _text_sanitize($instances[$id], $langcode, $item, 'summary') : '';
  297. }
  298. }
  299. }
  300. }
  301. }
  302. /**
  303. * Prepare field values prior to display.
  304. *
  305. * This hook is invoked before the field values are handed to formatters
  306. * for display, and runs before the formatters' own
  307. * hook_field_formatter_prepare_view().
  308. *
  309. * Unlike most other field hooks, this hook operates on multiple entities. The
  310. * $entities, $instances and $items parameters are arrays keyed by entity ID.
  311. * For performance reasons, information for all available entities should be
  312. * loaded in a single query where possible.
  313. *
  314. * Make changes or additions to field values by altering the $items parameter by
  315. * reference. There is no return value.
  316. *
  317. * @param $entity_type
  318. * The type of $entity.
  319. * @param $entities
  320. * Array of entities being displayed, keyed by entity ID.
  321. * @param $field
  322. * The field structure for the operation.
  323. * @param $instances
  324. * Array of instance structures for $field for each entity, keyed by entity
  325. * ID.
  326. * @param $langcode
  327. * The language associated to $items.
  328. * @param $items
  329. * $entity->{$field['field_name']}, or an empty array if unset.
  330. */
  331. function hook_field_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items) {
  332. // Sample code from image.module: if there are no images specified at all,
  333. // use the default image.
  334. foreach ($entities as $id => $entity) {
  335. if (empty($items[$id]) && $field['settings']['default_image']) {
  336. if ($file = file_load($field['settings']['default_image'])) {
  337. $items[$id][0] = (array) $file + array(
  338. 'is_default' => TRUE,
  339. 'alt' => '',
  340. 'title' => '',
  341. );
  342. }
  343. }
  344. }
  345. }
  346. /**
  347. * Validate this module's field data.
  348. *
  349. * If there are validation problems, add to the $errors array (passed by
  350. * reference). There is no return value.
  351. *
  352. * @param $entity_type
  353. * The type of $entity.
  354. * @param $entity
  355. * The entity for the operation.
  356. * @param $field
  357. * The field structure for the operation.
  358. * @param $instance
  359. * The instance structure for $field on $entity's bundle.
  360. * @param $langcode
  361. * The language associated with $items.
  362. * @param $items
  363. * $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  364. * @param $errors
  365. * The array of errors (keyed by field name, language code, and delta) that
  366. * have already been reported for the entity. The function should add its
  367. * errors to this array. Each error is an associative array with the following
  368. * keys and values:
  369. * - error: An error code (should be a string prefixed with the module name).
  370. * - message: The human readable message to be displayed.
  371. */
  372. function hook_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
  373. foreach ($items as $delta => $item) {
  374. if (!empty($item['value'])) {
  375. if (!empty($field['settings']['max_length']) && drupal_strlen($item['value']) > $field['settings']['max_length']) {
  376. $errors[$field['field_name']][$langcode][$delta][] = array(
  377. 'error' => 'text_max_length',
  378. 'message' => t('%name: the value may not be longer than %max characters.', array('%name' => $instance['label'], '%max' => $field['settings']['max_length'])),
  379. );
  380. }
  381. }
  382. }
  383. }
  384. /**
  385. * Define custom presave behavior for this module's field types.
  386. *
  387. * Make changes or additions to field values by altering the $items parameter by
  388. * reference. There is no return value.
  389. *
  390. * @param $entity_type
  391. * The type of $entity.
  392. * @param $entity
  393. * The entity for the operation.
  394. * @param $field
  395. * The field structure for the operation.
  396. * @param $instance
  397. * The instance structure for $field on $entity's bundle.
  398. * @param $langcode
  399. * The language associated with $items.
  400. * @param $items
  401. * $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  402. */
  403. function hook_field_presave($entity_type, $entity, $field, $instance, $langcode, &$items) {
  404. if ($field['type'] == 'number_decimal') {
  405. // Let PHP round the value to ensure consistent behavior across storage
  406. // backends.
  407. foreach ($items as $delta => $item) {
  408. if (isset($item['value'])) {
  409. $items[$delta]['value'] = round($item['value'], $field['settings']['scale']);
  410. }
  411. }
  412. }
  413. }
  414. /**
  415. * Define custom insert behavior for this module's field data.
  416. *
  417. * This hook is invoked from field_attach_insert() on the module that defines a
  418. * field, during the process of inserting an entity object (node, taxonomy term,
  419. * etc.). It is invoked just before the data for this field on the particular
  420. * entity object is inserted into field storage. Only field modules that are
  421. * storing or tracking information outside the standard field storage mechanism
  422. * need to implement this hook.
  423. *
  424. * @param $entity_type
  425. * The type of $entity.
  426. * @param $entity
  427. * The entity for the operation.
  428. * @param $field
  429. * The field structure for the operation.
  430. * @param $instance
  431. * The instance structure for $field on $entity's bundle.
  432. * @param $langcode
  433. * The language associated with $items.
  434. * @param $items
  435. * $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  436. *
  437. * @see hook_field_update()
  438. * @see hook_field_delete()
  439. */
  440. function hook_field_insert($entity_type, $entity, $field, $instance, $langcode, &$items) {
  441. if (variable_get('taxonomy_maintain_index_table', TRUE) && $field['storage']['type'] == 'field_sql_storage' && $entity_type == 'node' && $entity->status) {
  442. $query = db_insert('taxonomy_index')->fields(array('nid', 'tid', 'sticky', 'created', ));
  443. foreach ($items as $item) {
  444. $query->values(array(
  445. 'nid' => $entity->nid,
  446. 'tid' => $item['tid'],
  447. 'sticky' => $entity->sticky,
  448. 'created' => $entity->created,
  449. ));
  450. }
  451. $query->execute();
  452. }
  453. }
  454. /**
  455. * Define custom update behavior for this module's field data.
  456. *
  457. * This hook is invoked from field_attach_update() on the module that defines a
  458. * field, during the process of updating an entity object (node, taxonomy term,
  459. * etc.). It is invoked just before the data for this field on the particular
  460. * entity object is updated into field storage. Only field modules that are
  461. * storing or tracking information outside the standard field storage mechanism
  462. * need to implement this hook.
  463. *
  464. * @param $entity_type
  465. * The type of $entity.
  466. * @param $entity
  467. * The entity for the operation.
  468. * @param $field
  469. * The field structure for the operation.
  470. * @param $instance
  471. * The instance structure for $field on $entity's bundle.
  472. * @param $langcode
  473. * The language associated with $items.
  474. * @param $items
  475. * $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  476. *
  477. * @see hook_field_insert()
  478. * @see hook_field_delete()
  479. */
  480. function hook_field_update($entity_type, $entity, $field, $instance, $langcode, &$items) {
  481. if (variable_get('taxonomy_maintain_index_table', TRUE) && $field['storage']['type'] == 'field_sql_storage' && $entity_type == 'node') {
  482. $first_call = &drupal_static(__FUNCTION__, array());
  483. // We don't maintain data for old revisions, so clear all previous values
  484. // from the table. Since this hook runs once per field, per object, make
  485. // sure we only wipe values once.
  486. if (!isset($first_call[$entity->nid])) {
  487. $first_call[$entity->nid] = FALSE;
  488. db_delete('taxonomy_index')->condition('nid', $entity->nid)->execute();
  489. }
  490. // Only save data to the table if the node is published.
  491. if ($entity->status) {
  492. $query = db_insert('taxonomy_index')->fields(array('nid', 'tid', 'sticky', 'created'));
  493. foreach ($items as $item) {
  494. $query->values(array(
  495. 'nid' => $entity->nid,
  496. 'tid' => $item['tid'],
  497. 'sticky' => $entity->sticky,
  498. 'created' => $entity->created,
  499. ));
  500. }
  501. $query->execute();
  502. }
  503. }
  504. }
  505. /**
  506. * Update the storage information for a field.
  507. *
  508. * This is invoked on the field's storage module from field_update_field(),
  509. * before the new field information is saved to the database. The field storage
  510. * module should update its storage tables to agree with the new field
  511. * information. If there is a problem, the field storage module should throw an
  512. * exception.
  513. *
  514. * @param $field
  515. * The updated field structure to be saved.
  516. * @param $prior_field
  517. * The previously-saved field structure.
  518. * @param $has_data
  519. * TRUE if the field has data in storage currently.
  520. */
  521. function hook_field_storage_update_field($field, $prior_field, $has_data) {
  522. if (!$has_data) {
  523. // There is no data. Re-create the tables completely.
  524. $prior_schema = _field_sql_storage_schema($prior_field);
  525. foreach ($prior_schema as $name => $table) {
  526. db_drop_table($name, $table);
  527. }
  528. $schema = _field_sql_storage_schema($field);
  529. foreach ($schema as $name => $table) {
  530. db_create_table($name, $table);
  531. }
  532. }
  533. else {
  534. // There is data. See field_sql_storage_field_storage_update_field() for
  535. // an example of what to do to modify the schema in place, preserving the
  536. // old data as much as possible.
  537. }
  538. drupal_get_schema(NULL, TRUE);
  539. }
  540. /**
  541. * Define custom delete behavior for this module's field data.
  542. *
  543. * This hook is invoked from field_attach_delete() on the module that defines a
  544. * field, during the process of deleting an entity object (node, taxonomy term,
  545. * etc.). It is invoked just before the data for this field on the particular
  546. * entity object is deleted from field storage. Only field modules that are
  547. * storing or tracking information outside the standard field storage mechanism
  548. * need to implement this hook.
  549. *
  550. * @param $entity_type
  551. * The type of $entity.
  552. * @param $entity
  553. * The entity for the operation.
  554. * @param $field
  555. * The field structure for the operation.
  556. * @param $instance
  557. * The instance structure for $field on $entity's bundle.
  558. * @param $langcode
  559. * The language associated with $items.
  560. * @param $items
  561. * $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  562. *
  563. * @see hook_field_insert()
  564. * @see hook_field_update()
  565. */
  566. function hook_field_delete($entity_type, $entity, $field, $instance, $langcode, &$items) {
  567. list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
  568. foreach ($items as $delta => $item) {
  569. // For hook_file_references(), remember that this is being deleted.
  570. $item['file_field_name'] = $field['field_name'];
  571. // Pass in the ID of the object that is being removed so all references can
  572. // be counted in hook_file_references().
  573. $item['file_field_type'] = $entity_type;
  574. $item['file_field_id'] = $id;
  575. file_field_delete_file($item, $field, $entity_type, $id);
  576. }
  577. }
  578. /**
  579. * Define custom revision delete behavior for this module's field types.
  580. *
  581. * This hook is invoked just before the data is deleted from field storage
  582. * in field_attach_delete_revision(), and will only be called for fieldable
  583. * types that are versioned.
  584. *
  585. * @param $entity_type
  586. * The type of $entity.
  587. * @param $entity
  588. * The entity for the operation.
  589. * @param $field
  590. * The field structure for the operation.
  591. * @param $instance
  592. * The instance structure for $field on $entity's bundle.
  593. * @param $langcode
  594. * The language associated with $items.
  595. * @param $items
  596. * $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  597. */
  598. function hook_field_delete_revision($entity_type, $entity, $field, $instance, $langcode, &$items) {
  599. list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
  600. foreach ($items as $delta => $item) {
  601. // For hook_file_references, remember that this file is being deleted.
  602. $item['file_field_name'] = $field['field_name'];
  603. if (file_field_delete_file($item, $field, $entity_type, $id)) {
  604. $items[$delta] = NULL;
  605. }
  606. }
  607. }
  608. /**
  609. * Define custom prepare_translation behavior for this module's field types.
  610. *
  611. * @param $entity_type
  612. * The type of $entity.
  613. * @param $entity
  614. * The entity for the operation.
  615. * @param $field
  616. * The field structure for the operation.
  617. * @param $instance
  618. * The instance structure for $field on $entity's bundle.
  619. * @param $langcode
  620. * The language associated to $items.
  621. * @param $items
  622. * $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  623. * @param $source_entity
  624. * The source entity from which field values are being copied.
  625. * @param $source_langcode
  626. * The source language from which field values are being copied.
  627. */
  628. function hook_field_prepare_translation($entity_type, $entity, $field, $instance, $langcode, &$items, $source_entity, $source_langcode) {
  629. // If the translating user is not permitted to use the assigned text format,
  630. // we must not expose the source values.
  631. $field_name = $field['field_name'];
  632. $formats = filter_formats();
  633. $format_id = $source_entity->{$field_name}[$source_langcode][0]['format'];
  634. if (!filter_access($formats[$format_id])) {
  635. $items = array();
  636. }
  637. }
  638. /**
  639. * Define what constitutes an empty item for a field type.
  640. *
  641. * @param $item
  642. * An item that may or may not be empty.
  643. * @param $field
  644. * The field to which $item belongs.
  645. *
  646. * @return
  647. * TRUE if $field's type considers $item not to contain any data;
  648. * FALSE otherwise.
  649. */
  650. function hook_field_is_empty($item, $field) {
  651. if (empty($item['value']) && (string) $item['value'] !== '0') {
  652. return TRUE;
  653. }
  654. return FALSE;
  655. }
  656. /**
  657. * @} End of "defgroup field_types".
  658. */
  659. /**
  660. * @defgroup field_widget Field Widget API
  661. * @{
  662. * Define Field API widget types.
  663. *
  664. * Field API widgets specify how fields are displayed in edit forms. Fields of a
  665. * given @link field_types field type @endlink may be edited using more than one
  666. * widget. In this case, the Field UI module allows the site builder to choose
  667. * which widget to use. Widget types are defined by implementing
  668. * hook_field_widget_info().
  669. *
  670. * Widgets are @link forms_api_reference.html Form API @endlink elements with
  671. * additional processing capabilities. Widget hooks are typically called by the
  672. * Field Attach API during the creation of the field form structure with
  673. * field_attach_form().
  674. *
  675. * @see field
  676. * @see field_types
  677. * @see field_formatter
  678. */
  679. /**
  680. * Expose Field API widget types.
  681. *
  682. * @return
  683. * An array describing the widget types implemented by the module.
  684. * The keys are widget type names. To avoid name clashes, widget type
  685. * names should be prefixed with the name of the module that exposes them.
  686. * The values are arrays describing the widget type, with the following
  687. * key/value pairs:
  688. * - label: The human-readable name of the widget type.
  689. * - description: A short description for the widget type.
  690. * - field types: An array of field types the widget supports.
  691. * - settings: An array whose keys are the names of the settings available
  692. * for the widget type, and whose values are the default values for those
  693. * settings.
  694. * - behaviors: (optional) An array describing behaviors of the widget, with
  695. * the following elements:
  696. * - multiple values: One of the following constants:
  697. * - FIELD_BEHAVIOR_DEFAULT: (default) If the widget allows the input of
  698. * one single field value (most common case). The widget will be
  699. * repeated for each value input.
  700. * - FIELD_BEHAVIOR_CUSTOM: If one single copy of the widget can receive
  701. * several field values. Examples: checkboxes, multiple select,
  702. * comma-separated textfield.
  703. * - default value: One of the following constants:
  704. * - FIELD_BEHAVIOR_DEFAULT: (default) If the widget accepts default
  705. * values.
  706. * - FIELD_BEHAVIOR_NONE: if the widget does not support default values.
  707. * - weight: (optional) An integer to determine the weight of this widget
  708. * relative to other widgets in the Field UI when selecting a widget for a
  709. * given field instance.
  710. *
  711. * @see hook_field_widget_info_alter()
  712. * @see hook_field_widget_form()
  713. * @see hook_field_widget_form_alter()
  714. * @see hook_field_widget_WIDGET_TYPE_form_alter()
  715. * @see hook_field_widget_error()
  716. * @see hook_field_widget_settings_form()
  717. */
  718. function hook_field_widget_info() {
  719. return array(
  720. 'text_textfield' => array(
  721. 'label' => t('Text field'),
  722. 'field types' => array('text'),
  723. 'settings' => array('size' => 60),
  724. 'behaviors' => array(
  725. 'multiple values' => FIELD_BEHAVIOR_DEFAULT,
  726. 'default value' => FIELD_BEHAVIOR_DEFAULT,
  727. ),
  728. ),
  729. 'text_textarea' => array(
  730. 'label' => t('Text area (multiple rows)'),
  731. 'field types' => array('text_long'),
  732. 'settings' => array('rows' => 5),
  733. 'behaviors' => array(
  734. 'multiple values' => FIELD_BEHAVIOR_DEFAULT,
  735. 'default value' => FIELD_BEHAVIOR_DEFAULT,
  736. ),
  737. ),
  738. 'text_textarea_with_summary' => array(
  739. 'label' => t('Text area with a summary'),
  740. 'field types' => array('text_with_summary'),
  741. 'settings' => array('rows' => 20, 'summary_rows' => 5),
  742. 'behaviors' => array(
  743. 'multiple values' => FIELD_BEHAVIOR_DEFAULT,
  744. 'default value' => FIELD_BEHAVIOR_DEFAULT,
  745. ),
  746. // As an advanced widget, force it to sink to the bottom of the choices.
  747. 'weight' => 2,
  748. ),
  749. );
  750. }
  751. /**
  752. * Perform alterations on Field API widget types.
  753. *
  754. * @param $info
  755. * Array of informations on widget types exposed by hook_field_widget_info()
  756. * implementations.
  757. */
  758. function hook_field_widget_info_alter(&$info) {
  759. // Add a setting to a widget type.
  760. $info['text_textfield']['settings'] += array(
  761. 'mymodule_additional_setting' => 'default value',
  762. );
  763. // Let a new field type re-use an existing widget.
  764. $info['options_select']['field types'][] = 'my_field_type';
  765. }
  766. /**
  767. * Return the form for a single field widget.
  768. *
  769. * Field widget form elements should be based on the passed-in $element, which
  770. * contains the base form element properties derived from the field
  771. * configuration.
  772. *
  773. * Field API will set the weight, field name and delta values for each form
  774. * element. If there are multiple values for this field, the Field API will
  775. * invoke this hook as many times as needed.
  776. *
  777. * Note that, depending on the context in which the widget is being included
  778. * (regular entity form, field configuration form, advanced search form...),
  779. * the values for $field and $instance might be different from the "official"
  780. * definitions returned by field_info_field() and field_info_instance().
  781. * Examples: mono-value widget even if the field is multi-valued, non-required
  782. * widget even if the field is 'required'...
  783. *
  784. * Therefore, the FAPI element callbacks (such as #process, #element_validate,
  785. * #value_callback...) used by the widget cannot use the field_info_field()
  786. * or field_info_instance() functions to retrieve the $field or $instance
  787. * definitions they should operate on. The field_widget_field() and
  788. * field_widget_instance() functions should be used instead to fetch the
  789. * current working definitions from $form_state, where Field API stores them.
  790. *
  791. * Alternatively, hook_field_widget_form() can extract the needed specific
  792. * properties from $field and $instance and set them as ad-hoc
  793. * $element['#custom'] properties, for later use by its element callbacks.
  794. *
  795. * Other modules may alter the form element provided by this function using
  796. * hook_field_widget_form_alter().
  797. *
  798. * @param $form
  799. * The form structure where widgets are being attached to. This might be a
  800. * full form structure, or a sub-element of a larger form.
  801. * @param $form_state
  802. * An associative array containing the current state of the form.
  803. * @param $field
  804. * The field structure.
  805. * @param $instance
  806. * The field instance.
  807. * @param $langcode
  808. * The language associated with $items.
  809. * @param $items
  810. * Array of default values for this field.
  811. * @param $delta
  812. * The order of this item in the array of subelements (0, 1, 2, etc).
  813. * @param $element
  814. * A form element array containing basic properties for the widget:
  815. * - #entity_type: The name of the entity the field is attached to.
  816. * - #bundle: The name of the field bundle the field is contained in.
  817. * - #field_name: The name of the field.
  818. * - #language: The language the field is being edited in.
  819. * - #field_parents: The 'parents' space for the field in the form. Most
  820. * widgets can simply overlook this property. This identifies the
  821. * location where the field values are placed within
  822. * $form_state['values'], and is used to access processing information
  823. * for the field through the field_form_get_state() and
  824. * field_form_set_state() functions.
  825. * - #columns: A list of field storage columns of the field.
  826. * - #title: The sanitized element label for the field instance, ready for
  827. * output.
  828. * - #description: The sanitized element description for the field instance,
  829. * ready for output.
  830. * - #required: A Boolean indicating whether the element value is required;
  831. * for required multiple value fields, only the first widget's values are
  832. * required.
  833. * - #delta: The order of this item in the array of subelements; see $delta
  834. * above.
  835. *
  836. * @return
  837. * The form elements for a single widget for this field.
  838. *
  839. * @see field_widget_field()
  840. * @see field_widget_instance()
  841. * @see hook_field_widget_form_alter()
  842. * @see hook_field_widget_WIDGET_TYPE_form_alter()
  843. */
  844. function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
  845. $element += array(
  846. '#type' => $instance['widget']['type'],
  847. '#default_value' => isset($items[$delta]) ? $items[$delta] : '',
  848. );
  849. return array('value' => $element);
  850. }
  851. /**
  852. * Alter forms for field widgets provided by other modules.
  853. *
  854. * @param $element
  855. * The field widget form element as constructed by hook_field_widget_form().
  856. * @param $form_state
  857. * An associative array containing the current state of the form.
  858. * @param $context
  859. * An associative array containing the following key-value pairs, matching the
  860. * arguments received by hook_field_widget_form():
  861. * - form: The form structure to which widgets are being attached. This may be
  862. * a full form structure, or a sub-element of a larger form.
  863. * - field: The field structure.
  864. * - instance: The field instance structure.
  865. * - langcode: The language associated with $items.
  866. * - items: Array of default values for this field.
  867. * - delta: The order of this item in the array of subelements (0, 1, 2, etc).
  868. *
  869. * @see hook_field_widget_form()
  870. * @see hook_field_widget_WIDGET_TYPE_form_alter()
  871. */
  872. function hook_field_widget_form_alter(&$element, &$form_state, $context) {
  873. // Add a css class to widget form elements for all fields of type mytype.
  874. if ($context['field']['type'] == 'mytype') {
  875. // Be sure not to overwrite existing attributes.
  876. $element['#attributes']['class'][] = 'myclass';
  877. }
  878. }
  879. /**
  880. * Alter widget forms for a specific widget provided by another module.
  881. *
  882. * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a
  883. * specific widget form, rather than using hook_field_widget_form_alter() and
  884. * checking the widget type.
  885. *
  886. * @param $element
  887. * The field widget form element as constructed by hook_field_widget_form().
  888. * @param $form_state
  889. * An associative array containing the current state of the form.
  890. * @param $context
  891. * An associative array containing the following key-value pairs, matching the
  892. * arguments received by hook_field_widget_form():
  893. * - "form": The form structure where widgets are being attached to. This
  894. * might be a full form structure, or a sub-element of a larger form.
  895. * - "field": The field structure.
  896. * - "instance": The field instance structure.
  897. * - "langcode": The language associated with $items.
  898. * - "items": Array of default values for this field.
  899. * - "delta": The order of this item in the array of subelements (0, 1, 2,
  900. * etc).
  901. *
  902. * @see hook_field_widget_form()
  903. * @see hook_field_widget_form_alter()
  904. */
  905. function hook_field_widget_WIDGET_TYPE_form_alter(&$element, &$form_state, $context) {
  906. // Code here will only act on widgets of type WIDGET_TYPE. For example,
  907. // hook_field_widget_mymodule_autocomplete_form_alter() will only act on
  908. // widgets of type 'mymodule_autocomplete'.
  909. $element['#autocomplete_path'] = 'mymodule/autocomplete_path';
  910. }
  911. /**
  912. * Alters the widget properties of a field instance before it gets displayed.
  913. *
  914. * Note that instead of hook_field_widget_properties_alter(), which is called
  915. * for all fields on all entity types,
  916. * hook_field_widget_properties_ENTITY_TYPE_alter() may be used to alter widget
  917. * properties for fields on a specific entity type only.
  918. *
  919. * This hook is called once per field per added or edit entity. If the result
  920. * of the hook involves reading from the database, it is highly recommended to
  921. * statically cache the information.
  922. *
  923. * @param $widget
  924. * The instance's widget properties.
  925. * @param $context
  926. * An associative array containing:
  927. * - entity_type: The entity type; e.g., 'node' or 'user'.
  928. * - entity: The entity object.
  929. * - field: The field that the widget belongs to.
  930. * - instance: The instance of the field.
  931. *
  932. * @see hook_field_widget_properties_ENTITY_TYPE_alter()
  933. */
  934. function hook_field_widget_properties_alter(&$widget, $context) {
  935. // Change a widget's type according to the time of day.
  936. $field = $context['field'];
  937. if ($context['entity_type'] == 'node' && $field['field_name'] == 'field_foo') {
  938. $time = date('H');
  939. $widget['type'] = $time < 12 ? 'widget_am' : 'widget_pm';
  940. }
  941. }
  942. /**
  943. * Flag a field-level validation error.
  944. *
  945. * @param $element
  946. * An array containing the form element for the widget. The error needs to be
  947. * flagged on the right sub-element, according to the widget's internal
  948. * structure.
  949. * @param $error
  950. * An associative array with the following key-value pairs, as returned by
  951. * hook_field_validate():
  952. * - error: the error code. Complex widgets might need to report different
  953. * errors to different form elements inside the widget.
  954. * - message: the human readable message to be displayed.
  955. * @param $form
  956. * The form structure where field elements are attached to. This might be a
  957. * full form structure, or a sub-element of a larger form.
  958. * @param $form_state
  959. * An associative array containing the current state of the form.
  960. */
  961. function hook_field_widget_error($element, $error, $form, &$form_state) {
  962. form_error($element, $error['message']);
  963. }
  964. /**
  965. * @} End of "defgroup field_widget".
  966. */
  967. /**
  968. * @defgroup field_formatter Field Formatter API
  969. * @{
  970. * Define Field API formatter types.
  971. *
  972. * Field API formatters specify how fields are displayed when the entity to
  973. * which the field is attached is displayed. Fields of a given
  974. * @link field_types field type @endlink may be displayed using more than one
  975. * formatter. In this case, the Field UI module allows the site builder to
  976. * choose which formatter to use. Field formatters are defined by implementing
  977. * hook_field_formatter_info().
  978. *
  979. * @see field
  980. * @see field_types
  981. * @see field_widget
  982. */
  983. /**
  984. * Expose Field API formatter types.
  985. *
  986. * Formatters handle the display of field values. Formatter hooks are typically
  987. * called by the Field Attach API field_attach_prepare_view() and
  988. * field_attach_view() functions.
  989. *
  990. * @return
  991. * An array describing the formatter types implemented by the module.
  992. * The keys are formatter type names. To avoid name clashes, formatter type
  993. * names should be prefixed with the name of the module that exposes them.
  994. * The values are arrays describing the formatter type, with the following
  995. * key/value pairs:
  996. * - label: The human-readable name of the formatter type.
  997. * - description: A short description for the formatter type.
  998. * - field types: An array of field types the formatter supports.
  999. * - settings: An array whose keys are the names of the settings available
  1000. * for the formatter type, and whose values are the default values for
  1001. * those settings.
  1002. *
  1003. * @see hook_field_formatter_info_alter()
  1004. * @see hook_field_formatter_view()
  1005. * @see hook_field_formatter_prepare_view()
  1006. */
  1007. function hook_field_formatter_info() {
  1008. return array(
  1009. 'text_default' => array(
  1010. 'label' => t('Default'),
  1011. 'field types' => array('text', 'text_long', 'text_with_summary'),
  1012. ),
  1013. 'text_plain' => array(
  1014. 'label' => t('Plain text'),
  1015. 'field types' => array('text', 'text_long', 'text_with_summary'),
  1016. ),
  1017. // The text_trimmed formatter displays the trimmed version of the
  1018. // full element of the field. It is intended to be used with text
  1019. // and text_long fields. It also works with text_with_summary
  1020. // fields though the text_summary_or_trimmed formatter makes more
  1021. // sense for that field type.
  1022. 'text_trimmed' => array(
  1023. 'label' => t('Trimmed'),
  1024. 'field types' => array('text', 'text_long', 'text_with_summary'),
  1025. ),
  1026. // The 'summary or trimmed' field formatter for text_with_summary
  1027. // fields displays returns the summary element of the field or, if
  1028. // the summary is empty, the trimmed version of the full element
  1029. // of the field.
  1030. 'text_summary_or_trimmed' => array(
  1031. 'label' => t('Summary or trimmed'),
  1032. 'field types' => array('text_with_summary'),
  1033. ),
  1034. );
  1035. }
  1036. /**
  1037. * Perform alterations on Field API formatter types.
  1038. *
  1039. * @param $info
  1040. * An array of information on formatter types exposed by
  1041. * hook_field_formatter_info() implementations.
  1042. */
  1043. function hook_field_formatter_info_alter(&$info) {
  1044. // Add a setting to a formatter type.
  1045. $info['text_default']['settings'] += array(
  1046. 'mymodule_additional_setting' => 'default value',
  1047. );
  1048. // Let a new field type re-use an existing formatter.
  1049. $info['text_default']['field types'][] = 'my_field_type';
  1050. }
  1051. /**
  1052. * Allow formatters to load information for field values being displayed.
  1053. *
  1054. * This should be used when a formatter needs to load additional information
  1055. * from the database in order to render a field, for example a reference field
  1056. * which displays properties of the referenced entities such as name or type.
  1057. *
  1058. * This hook is called after the field type's own hook_field_prepare_view().
  1059. *
  1060. * Unlike most other field hooks, this hook operates on multiple entities. The
  1061. * $entities, $instances and $items parameters are arrays keyed by entity ID.
  1062. * For performance reasons, information for all available entities should be
  1063. * loaded in a single query where possible.
  1064. *
  1065. * @param $entity_type
  1066. * The type of $entity.
  1067. * @param $entities
  1068. * Array of entities being displayed, keyed by entity ID.
  1069. * @param $field
  1070. * The field structure for the operation.
  1071. * @param $instances
  1072. * Array of instance structures for $field for each entity, keyed by entity
  1073. * ID.
  1074. * @param $langcode
  1075. * The language the field values are to be shown in. If no language is
  1076. * provided the current language is used.
  1077. * @param $items
  1078. * Array of field values for the entities, keyed by entity ID.
  1079. * @param $displays
  1080. * Array of display settings to use for each entity, keyed by entity ID.
  1081. *
  1082. * @return
  1083. * Changes or additions to field values are done by altering the $items
  1084. * parameter by reference.
  1085. */
  1086. function hook_field_formatter_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items, $displays) {
  1087. $tids = array();
  1088. // Collect every possible term attached to any of the fieldable entities.
  1089. foreach ($entities as $id => $entity) {
  1090. foreach ($items[$id] as $delta => $item) {
  1091. // Force the array key to prevent duplicates.
  1092. $tids[$item['tid']] = $item['tid'];
  1093. }
  1094. }
  1095. if ($tids) {
  1096. $terms = taxonomy_term_load_multiple($tids);
  1097. // Iterate through the fieldable entities again to attach the loaded term
  1098. // data.
  1099. foreach ($entities as $id => $entity) {
  1100. $rekey = FALSE;
  1101. foreach ($items[$id] as $delta => $item) {
  1102. // Check whether the taxonomy term field instance value could be loaded.
  1103. if (isset($terms[$item['tid']])) {
  1104. // Replace the instance value with the term data.
  1105. $items[$id][$delta]['taxonomy_term'] = $terms[$item['tid']];
  1106. }
  1107. // Otherwise, unset the instance value, since the term does not exist.
  1108. else {
  1109. unset($items[$id][$delta]);
  1110. $rekey = TRUE;
  1111. }
  1112. }
  1113. if ($rekey) {
  1114. // Rekey the items array.
  1115. $items[$id] = array_values($items[$id]);
  1116. }
  1117. }
  1118. }
  1119. }
  1120. /**
  1121. * Build a renderable array for a field value.
  1122. *
  1123. * @param $entity_type
  1124. * The type of $entity.
  1125. * @param $entity
  1126. * The entity being displayed.
  1127. * @param $field
  1128. * The field structure.
  1129. * @param $instance
  1130. * The field instance.
  1131. * @param $langcode
  1132. * The language associated with $items.
  1133. * @param $items
  1134. * Array of values for this field.
  1135. * @param $display
  1136. * The display settings to use, as found in the 'display' entry of instance
  1137. * definitions. The array notably contains the following keys and values;
  1138. * - type: The name of the formatter to use.
  1139. * - settings: The array of formatter settings.
  1140. *
  1141. * @return
  1142. * A renderable array for the $items, as an array of child elements keyed
  1143. * by numeric indexes starting from 0.
  1144. */
  1145. function hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  1146. $element = array();
  1147. $settings = $display['settings'];
  1148. switch ($display['type']) {
  1149. case 'sample_field_formatter_simple':
  1150. // Common case: each value is displayed individually in a sub-element
  1151. // keyed by delta. The field.tpl.php template specifies the markup
  1152. // wrapping each value.
  1153. foreach ($items as $delta => $item) {
  1154. $element[$delta] = array('#markup' => $settings['some_setting'] . $item['value']);
  1155. }
  1156. break;
  1157. case 'sample_field_formatter_themeable':
  1158. // More elaborate formatters can defer to a theme function for easier
  1159. // customization.
  1160. foreach ($items as $delta => $item) {
  1161. $element[$delta] = array(
  1162. '#theme' => 'mymodule_theme_sample_field_formatter_themeable',
  1163. '#data' => $item['value'],
  1164. '#some_setting' => $settings['some_setting'],
  1165. );
  1166. }
  1167. break;
  1168. case 'sample_field_formatter_combined':
  1169. // Some formatters might need to display all values within a single piece
  1170. // of markup.
  1171. $rows = array();
  1172. foreach ($items as $delta => $item) {
  1173. $rows[] = array($delta, $item['value']);
  1174. }
  1175. $element[0] = array(
  1176. '#theme' => 'table',
  1177. '#header' => array(t('Delta'), t('Value')),
  1178. '#rows' => $rows,
  1179. );
  1180. break;
  1181. }
  1182. return $element;
  1183. }
  1184. /**
  1185. * @} End of "defgroup field_formatter".
  1186. */
  1187. /**
  1188. * @ingroup field_attach
  1189. * @{
  1190. */
  1191. /**
  1192. * Act on field_attach_form().
  1193. *
  1194. * This hook is invoked after the field module has performed the operation.
  1195. * Implementing modules should alter the $form or $form_state parameters.
  1196. *
  1197. * @param $entity_type
  1198. * The type of $entity; for example, 'node' or 'user'.
  1199. * @param $entity
  1200. * The entity for which an edit form is being built.
  1201. * @param $form
  1202. * The form structure where field elements are attached to. This might be a
  1203. * full form structure, or a sub-element of a larger form. The
  1204. * $form['#parents'] property can be used to identify the corresponding part
  1205. * of $form_state['values']. Hook implementations that need to act on the
  1206. * top-level properties of the global form (like #submit, #validate...) can
  1207. * add a #process callback to the array received in the $form parameter, and
  1208. * act on the $complete_form parameter in the process callback.
  1209. * @param $form_state
  1210. * An associative array containing the current state of the form.
  1211. * @param $langcode
  1212. * The language the field values are going to be entered in. If no language
  1213. * is provided the default site language will be used.
  1214. */
  1215. function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $langcode) {
  1216. // Add a checkbox allowing a given field to be emptied.
  1217. // See hook_field_attach_submit() for the corresponding processing code.
  1218. $form['empty_field_foo'] = array(
  1219. '#type' => 'checkbox',
  1220. '#title' => t("Empty the 'field_foo' field"),
  1221. );
  1222. }
  1223. /**
  1224. * Act on field_attach_load().
  1225. *
  1226. * This hook is invoked after the field module has performed the operation.
  1227. *
  1228. * Unlike other field_attach hooks, this hook accounts for 'multiple loads'.
  1229. * Instead of the usual $entity parameter, it accepts an array of entities,
  1230. * indexed by entity ID. For performance reasons, information for all available
  1231. * entities should be loaded in a single query where possible.
  1232. *
  1233. * The changes made to the entities' field values get cached by the field cache
  1234. * for subsequent loads.
  1235. *
  1236. * See field_attach_load() for details and arguments.
  1237. */
  1238. function hook_field_attach_load($entity_type, $entities, $age, $options) {
  1239. // @todo Needs function body.
  1240. }
  1241. /**
  1242. * Act on field_attach_validate().
  1243. *
  1244. * This hook is invoked after the field module has performed the operation.
  1245. *
  1246. * See field_attach_validate() for details and arguments.
  1247. */
  1248. function hook_field_attach_validate($entity_type, $entity, &$errors) {
  1249. // @todo Needs function body.
  1250. }
  1251. /**
  1252. * Act on field_attach_submit().
  1253. *
  1254. * This hook is invoked after the field module has performed the operation.
  1255. *
  1256. * @param $entity_type
  1257. * The type of $entity; for example, 'node' or 'user'.
  1258. * @param $entity
  1259. * The entity for which an edit form is being submitted. The incoming form
  1260. * values have been extracted as field values of the $entity object.
  1261. * @param $form
  1262. * The form structure where field elements are attached to. This might be a
  1263. * full form structure, or a sub-part of a larger form. The $form['#parents']
  1264. * property can be used to identify the corresponding part of
  1265. * $form_state['values'].
  1266. * @param $form_state
  1267. * An associative array containing the current state of the form.
  1268. */
  1269. function hook_field_attach_submit($entity_type, $entity, $form, &$form_state) {
  1270. // Sample case of an 'Empty the field' checkbox added on the form, allowing
  1271. // a given field to be emptied.
  1272. $values = drupal_array_get_nested_value($form_state['values'], $form['#parents']);
  1273. if (!empty($values['empty_field_foo'])) {
  1274. unset($entity->field_foo);
  1275. }
  1276. }
  1277. /**
  1278. * Act on field_attach_presave().
  1279. *
  1280. * This hook is invoked after the field module has performed the operation.
  1281. *
  1282. * See field_attach_presave() for details and arguments.
  1283. */
  1284. function hook_field_attach_presave($entity_type, $entity) {
  1285. // @todo Needs function body.
  1286. }
  1287. /**
  1288. * Act on field_attach_insert().
  1289. *
  1290. * This hook is invoked after the field module has performed the operation.
  1291. *
  1292. * See field_attach_insert() for details and arguments.
  1293. */
  1294. function hook_field_attach_insert($entity_type, $entity) {
  1295. // @todo Needs function body.
  1296. }
  1297. /**
  1298. * Act on field_attach_update().
  1299. *
  1300. * This hook is invoked after the field module has performed the operation.
  1301. *
  1302. * See field_attach_update() for details and arguments.
  1303. */
  1304. function hook_field_attach_update($entity_type, $entity) {
  1305. // @todo Needs function body.
  1306. }
  1307. /**
  1308. * Alter field_attach_preprocess() variables.
  1309. *
  1310. * This hook is invoked while preprocessing the field.tpl.php template file
  1311. * in field_attach_preprocess().
  1312. *
  1313. * @param $variables
  1314. * The variables array is passed by reference and will be populated with field
  1315. * values.
  1316. * @param $context
  1317. * An associative array containing:
  1318. * - entity_type: The type of $entity; for example, 'node' or 'user'.
  1319. * - entity: The entity with fields to render.
  1320. * - element: The structured array containing the values ready for rendering.
  1321. */
  1322. function hook_field_attach_preprocess_alter(&$variables, $context) {
  1323. // @todo Needs function body.
  1324. }
  1325. /**
  1326. * Act on field_attach_delete().
  1327. *
  1328. * This hook is invoked after the field module has performed the operation.
  1329. *
  1330. * See field_attach_delete() for details and arguments.
  1331. */
  1332. function hook_field_attach_delete($entity_type, $entity) {
  1333. // @todo Needs function body.
  1334. }
  1335. /**
  1336. * Act on field_attach_delete_revision().
  1337. *
  1338. * This hook is invoked after the field module has performed the operation.
  1339. *
  1340. * See field_attach_delete_revision() for details and arguments.
  1341. */
  1342. function hook_field_attach_delete_revision($entity_type, $entity) {
  1343. // @todo Needs function body.
  1344. }
  1345. /**
  1346. * Act on field_purge_data().
  1347. *
  1348. * This hook is invoked in field_purge_data() and allows modules to act on
  1349. * purging data from a single field pseudo-entity. For example, if a module
  1350. * relates data in the field with its own data, it may purge its own data
  1351. * during this process as well.
  1352. *
  1353. * @param $entity_type
  1354. * The type of $entity; for example, 'node' or 'user'.
  1355. * @param $entity
  1356. * The pseudo-entity whose field data is being purged.
  1357. * @param $field
  1358. * The (possibly deleted) field whose data is being purged.
  1359. * @param $instance
  1360. * The deleted field instance whose data is being purged.
  1361. *
  1362. * @see @link field_purge Field API bulk data deletion @endlink
  1363. * @see field_purge_data()
  1364. */
  1365. function hook_field_attach_purge($entity_type, $entity, $field, $instance) {
  1366. // find the corresponding data in mymodule and purge it
  1367. if ($entity_type == 'node' && $field->field_name == 'my_field_name') {
  1368. mymodule_remove_mydata($entity->nid);
  1369. }
  1370. }
  1371. /**
  1372. * Perform alterations on field_attach_view() or field_view_field().
  1373. *
  1374. * This hook is invoked after the field module has performed the operation.
  1375. *
  1376. * @param $output
  1377. * The structured content array tree for all of the entity's fields.
  1378. * @param $context
  1379. * An associative array containing:
  1380. * - entity_type: The type of $entity; for example, 'node' or 'user'.
  1381. * - entity: The entity with fields to render.
  1382. * - view_mode: View mode; for example, 'full' or 'teaser'.
  1383. * - display: Either a view mode string or an array of display settings. If
  1384. * this hook is being invoked from field_attach_view(), the 'display'
  1385. * element is set to the view mode string. If this hook is being invoked
  1386. * from field_view_field(), this element is set to the $display argument
  1387. * and the view_mode element is set to '_custom'. See field_view_field()
  1388. * for more information on what its $display argument contains.
  1389. * - language: The language code used for rendering.
  1390. */
  1391. function hook_field_attach_view_alter(&$output, $context) {
  1392. // Append RDF term mappings on displayed taxonomy links.
  1393. foreach (element_children($output) as $field_name) {
  1394. $element = &$output[$field_name];
  1395. if ($element['#field_type'] == 'taxonomy_term_reference' && $element['#formatter'] == 'taxonomy_term_reference_link') {
  1396. foreach ($element['#items'] as $delta => $item) {
  1397. $term = $item['taxonomy_term'];
  1398. if (!empty($term->rdf_mapping['rdftype'])) {
  1399. $element[$delta]['#options']['attributes']['typeof'] = $term->rdf_mapping['rdftype'];
  1400. }
  1401. if (!empty($term->rdf_mapping['name']['predicates'])) {
  1402. $element[$delta]['#options']['attributes']['property'] = $term->rdf_mapping['name']['predicates'];
  1403. }
  1404. }
  1405. }
  1406. }
  1407. }
  1408. /**
  1409. * Perform alterations on field_attach_prepare_translation().
  1410. *
  1411. * This hook is invoked after the field module has performed the operation.
  1412. *
  1413. * @param $entity
  1414. * The entity being prepared for translation.
  1415. * @param $context
  1416. * An associative array containing:
  1417. * - entity_type: The type of $entity; e.g. 'node' or 'user'.
  1418. * - langcode: The language the entity has to be translated in.
  1419. * - source_entity: The entity holding the field values to be translated.
  1420. * - source_langcode: The source language from which translate.
  1421. */
  1422. function hook_field_attach_prepare_translation_alter(&$entity, $context) {
  1423. if ($context['entity_type'] == 'custom_entity_type') {
  1424. $entity->custom_field = $context['source_entity']->custom_field;
  1425. }
  1426. }
  1427. /**
  1428. * Perform alterations on field_language() values.
  1429. *
  1430. * This hook is invoked to alter the array of display languages for the given
  1431. * entity.
  1432. *
  1433. * @param $display_language
  1434. * A reference to an array of language codes keyed by field name.
  1435. * @param $context
  1436. * An associative array containing:
  1437. * - entity_type: The type of the entity to be displayed.
  1438. * - entity: The entity with fields to render.
  1439. * - langcode: The language code $entity has to be displayed in.
  1440. */
  1441. function hook_field_language_alter(&$display_language, $context) {
  1442. // Do not apply core language fallback rules if they are disabled or if Locale
  1443. // is not registered as a translation handler.
  1444. if (variable_get('locale_field_language_fallback', TRUE) && field_has_translation_handler($context['entity_type'], 'locale')) {
  1445. locale_field_language_fallback($display_language, $context['entity'], $context['language']);
  1446. }
  1447. }
  1448. /**
  1449. * Alter field_available_languages() values.
  1450. *
  1451. * This hook is invoked from field_available_languages() to allow modules to
  1452. * alter the array of available languages for the given field.
  1453. *
  1454. * @param $languages
  1455. * A reference to an array of language codes to be made available.
  1456. * @param $context
  1457. * An associative array containing:
  1458. * - entity_type: The type of the entity the field is attached to.
  1459. * - field: A field data structure.
  1460. */
  1461. function hook_field_available_languages_alter(&$languages, $context) {
  1462. // Add an unavailable language.
  1463. $languages[] = 'xx';
  1464. // Remove an available language.
  1465. $index = array_search('yy', $languages);
  1466. unset($languages[$index]);
  1467. }
  1468. /**
  1469. * Act on field_attach_create_bundle().
  1470. *
  1471. * This hook is invoked after the field module has performed the operation.
  1472. *
  1473. * See field_attach_create_bundle() for details and arguments.
  1474. */
  1475. function hook_field_attach_create_bundle($entity_type, $bundle) {
  1476. // When a new bundle is created, the menu needs to be rebuilt to add the
  1477. // Field UI menu item tabs.
  1478. variable_set('menu_rebuild_needed', TRUE);
  1479. }
  1480. /**
  1481. * Act on field_attach_rename_bundle().
  1482. *
  1483. * This hook is invoked after the field module has performed the operation.
  1484. *
  1485. * See field_attach_rename_bundle() for details and arguments.
  1486. */
  1487. function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
  1488. // Update the extra weights variable with new information.
  1489. if ($bundle_old !== $bundle_new) {
  1490. $extra_weights = variable_get('field_extra_weights', array());
  1491. if (isset($info[$entity_type][$bundle_old])) {
  1492. $extra_weights[$entity_type][$bundle_new] = $extra_weights[$entity_type][$bundle_old];
  1493. unset($extra_weights[$entity_type][$bundle_old]);
  1494. variable_set('field_extra_weights', $extra_weights);
  1495. }
  1496. }
  1497. }
  1498. /**
  1499. * Act on field_attach_delete_bundle.
  1500. *
  1501. * This hook is invoked after the field module has performed the operation.
  1502. *
  1503. * @param $entity_type
  1504. * The type of entity; for example, 'node' or 'user'.
  1505. * @param $bundle
  1506. * The bundle that was just deleted.
  1507. * @param $instances
  1508. * An array of all instances that existed for the bundle before it was
  1509. * deleted.
  1510. */
  1511. function hook_field_attach_delete_bundle($entity_type, $bundle, $instances) {
  1512. // Remove the extra weights variable information for this bundle.
  1513. $extra_weights = variable_get('field_extra_weights', array());
  1514. if (isset($extra_weights[$entity_type][$bundle])) {
  1515. unset($extra_weights[$entity_type][$bundle]);
  1516. variable_set('field_extra_weights', $extra_weights);
  1517. }
  1518. }
  1519. /**
  1520. * @} End of "defgroup field_attach".
  1521. */
  1522. /**
  1523. * @addtogroup field_storage
  1524. * @{
  1525. */
  1526. /**
  1527. * Expose Field API storage backends.
  1528. *
  1529. * @return
  1530. * An array describing the storage backends implemented by the module.
  1531. * The keys are storage backend names. To avoid name clashes, storage backend
  1532. * names should be prefixed with the name of the module that exposes them.
  1533. * The values are arrays describing the storage backend, with the following
  1534. * key/value pairs:
  1535. * - label: The human-readable name of the storage backend.
  1536. * - description: A short description for the storage backend.
  1537. * - settings: An array whose keys are the names of the settings available
  1538. * for the storage backend, and whose values are the default values for
  1539. * those settings.
  1540. */
  1541. function hook_field_storage_info() {
  1542. return array(
  1543. 'field_sql_storage' => array(
  1544. 'label' => t('Default SQL storage'),
  1545. 'description' => t('Stores fields in the local SQL database, using per-field tables.'),
  1546. 'settings' => array(),
  1547. ),
  1548. );
  1549. }
  1550. /**
  1551. * Perform alterations on Field API storage types.
  1552. *
  1553. * @param $info
  1554. * Array of informations on storage types exposed by
  1555. * hook_field_field_storage_info() implementations.
  1556. */
  1557. function hook_field_storage_info_alter(&$info) {
  1558. // Add a setting to a storage type.
  1559. $info['field_sql_storage']['settings'] += array(
  1560. 'mymodule_additional_setting' => 'default value',
  1561. );
  1562. }
  1563. /**
  1564. * Reveal the internal details about the storage for a field.
  1565. *
  1566. * For example, an SQL storage module might return the Schema API structure for
  1567. * the table. A key/value storage module might return the server name,
  1568. * authentication credentials, and bin name.
  1569. *
  1570. * Field storage modules are not obligated to implement this hook. Modules
  1571. * that rely on these details must only use them for read operations.
  1572. *
  1573. * @param $field
  1574. * A field structure.
  1575. *
  1576. * @return
  1577. * An array of details.
  1578. * - The first dimension is a store type (sql, solr, etc).
  1579. * - The second dimension indicates the age of the values in the store
  1580. * FIELD_LOAD_CURRENT or FIELD_LOAD_REVISION.
  1581. * - Other dimensions are specific to the field storage module.
  1582. *
  1583. * @see hook_field_storage_details_alter()
  1584. */
  1585. function hook_field_storage_details($field) {
  1586. $details = array();
  1587. // Add field columns.
  1588. foreach ((array) $field['columns'] as $column_name => $attributes) {
  1589. $real_name = _field_sql_storage_columnname($field['field_name'], $column_name);
  1590. $columns[$column_name] = $real_name;
  1591. }
  1592. return array(
  1593. 'sql' => array(
  1594. FIELD_LOAD_CURRENT => array(
  1595. _field_sql_storage_tablename($field) => $columns,
  1596. ),
  1597. FIELD_LOAD_REVISION => array(
  1598. _field_sql_storage_revision_tablename($field) => $columns,
  1599. ),
  1600. ),
  1601. );
  1602. }
  1603. /**
  1604. * Perform alterations on Field API storage details.
  1605. *
  1606. * @param $details
  1607. * An array of storage details for fields as exposed by
  1608. * hook_field_storage_details() implementations.
  1609. * @param $field
  1610. * A field structure.
  1611. *
  1612. * @see hook_field_storage_details()
  1613. */
  1614. function hook_field_storage_details_alter(&$details, $field) {
  1615. if ($field['field_name'] == 'field_of_interest') {
  1616. $columns = array();
  1617. foreach ((array) $field['columns'] as $column_name => $attributes) {
  1618. $columns[$column_name] = $column_name;
  1619. }
  1620. $details['drupal_variables'] = array(
  1621. FIELD_LOAD_CURRENT => array(
  1622. 'moon' => $columns,
  1623. ),
  1624. FIELD_LOAD_REVISION => array(
  1625. 'mars' => $columns,
  1626. ),
  1627. );
  1628. }
  1629. }
  1630. /**
  1631. * Load field data for a set of entities.
  1632. *
  1633. * This hook is invoked from field_attach_load() to ask the field storage
  1634. * module to load field data.
  1635. *
  1636. * Modules implementing this hook should load field values and add them to
  1637. * objects in $entities. Fields with no values should be added as empty
  1638. * arrays.
  1639. *
  1640. * @param $entity_type
  1641. * The type of entity, such as 'node' or 'user'.
  1642. * @param $entities
  1643. * The array of entity objects to add fields to, keyed by entity ID.
  1644. * @param $age
  1645. * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
  1646. * FIELD_LOAD_REVISION to load the version indicated by each entity.
  1647. * @param $fields
  1648. * An array listing the fields to be loaded. The keys of the array are field
  1649. * IDs, and the values of the array are the entity IDs (or revision IDs,
  1650. * depending on the $age parameter) to add each field to.
  1651. * @param $options
  1652. * An associative array of additional options, with the following keys:
  1653. * - deleted: If TRUE, deleted fields should be loaded as well as
  1654. * non-deleted fields. If unset or FALSE, only non-deleted fields should be
  1655. * loaded.
  1656. */
  1657. function hook_field_storage_load($entity_type, $entities, $age, $fields, $options) {
  1658. $load_current = $age == FIELD_LOAD_CURRENT;
  1659. foreach ($fields as $field_id => $ids) {
  1660. // By the time this hook runs, the relevant field definitions have been
  1661. // populated and cached in FieldInfo, so calling field_info_field_by_id()
  1662. // on each field individually is more efficient than loading all fields in
  1663. // memory upfront with field_info_field_by_ids().
  1664. $field = field_info_field_by_id($field_id);
  1665. $field_name = $field['field_name'];
  1666. $table = $load_current ? _field_sql_storage_tablename($field) : _field_sql_storage_revision_tablename($field);
  1667. $query = db_select($table, 't')
  1668. ->fields('t')
  1669. ->condition('entity_type', $entity_type)
  1670. ->condition($load_current ? 'entity_id' : 'revision_id', $ids, 'IN')
  1671. ->condition('language', field_available_languages($entity_type, $field), 'IN')
  1672. ->orderBy('delta');
  1673. if (empty($options['deleted'])) {
  1674. $query->condition('deleted', 0);
  1675. }
  1676. $results = $query->execute();
  1677. $delta_count = array();
  1678. foreach ($results as $row) {
  1679. if (!isset($delta_count[$row->entity_id][$row->language])) {
  1680. $delta_count[$row->entity_id][$row->language] = 0;
  1681. }
  1682. if ($field['cardinality'] == FIELD_CARDINALITY_UNLIMITED || $delta_count[$row->entity_id][$row->language] < $field['cardinality']) {
  1683. $item = array();
  1684. // For each column declared by the field, populate the item
  1685. // from the prefixed database column.
  1686. foreach ($field['columns'] as $column => $attributes) {
  1687. $column_name = _field_sql_storage_columnname($field_name, $column);
  1688. $item[$column] = $row->$column_name;
  1689. }
  1690. // Add the item to the field values for the entity.
  1691. $entities[$row->entity_id]->{$field_name}[$row->language][] = $item;
  1692. $delta_count[$row->entity_id][$row->language]++;
  1693. }
  1694. }
  1695. }
  1696. }
  1697. /**
  1698. * Write field data for an entity.
  1699. *
  1700. * This hook is invoked from field_attach_insert() and field_attach_update(),
  1701. * to ask the field storage module to save field data.
  1702. *
  1703. * @param $entity_type
  1704. * The entity type of entity, such as 'node' or 'user'.
  1705. * @param $entity
  1706. * The entity on which to operate.
  1707. * @param $op
  1708. * FIELD_STORAGE_UPDATE when updating an existing entity,
  1709. * FIELD_STORAGE_INSERT when inserting a new entity.
  1710. * @param $fields
  1711. * An array listing the fields to be written. The keys and values of the
  1712. * array are field IDs.
  1713. */
  1714. function hook_field_storage_write($entity_type, $entity, $op, $fields) {
  1715. list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
  1716. if (!isset($vid)) {
  1717. $vid = $id;
  1718. }
  1719. foreach ($fields as $field_id) {
  1720. $field = field_info_field_by_id($field_id);
  1721. $field_name = $field['field_name'];
  1722. $table_name = _field_sql_storage_tablename($field);
  1723. $revision_name = _field_sql_storage_revision_tablename($field);
  1724. $all_languages = field_available_languages($entity_type, $field);
  1725. $field_languages = array_intersect($all_languages, array_keys((array) $entity->$field_name));
  1726. // Delete and insert, rather than update, in case a value was added.
  1727. if ($op == FIELD_STORAGE_UPDATE) {
  1728. // Delete languages present in the incoming $entity->$field_name.
  1729. // Delete all languages if $entity->$field_name is empty.
  1730. $languages = !empty($entity->$field_name) ? $field_languages : $all_languages;
  1731. if ($languages) {
  1732. db_delete($table_name)
  1733. ->condition('entity_type', $entity_type)
  1734. ->condition('entity_id', $id)
  1735. ->condition('language', $languages, 'IN')
  1736. ->execute();
  1737. db_delete($revision_name)
  1738. ->condition('entity_type', $entity_type)
  1739. ->condition('entity_id', $id)
  1740. ->condition('revision_id', $vid)
  1741. ->condition('language', $languages, 'IN')
  1742. ->execute();
  1743. }
  1744. }
  1745. // Prepare the multi-insert query.
  1746. $do_insert = FALSE;
  1747. $columns = array('entity_type', 'entity_id', 'revision_id', 'bundle', 'delta', 'language');
  1748. foreach ($field['columns'] as $column => $attributes) {
  1749. $columns[] = _field_sql_storage_columnname($field_name, $column);
  1750. }
  1751. $query = db_insert($table_name)->fields($columns);
  1752. $revision_query = db_insert($revision_name)->fields($columns);
  1753. foreach ($field_languages as $langcode) {
  1754. $items = (array) $entity->{$field_name}[$langcode];
  1755. $delta_count = 0;
  1756. foreach ($items as $delta => $item) {
  1757. // We now know we have someting to insert.
  1758. $do_insert = TRUE;
  1759. $record = array(
  1760. 'entity_type' => $entity_type,
  1761. 'entity_id' => $id,
  1762. 'revision_id' => $vid,
  1763. 'bundle' => $bundle,
  1764. 'delta' => $delta,
  1765. 'language' => $langcode,
  1766. );
  1767. foreach ($field['columns'] as $column => $attributes) {
  1768. $record[_field_sql_storage_columnname($field_name, $column)] = isset($item[$column]) ? $item[$column] : NULL;
  1769. }
  1770. $query->values($record);
  1771. if (isset($vid)) {
  1772. $revision_query->values($record);
  1773. }
  1774. if ($field['cardinality'] != FIELD_CARDINALITY_UNLIMITED && ++$delta_count == $field['cardinality']) {
  1775. break;
  1776. }
  1777. }
  1778. }
  1779. // Execute the query if we have values to insert.
  1780. if ($do_insert) {
  1781. $query->execute();
  1782. $revision_query->execute();
  1783. }
  1784. }
  1785. }
  1786. /**
  1787. * Delete all field data for an entity.
  1788. *
  1789. * This hook is invoked from field_attach_delete() to ask the field storage
  1790. * module to delete field data.
  1791. *
  1792. * @param $entity_type
  1793. * The entity type of entity, such as 'node' or 'user'.
  1794. * @param $entity
  1795. * The entity on which to operate.
  1796. * @param $fields
  1797. * An array listing the fields to delete. The keys and values of the
  1798. * array are field IDs.
  1799. */
  1800. function hook_field_storage_delete($entity_type, $entity, $fields) {
  1801. list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
  1802. foreach (field_info_instances($entity_type, $bundle) as $instance) {
  1803. if (isset($fields[$instance['field_id']])) {
  1804. $field = field_info_field_by_id($instance['field_id']);
  1805. field_sql_storage_field_storage_purge($entity_type, $entity, $field, $instance);
  1806. }
  1807. }
  1808. }
  1809. /**
  1810. * Delete a single revision of field data for an entity.
  1811. *
  1812. * This hook is invoked from field_attach_delete_revision() to ask the field
  1813. * storage module to delete field revision data.
  1814. *
  1815. * Deleting the current (most recently written) revision is not
  1816. * allowed as has undefined results.
  1817. *
  1818. * @param $entity_type
  1819. * The entity type of entity, such as 'node' or 'user'.
  1820. * @param $entity
  1821. * The entity on which to operate. The revision to delete is
  1822. * indicated by the entity's revision ID property, as identified by
  1823. * hook_fieldable_info() for $entity_type.
  1824. * @param $fields
  1825. * An array listing the fields to delete. The keys and values of the
  1826. * array are field IDs.
  1827. */
  1828. function hook_field_storage_delete_revision($entity_type, $entity, $fields) {
  1829. list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
  1830. if (isset($vid)) {
  1831. foreach ($fields as $field_id) {
  1832. $field = field_info_field_by_id($field_id);
  1833. $revision_name = _field_sql_storage_revision_tablename($field);
  1834. db_delete($revision_name)
  1835. ->condition('entity_type', $entity_type)
  1836. ->condition('entity_id', $id)
  1837. ->condition('revision_id', $vid)
  1838. ->execute();
  1839. }
  1840. }
  1841. }
  1842. /**
  1843. * Execute an EntityFieldQuery.
  1844. *
  1845. * This hook is called to find the entities having certain entity and field
  1846. * conditions and sort them in the given field order. If the field storage
  1847. * engine also handles property sorts and orders, it should unset those
  1848. * properties in the called object to signal that those have been handled.
  1849. *
  1850. * @param EntityFieldQuery $query
  1851. * An EntityFieldQuery.
  1852. *
  1853. * @return
  1854. * See EntityFieldQuery::execute() for the return values.
  1855. */
  1856. function hook_field_storage_query($query) {
  1857. $groups = array();
  1858. if ($query->age == FIELD_LOAD_CURRENT) {
  1859. $tablename_function = '_field_sql_storage_tablename';
  1860. $id_key = 'entity_id';
  1861. }
  1862. else {
  1863. $tablename_function = '_field_sql_storage_revision_tablename';
  1864. $id_key = 'revision_id';
  1865. }
  1866. $table_aliases = array();
  1867. // Add tables for the fields used.
  1868. foreach ($query->fields as $key => $field) {
  1869. $tablename = $tablename_function($field);
  1870. // Every field needs a new table.
  1871. $table_alias = $tablename . $key;
  1872. $table_aliases[$key] = $table_alias;
  1873. if ($key) {
  1874. $select_query->join($tablename, $table_alias, "$table_alias.entity_type = $field_base_table.entity_type AND $table_alias.$id_key = $field_base_table.$id_key");
  1875. }
  1876. else {
  1877. $select_query = db_select($tablename, $table_alias);
  1878. $select_query->addTag('entity_field_access');
  1879. $select_query->addMetaData('base_table', $tablename);
  1880. $select_query->fields($table_alias, array('entity_type', 'entity_id', 'revision_id', 'bundle'));
  1881. $field_base_table = $table_alias;
  1882. }
  1883. if ($field['cardinality'] != 1) {
  1884. $select_query->distinct();
  1885. }
  1886. }
  1887. // Add field conditions.
  1888. foreach ($query->fieldConditions as $key => $condition) {
  1889. $table_alias = $table_aliases[$key];
  1890. $field = $condition['field'];
  1891. // Add the specified condition.
  1892. $sql_field = "$table_alias." . _field_sql_storage_columnname($field['field_name'], $condition['column']);
  1893. $query->addCondition($select_query, $sql_field, $condition);
  1894. // Add delta / language group conditions.
  1895. foreach (array('delta', 'language') as $column) {
  1896. if (isset($condition[$column . '_group'])) {
  1897. $group_name = $condition[$column . '_group'];
  1898. if (!isset($groups[$column][$group_name])) {
  1899. $groups[$column][$group_name] = $table_alias;
  1900. }
  1901. else {
  1902. $select_query->where("$table_alias.$column = " . $groups[$column][$group_name] . ".$column");
  1903. }
  1904. }
  1905. }
  1906. }
  1907. if (isset($query->deleted)) {
  1908. $select_query->condition("$field_base_table.deleted", (int) $query->deleted);
  1909. }
  1910. // Is there a need to sort the query by property?
  1911. $has_property_order = FALSE;
  1912. foreach ($query->order as $order) {
  1913. if ($order['type'] == 'property') {
  1914. $has_property_order = TRUE;
  1915. }
  1916. }
  1917. if ($query->propertyConditions || $has_property_order) {
  1918. if (empty($query->entityConditions['entity_type']['value'])) {
  1919. throw new EntityFieldQueryException('Property conditions and orders must have an entity type defined.');
  1920. }
  1921. $entity_type = $query->entityConditions['entity_type']['value'];
  1922. $entity_base_table = _field_sql_storage_query_join_entity($select_query, $entity_type, $field_base_table);
  1923. $query->entityConditions['entity_type']['operator'] = '=';
  1924. foreach ($query->propertyConditions as $property_condition) {
  1925. $query->addCondition($select_query, "$entity_base_table." . $property_condition['column'], $property_condition);
  1926. }
  1927. }
  1928. foreach ($query->entityConditions as $key => $condition) {
  1929. $query->addCondition($select_query, "$field_base_table.$key", $condition);
  1930. }
  1931. // Order the query.
  1932. foreach ($query->order as $order) {
  1933. if ($order['type'] == 'entity') {
  1934. $key = $order['specifier'];
  1935. $select_query->orderBy("$field_base_table.$key", $order['direction']);
  1936. }
  1937. elseif ($order['type'] == 'field') {
  1938. $specifier = $order['specifier'];
  1939. $field = $specifier['field'];
  1940. $table_alias = $table_aliases[$specifier['index']];
  1941. $sql_field = "$table_alias." . _field_sql_storage_columnname($field['field_name'], $specifier['column']);
  1942. $select_query->orderBy($sql_field, $order['direction']);
  1943. }
  1944. elseif ($order['type'] == 'property') {
  1945. $select_query->orderBy("$entity_base_table." . $order['specifier'], $order['direction']);
  1946. }
  1947. }
  1948. return $query->finishQuery($select_query, $id_key);
  1949. }
  1950. /**
  1951. * Act on creation of a new field.
  1952. *
  1953. * This hook is invoked from field_create_field() to ask the field storage
  1954. * module to save field information and prepare for storing field instances.
  1955. * If there is a problem, the field storage module should throw an exception.
  1956. *
  1957. * @param $field
  1958. * The field structure being created.
  1959. */
  1960. function hook_field_storage_create_field($field) {
  1961. $schema = _field_sql_storage_schema($field);
  1962. foreach ($schema as $name => $table) {
  1963. db_create_table($name, $table);
  1964. }
  1965. drupal_get_schema(NULL, TRUE);
  1966. }
  1967. /**
  1968. * Act on deletion of a field.
  1969. *
  1970. * This hook is invoked from field_delete_field() to ask the field storage
  1971. * module to mark all information stored in the field for deletion.
  1972. *
  1973. * @param $field
  1974. * The field being deleted.
  1975. */
  1976. function hook_field_storage_delete_field($field) {
  1977. // Mark all data associated with the field for deletion.
  1978. $field['deleted'] = 0;
  1979. $table = _field_sql_storage_tablename($field);
  1980. $revision_table = _field_sql_storage_revision_tablename($field);
  1981. db_update($table)
  1982. ->fields(array('deleted' => 1))
  1983. ->execute();
  1984. // Move the table to a unique name while the table contents are being deleted.
  1985. $field['deleted'] = 1;
  1986. $new_table = _field_sql_storage_tablename($field);
  1987. $revision_new_table = _field_sql_storage_revision_tablename($field);
  1988. db_rename_table($table, $new_table);
  1989. db_rename_table($revision_table, $revision_new_table);
  1990. drupal_get_schema(NULL, TRUE);
  1991. }
  1992. /**
  1993. * Act on deletion of a field instance.
  1994. *
  1995. * This hook is invoked from field_delete_instance() to ask the field storage
  1996. * module to mark all information stored for the field instance for deletion.
  1997. *
  1998. * @param $instance
  1999. * The instance being deleted.
  2000. */
  2001. function hook_field_storage_delete_instance($instance) {
  2002. $field = field_info_field($instance['field_name']);
  2003. $table_name = _field_sql_storage_tablename($field);
  2004. $revision_name = _field_sql_storage_revision_tablename($field);
  2005. db_update($table_name)
  2006. ->fields(array('deleted' => 1))
  2007. ->condition('entity_type', $instance['entity_type'])
  2008. ->condition('bundle', $instance['bundle'])
  2009. ->execute();
  2010. db_update($revision_name)
  2011. ->fields(array('deleted' => 1))
  2012. ->condition('entity_type', $instance['entity_type'])
  2013. ->condition('bundle', $instance['bundle'])
  2014. ->execute();
  2015. }
  2016. /**
  2017. * Act before the storage backends load field data.
  2018. *
  2019. * This hook allows modules to load data before the Field Storage API,
  2020. * optionally preventing the field storage module from doing so.
  2021. *
  2022. * This lets 3rd party modules override, mirror, shard, or otherwise store a
  2023. * subset of fields in a different way than the current storage engine.
  2024. * Possible use cases include per-bundle storage, per-combo-field storage, etc.
  2025. *
  2026. * Modules implementing this hook should load field values and add them to
  2027. * objects in $entities. Fields with no values should be added as empty
  2028. * arrays. In addition, fields loaded should be added as keys to $skip_fields.
  2029. *
  2030. * @param $entity_type
  2031. * The type of entity, such as 'node' or 'user'.
  2032. * @param $entities
  2033. * The array of entity objects to add fields to, keyed by entity ID.
  2034. * @param $age
  2035. * FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
  2036. * FIELD_LOAD_REVISION to load the version indicated by each entity.
  2037. * @param $skip_fields
  2038. * An array keyed by field IDs whose data has already been loaded and
  2039. * therefore should not be loaded again. Add a key to this array to indicate
  2040. * that your module has already loaded a field.
  2041. * @param $options
  2042. * An associative array of additional options, with the following keys:
  2043. * - field_id: The field ID that should be loaded. If unset, all fields
  2044. * should be loaded.
  2045. * - deleted: If TRUE, deleted fields should be loaded as well as
  2046. * non-deleted fields. If unset or FALSE, only non-deleted fields should be
  2047. * loaded.
  2048. */
  2049. function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_fields, $options) {
  2050. // @todo Needs function body.
  2051. }
  2052. /**
  2053. * Act before the storage backends insert field data.
  2054. *
  2055. * This hook allows modules to store data before the Field Storage API,
  2056. * optionally preventing the field storage module from doing so.
  2057. *
  2058. * @param $entity_type
  2059. * The type of $entity; for example, 'node' or 'user'.
  2060. * @param $entity
  2061. * The entity with fields to save.
  2062. * @param $skip_fields
  2063. * An array keyed by field IDs whose data has already been written and
  2064. * therefore should not be written again. The values associated with these
  2065. * keys are not specified.
  2066. * @return
  2067. * Saved field IDs are set set as keys in $skip_fields.
  2068. */
  2069. function hook_field_storage_pre_insert($entity_type, $entity, &$skip_fields) {
  2070. if ($entity_type == 'node' && $entity->status && _forum_node_check_node_type($entity)) {
  2071. $query = db_insert('forum_index')->fields(array('nid', 'title', 'tid', 'sticky', 'created', 'comment_count', 'last_comment_timestamp'));
  2072. foreach ($entity->taxonomy_forums as $language) {
  2073. foreach ($language as $delta) {
  2074. $query->values(array(
  2075. 'nid' => $entity->nid,
  2076. 'title' => $entity->title,
  2077. 'tid' => $delta['value'],
  2078. 'sticky' => $entity->sticky,
  2079. 'created' => $entity->created,
  2080. 'comment_count' => 0,
  2081. 'last_comment_timestamp' => $entity->created,
  2082. ));
  2083. }
  2084. }
  2085. $query->execute();
  2086. }
  2087. }
  2088. /**
  2089. * Act before the storage backends update field data.
  2090. *
  2091. * This hook allows modules to store data before the Field Storage API,
  2092. * optionally preventing the field storage module from doing so.
  2093. *
  2094. * @param $entity_type
  2095. * The type of $entity; for example, 'node' or 'user'.
  2096. * @param $entity
  2097. * The entity with fields to save.
  2098. * @param $skip_fields
  2099. * An array keyed by field IDs whose data has already been written and
  2100. * therefore should not be written again. The values associated with these
  2101. * keys are not specified.
  2102. * @return
  2103. * Saved field IDs are set set as keys in $skip_fields.
  2104. */
  2105. function hook_field_storage_pre_update($entity_type, $entity, &$skip_fields) {
  2106. $first_call = &drupal_static(__FUNCTION__, array());
  2107. if ($entity_type == 'node' && $entity->status && _forum_node_check_node_type($entity)) {
  2108. // We don't maintain data for old revisions, so clear all previous values
  2109. // from the table. Since this hook runs once per field, per entity, make
  2110. // sure we only wipe values once.
  2111. if (!isset($first_call[$entity->nid])) {
  2112. $first_call[$entity->nid] = FALSE;
  2113. db_delete('forum_index')->condition('nid', $entity->nid)->execute();
  2114. }
  2115. // Only save data to the table if the node is published.
  2116. if ($entity->status) {
  2117. $query = db_insert('forum_index')->fields(array('nid', 'title', 'tid', 'sticky', 'created', 'comment_count', 'last_comment_timestamp'));
  2118. foreach ($entity->taxonomy_forums as $language) {
  2119. foreach ($language as $delta) {
  2120. $query->values(array(
  2121. 'nid' => $entity->nid,
  2122. 'title' => $entity->title,
  2123. 'tid' => $delta['value'],
  2124. 'sticky' => $entity->sticky,
  2125. 'created' => $entity->created,
  2126. 'comment_count' => 0,
  2127. 'last_comment_timestamp' => $entity->created,
  2128. ));
  2129. }
  2130. }
  2131. $query->execute();
  2132. // The logic for determining last_comment_count is fairly complex, so
  2133. // call _forum_update_forum_index() too.
  2134. _forum_update_forum_index($entity->nid);
  2135. }
  2136. }
  2137. }
  2138. /**
  2139. * Returns the maximum weight for the entity components handled by the module.
  2140. *
  2141. * Field API takes care of fields and 'extra_fields'. This hook is intended for
  2142. * third-party modules adding other entity components (e.g. field_group).
  2143. *
  2144. * @param $entity_type
  2145. * The type of entity; e.g. 'node' or 'user'.
  2146. * @param $bundle
  2147. * The bundle name.
  2148. * @param $context
  2149. * The context for which the maximum weight is requested. Either 'form', or
  2150. * the name of a view mode.
  2151. * @return
  2152. * The maximum weight of the entity's components, or NULL if no components
  2153. * were found.
  2154. */
  2155. function hook_field_info_max_weight($entity_type, $bundle, $context) {
  2156. $weights = array();
  2157. foreach (my_module_entity_additions($entity_type, $bundle, $context) as $addition) {
  2158. $weights[] = $addition['weight'];
  2159. }
  2160. return $weights ? max($weights) : NULL;
  2161. }
  2162. /**
  2163. * Alters the display settings of a field before it gets displayed.
  2164. *
  2165. * Note that instead of hook_field_display_alter(), which is called for all
  2166. * fields on all entity types, hook_field_display_ENTITY_TYPE_alter() may be
  2167. * used to alter display settings for fields on a specific entity type only.
  2168. *
  2169. * This hook is called once per field per displayed entity. If the result of the
  2170. * hook involves reading from the database, it is highly recommended to
  2171. * statically cache the information.
  2172. *
  2173. * @param $display
  2174. * The display settings that will be used to display the field values, as
  2175. * found in the 'display' key of $instance definitions.
  2176. * @param $context
  2177. * An associative array containing:
  2178. * - entity_type: The entity type; e.g., 'node' or 'user'.
  2179. * - field: The field being rendered.
  2180. * - instance: The instance being rendered.
  2181. * - entity: The entity being rendered.
  2182. * - view_mode: The view mode, e.g. 'full', 'teaser'...
  2183. *
  2184. * @see hook_field_display_ENTITY_TYPE_alter()
  2185. */
  2186. function hook_field_display_alter(&$display, $context) {
  2187. // Leave field labels out of the search index.
  2188. // Note: The check against $context['entity_type'] == 'node' could be avoided
  2189. // by using hook_field_display_node_alter() instead of
  2190. // hook_field_display_alter(), resulting in less function calls when
  2191. // rendering non-node entities.
  2192. if ($context['entity_type'] == 'node' && $context['view_mode'] == 'search_index') {
  2193. $display['label'] = 'hidden';
  2194. }
  2195. }
  2196. /**
  2197. * Alters the display settings of a field on a given entity type before it gets displayed.
  2198. *
  2199. * Modules can implement hook_field_display_ENTITY_TYPE_alter() to alter display
  2200. * settings for fields on a specific entity type, rather than implementing
  2201. * hook_field_display_alter().
  2202. *
  2203. * This hook is called once per field per displayed entity. If the result of the
  2204. * hook involves reading from the database, it is highly recommended to
  2205. * statically cache the information.
  2206. *
  2207. * @param $display
  2208. * The display settings that will be used to display the field values, as
  2209. * found in the 'display' key of $instance definitions.
  2210. * @param $context
  2211. * An associative array containing:
  2212. * - entity_type: The entity type; e.g., 'node' or 'user'.
  2213. * - field: The field being rendered.
  2214. * - instance: The instance being rendered.
  2215. * - entity: The entity being rendered.
  2216. * - view_mode: The view mode, e.g. 'full', 'teaser'...
  2217. *
  2218. * @see hook_field_display_alter()
  2219. */
  2220. function hook_field_display_ENTITY_TYPE_alter(&$display, $context) {
  2221. // Leave field labels out of the search index.
  2222. if ($context['view_mode'] == 'search_index') {
  2223. $display['label'] = 'hidden';
  2224. }
  2225. }
  2226. /**
  2227. * Alters the display settings of pseudo-fields before an entity is displayed.
  2228. *
  2229. * This hook is called once per displayed entity. If the result of the hook
  2230. * involves reading from the database, it is highly recommended to statically
  2231. * cache the information.
  2232. *
  2233. * @param $displays
  2234. * An array of display settings for the pseudo-fields in the entity, keyed
  2235. * by pseudo-field names.
  2236. * @param $context
  2237. * An associative array containing:
  2238. * - entity_type: The entity type; e.g., 'node' or 'user'.
  2239. * - bundle: The bundle name.
  2240. * - view_mode: The view mode, e.g. 'full', 'teaser'...
  2241. */
  2242. function hook_field_extra_fields_display_alter(&$displays, $context) {
  2243. if ($context['entity_type'] == 'taxonomy_term' && $context['view_mode'] == 'full') {
  2244. $displays['description']['visible'] = FALSE;
  2245. }
  2246. }
  2247. /**
  2248. * Alters the widget properties of a field instance on a given entity type
  2249. * before it gets displayed.
  2250. *
  2251. * Modules can implement hook_field_widget_properties_ENTITY_TYPE_alter() to
  2252. * alter the widget properties for fields on a specific entity type, rather than
  2253. * implementing hook_field_widget_properties_alter().
  2254. *
  2255. * This hook is called once per field per displayed widget entity. If the result
  2256. * of the hook involves reading from the database, it is highly recommended to
  2257. * statically cache the information.
  2258. *
  2259. * @param $widget
  2260. * The instance's widget properties.
  2261. * @param $context
  2262. * An associative array containing:
  2263. * - entity_type: The entity type; e.g., 'node' or 'user'.
  2264. * - entity: The entity object.
  2265. * - field: The field that the widget belongs to.
  2266. * - instance: The instance of the field.
  2267. *
  2268. * @see hook_field_widget_properties_alter()
  2269. */
  2270. function hook_field_widget_properties_ENTITY_TYPE_alter(&$widget, $context) {
  2271. // Change a widget's type according to the time of day.
  2272. $field = $context['field'];
  2273. if ($field['field_name'] == 'field_foo') {
  2274. $time = date('H');
  2275. $widget['type'] = $time < 12 ? 'widget_am' : 'widget_pm';
  2276. }
  2277. }
  2278. /**
  2279. * @} End of "addtogroup field_storage".
  2280. */
  2281. /**
  2282. * @addtogroup field_crud
  2283. * @{
  2284. */
  2285. /**
  2286. * Act on a field being created.
  2287. *
  2288. * This hook is invoked from field_create_field() after the field is created, to
  2289. * allow modules to act on field creation.
  2290. *
  2291. * @param $field
  2292. * The field just created.
  2293. */
  2294. function hook_field_create_field($field) {
  2295. // @todo Needs function body.
  2296. }
  2297. /**
  2298. * Act on a field instance being created.
  2299. *
  2300. * This hook is invoked from field_create_instance() after the instance record
  2301. * is saved, so it cannot be used to modify the instance itself.
  2302. *
  2303. * @param $instance
  2304. * The instance just created.
  2305. */
  2306. function hook_field_create_instance($instance) {
  2307. // @todo Needs function body.
  2308. }
  2309. /**
  2310. * Forbid a field update from occurring.
  2311. *
  2312. * Any module may forbid any update for any reason. For example, the
  2313. * field's storage module might forbid an update if it would change
  2314. * the storage schema while data for the field exists. A field type
  2315. * module might forbid an update if it would change existing data's
  2316. * semantics, or if there are external dependencies on field settings
  2317. * that cannot be updated.
  2318. *
  2319. * To forbid the update from occurring, throw a FieldUpdateForbiddenException.
  2320. *
  2321. * @param $field
  2322. * The field as it will be post-update.
  2323. * @param $prior_field
  2324. * The field as it is pre-update.
  2325. * @param $has_data
  2326. * Whether any data already exists for this field.
  2327. */
  2328. function hook_field_update_forbid($field, $prior_field, $has_data) {
  2329. // A 'list' field stores integer keys mapped to display values. If
  2330. // the new field will have fewer values, and any data exists for the
  2331. // abandoned keys, the field will have no way to display them. So,
  2332. // forbid such an update.
  2333. if ($has_data && count($field['settings']['allowed_values']) < count($prior_field['settings']['allowed_values'])) {
  2334. // Identify the keys that will be lost.
  2335. $lost_keys = array_diff(array_keys($field['settings']['allowed_values']), array_keys($prior_field['settings']['allowed_values']));
  2336. // If any data exist for those keys, forbid the update.
  2337. $query = new EntityFieldQuery();
  2338. $found = $query
  2339. ->fieldCondition($prior_field['field_name'], 'value', $lost_keys)
  2340. ->range(0, 1)
  2341. ->execute();
  2342. if ($found) {
  2343. throw new FieldUpdateForbiddenException("Cannot update a list field not to include keys with existing data");
  2344. }
  2345. }
  2346. }
  2347. /**
  2348. * Act on a field being updated.
  2349. *
  2350. * This hook is invoked just after field is updated in field_update_field().
  2351. *
  2352. * @param $field
  2353. * The field as it is post-update.
  2354. * @param $prior_field
  2355. * The field as it was pre-update.
  2356. * @param $has_data
  2357. * Whether any data already exists for this field.
  2358. */
  2359. function hook_field_update_field($field, $prior_field, $has_data) {
  2360. // Reset the static value that keeps track of allowed values for list fields.
  2361. drupal_static_reset('list_allowed_values');
  2362. }
  2363. /**
  2364. * Act on a field being deleted.
  2365. *
  2366. * This hook is invoked just after a field is deleted by field_delete_field().
  2367. *
  2368. * @param $field
  2369. * The field just deleted.
  2370. */
  2371. function hook_field_delete_field($field) {
  2372. // @todo Needs function body.
  2373. }
  2374. /**
  2375. * Act on a field instance being updated.
  2376. *
  2377. * This hook is invoked from field_update_instance() after the instance record
  2378. * is saved, so it cannot be used by a module to modify the instance itself.
  2379. *
  2380. * @param $instance
  2381. * The instance as it is post-update.
  2382. * @param $prior_$instance
  2383. * The instance as it was pre-update.
  2384. */
  2385. function hook_field_update_instance($instance, $prior_instance) {
  2386. // @todo Needs function body.
  2387. }
  2388. /**
  2389. * Act on a field instance being deleted.
  2390. *
  2391. * This hook is invoked from field_delete_instance() after the instance is
  2392. * deleted.
  2393. *
  2394. * @param $instance
  2395. * The instance just deleted.
  2396. */
  2397. function hook_field_delete_instance($instance) {
  2398. // @todo Needs function body.
  2399. }
  2400. /**
  2401. * Act on field records being read from the database.
  2402. *
  2403. * This hook is invoked from field_read_fields() on each field being read.
  2404. *
  2405. * @param $field
  2406. * The field record just read from the database.
  2407. */
  2408. function hook_field_read_field($field) {
  2409. // @todo Needs function body.
  2410. }
  2411. /**
  2412. * Act on a field record being read from the database.
  2413. *
  2414. * This hook is invoked from field_read_instances() on each instance being read.
  2415. *
  2416. * @param $instance
  2417. * The instance record just read from the database.
  2418. */
  2419. function hook_field_read_instance($instance) {
  2420. // @todo Needs function body.
  2421. }
  2422. /**
  2423. * Acts when a field record is being purged.
  2424. *
  2425. * In field_purge_field(), after the field configuration has been
  2426. * removed from the database, the field storage module has had a chance to
  2427. * run its hook_field_storage_purge_field(), and the field info cache
  2428. * has been cleared, this hook is invoked on all modules to allow them to
  2429. * respond to the field being purged.
  2430. *
  2431. * @param $field
  2432. * The field being purged.
  2433. */
  2434. function hook_field_purge_field($field) {
  2435. db_delete('my_module_field_info')
  2436. ->condition('id', $field['id'])
  2437. ->execute();
  2438. }
  2439. /**
  2440. * Acts when a field instance is being purged.
  2441. *
  2442. * In field_purge_instance(), after the field instance has been
  2443. * removed from the database, the field storage module has had a chance to
  2444. * run its hook_field_storage_purge_instance(), and the field info cache
  2445. * has been cleared, this hook is invoked on all modules to allow them to
  2446. * respond to the field instance being purged.
  2447. *
  2448. * @param $instance
  2449. * The instance being purged.
  2450. */
  2451. function hook_field_purge_instance($instance) {
  2452. db_delete('my_module_field_instance_info')
  2453. ->condition('id', $instance['id'])
  2454. ->execute();
  2455. }
  2456. /**
  2457. * Remove field storage information when a field record is purged.
  2458. *
  2459. * Called from field_purge_field() to allow the field storage module
  2460. * to remove field information when a field is being purged.
  2461. *
  2462. * @param $field
  2463. * The field being purged.
  2464. */
  2465. function hook_field_storage_purge_field($field) {
  2466. $table_name = _field_sql_storage_tablename($field);
  2467. $revision_name = _field_sql_storage_revision_tablename($field);
  2468. db_drop_table($table_name);
  2469. db_drop_table($revision_name);
  2470. }
  2471. /**
  2472. * Remove field storage information when a field instance is purged.
  2473. *
  2474. * Called from field_purge_instance() to allow the field storage module
  2475. * to remove field instance information when a field instance is being
  2476. * purged.
  2477. *
  2478. * @param $instance
  2479. * The instance being purged.
  2480. */
  2481. function hook_field_storage_purge_field_instance($instance) {
  2482. db_delete('my_module_field_instance_info')
  2483. ->condition('id', $instance['id'])
  2484. ->execute();
  2485. }
  2486. /**
  2487. * Remove field storage information when field data is purged.
  2488. *
  2489. * Called from field_purge_data() to allow the field storage
  2490. * module to delete field data information.
  2491. *
  2492. * @param $entity_type
  2493. * The type of $entity; for example, 'node' or 'user'.
  2494. * @param $entity
  2495. * The pseudo-entity whose field data to delete.
  2496. * @param $field
  2497. * The (possibly deleted) field whose data is being purged.
  2498. * @param $instance
  2499. * The deleted field instance whose data is being purged.
  2500. */
  2501. function hook_field_storage_purge($entity_type, $entity, $field, $instance) {
  2502. list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
  2503. $table_name = _field_sql_storage_tablename($field);
  2504. $revision_name = _field_sql_storage_revision_tablename($field);
  2505. db_delete($table_name)
  2506. ->condition('entity_type', $entity_type)
  2507. ->condition('entity_id', $id)
  2508. ->execute();
  2509. db_delete($revision_name)
  2510. ->condition('entity_type', $entity_type)
  2511. ->condition('entity_id', $id)
  2512. ->execute();
  2513. }
  2514. /**
  2515. * @} End of "addtogroup field_crud".
  2516. */
  2517. /**
  2518. * Determine whether the user has access to a given field.
  2519. *
  2520. * This hook is invoked from field_access() to let modules block access to
  2521. * operations on fields. If no module returns FALSE, the operation is allowed.
  2522. *
  2523. * @param $op
  2524. * The operation to be performed. Possible values: 'edit', 'view'.
  2525. * @param $field
  2526. * The field on which the operation is to be performed.
  2527. * @param $entity_type
  2528. * The type of $entity; for example, 'node' or 'user'.
  2529. * @param $entity
  2530. * (optional) The entity for the operation.
  2531. * @param $account
  2532. * (optional) The account to check; if not given use currently logged in user.
  2533. *
  2534. * @return
  2535. * TRUE if the operation is allowed, and FALSE if the operation is denied.
  2536. */
  2537. function hook_field_access($op, $field, $entity_type, $entity, $account) {
  2538. if ($field['field_name'] == 'field_of_interest' && $op == 'edit') {
  2539. return user_access('edit field of interest', $account);
  2540. }
  2541. return TRUE;
  2542. }
  2543. /**
  2544. * @} End of "addtogroup hooks".
  2545. */