field.api.php 97 KB

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