image.api.php

  1. 7.x drupal/modules/image/image.api.php
  2. 8.x drupal/core/modules/image/image.api.php

Hooks related to image styles and effects.

Functions

Namesort descending Description
hook_image_default_styles Provide module-based image styles for reuse throughout Drupal.
hook_image_effect_info Define information about image effects provided by a module.
hook_image_effect_info_alter Alter the information provided in hook_image_effect_info().
hook_image_styles_alter Modify any image styles provided by other modules or the user.
hook_image_style_delete Respond to image style deletion.
hook_image_style_flush Respond to image style flushing.
hook_image_style_save Respond to image style updating.

File

drupal/modules/image/image.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Hooks related to image styles and effects.
  5. */
  6. /**
  7. * @addtogroup hooks
  8. * @{
  9. */
  10. /**
  11. * Define information about image effects provided by a module.
  12. *
  13. * This hook enables modules to define image manipulation effects for use with
  14. * an image style.
  15. *
  16. * @return
  17. * An array of image effects. This array is keyed on the machine-readable
  18. * effect name. Each effect is defined as an associative array containing the
  19. * following items:
  20. * - "label": The human-readable name of the effect.
  21. * - "effect callback": The function to call to perform this image effect.
  22. * - "dimensions passthrough": (optional) Set this item if the effect doesn't
  23. * change the dimensions of the image.
  24. * - "dimensions callback": (optional) The function to call to transform
  25. * dimensions for this effect.
  26. * - "help": (optional) A brief description of the effect that will be shown
  27. * when adding or configuring this image effect.
  28. * - "form callback": (optional) The name of a function that will return a
  29. * $form array providing a configuration form for this image effect.
  30. * - "summary theme": (optional) The name of a theme function that will output
  31. * a summary of this image effect's configuration.
  32. *
  33. * @see hook_image_effect_info_alter()
  34. */
  35. function hook_image_effect_info() {
  36. $effects = array();
  37. $effects['mymodule_resize'] = array(
  38. 'label' => t('Resize'),
  39. 'help' => t('Resize an image to an exact set of dimensions, ignoring aspect ratio.'),
  40. 'effect callback' => 'mymodule_resize_effect',
  41. 'dimensions callback' => 'mymodule_resize_dimensions',
  42. 'form callback' => 'mymodule_resize_form',
  43. 'summary theme' => 'mymodule_resize_summary',
  44. );
  45. return $effects;
  46. }
  47. /**
  48. * Alter the information provided in hook_image_effect_info().
  49. *
  50. * @param $effects
  51. * The array of image effects, keyed on the machine-readable effect name.
  52. *
  53. * @see hook_image_effect_info()
  54. */
  55. function hook_image_effect_info_alter(&$effects) {
  56. // Override the Image module's crop effect with more options.
  57. $effects['image_crop']['effect callback'] = 'mymodule_crop_effect';
  58. $effects['image_crop']['dimensions callback'] = 'mymodule_crop_dimensions';
  59. $effects['image_crop']['form callback'] = 'mymodule_crop_form';
  60. }
  61. /**
  62. * Respond to image style updating.
  63. *
  64. * This hook enables modules to update settings that might be affected by
  65. * changes to an image. For example, updating a module specific variable to
  66. * reflect a change in the image style's name.
  67. *
  68. * @param $style
  69. * The image style array that is being updated.
  70. */
  71. function hook_image_style_save($style) {
  72. // If a module defines an image style and that style is renamed by the user
  73. // the module should update any references to that style.
  74. if (isset($style['old_name']) && $style['old_name'] == variable_get('mymodule_image_style', '')) {
  75. variable_set('mymodule_image_style', $style['name']);
  76. }
  77. }
  78. /**
  79. * Respond to image style deletion.
  80. *
  81. * This hook enables modules to update settings when a image style is being
  82. * deleted. If a style is deleted, a replacement name may be specified in
  83. * $style['name'] and the style being deleted will be specified in
  84. * $style['old_name'].
  85. *
  86. * @param $style
  87. * The image style array that being deleted.
  88. */
  89. function hook_image_style_delete($style) {
  90. // Administrators can choose an optional replacement style when deleting.
  91. // Update the modules style variable accordingly.
  92. if (isset($style['old_name']) && $style['old_name'] == variable_get('mymodule_image_style', '')) {
  93. variable_set('mymodule_image_style', $style['name']);
  94. }
  95. }
  96. /**
  97. * Respond to image style flushing.
  98. *
  99. * This hook enables modules to take effect when a style is being flushed (all
  100. * images are being deleted from the server and regenerated). Any
  101. * module-specific caches that contain information related to the style should
  102. * be cleared using this hook. This hook is called whenever a style is updated,
  103. * deleted, or any effect associated with the style is update or deleted.
  104. *
  105. * @param $style
  106. * The image style array that is being flushed.
  107. */
  108. function hook_image_style_flush($style) {
  109. // Empty cached data that contains information about the style.
  110. cache_clear_all('*', 'cache_mymodule', TRUE);
  111. }
  112. /**
  113. * Modify any image styles provided by other modules or the user.
  114. *
  115. * This hook allows modules to modify, add, or remove image styles. This may
  116. * be useful to modify default styles provided by other modules or enforce
  117. * that a specific effect is always enabled on a style. Note that modifications
  118. * to these styles may negatively affect the user experience, such as if an
  119. * effect is added to a style through this hook, the user may attempt to remove
  120. * the effect but it will be immediately be re-added.
  121. *
  122. * The best use of this hook is usually to modify default styles, which are not
  123. * editable by the user until they are overridden, so such interface
  124. * contradictions will not occur. This hook can target default (or user) styles
  125. * by checking the $style['storage'] property.
  126. *
  127. * If your module needs to provide a new style (rather than modify an existing
  128. * one) use hook_image_default_styles() instead.
  129. *
  130. * @see hook_image_default_styles()
  131. */
  132. function hook_image_styles_alter(&$styles) {
  133. // Check that we only affect a default style.
  134. if ($styles['thumbnail']['storage'] == IMAGE_STORAGE_DEFAULT) {
  135. // Add an additional effect to the thumbnail style.
  136. $styles['thumbnail']['effects'][] = array(
  137. 'name' => 'image_desaturate',
  138. 'data' => array(),
  139. 'weight' => 1,
  140. 'effect callback' => 'image_desaturate_effect',
  141. );
  142. }
  143. }
  144. /**
  145. * Provide module-based image styles for reuse throughout Drupal.
  146. *
  147. * This hook allows your module to provide image styles. This may be useful if
  148. * you require images to fit within exact dimensions. Note that you should
  149. * attempt to re-use the default styles provided by Image module whenever
  150. * possible, rather than creating image styles that are specific to your module.
  151. * Image provides the styles "thumbnail", "medium", and "large".
  152. *
  153. * You may use this hook to more easily manage your site's changes by moving
  154. * existing image styles from the database to a custom module. Note however that
  155. * moving image styles to code instead storing them in the database has a
  156. * negligible effect on performance, since custom image styles are loaded
  157. * from the database all at once. Even if all styles are pulled from modules,
  158. * Image module will still perform the same queries to check the database for
  159. * any custom styles.
  160. *
  161. * @return
  162. * An array of image styles, keyed by the style name.
  163. * @see image_image_default_styles()
  164. */
  165. function hook_image_default_styles() {
  166. $styles = array();
  167. $styles['mymodule_preview'] = array(
  168. 'label' => 'My module preview',
  169. 'effects' => array(
  170. array(
  171. 'name' => 'image_scale',
  172. 'data' => array('width' => 400, 'height' => 400, 'upscale' => 1),
  173. 'weight' => 0,
  174. ),
  175. array(
  176. 'name' => 'image_desaturate',
  177. 'data' => array(),
  178. 'weight' => 1,
  179. ),
  180. ),
  181. );
  182. return $styles;
  183. }
  184. /**
  185. * @} End of "addtogroup hooks".
  186. */