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