Skip navigation
Help

image.api.php

  1. drupal
    1. 7 drupal/modules/image/image.api.php

Hooks related to image styles and effects.

Functions & methods

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