Project

General

Profile

Paste
Download (7.04 KB) Statistics
| Branch: | Revision:

root / drupal7 / modules / image / image.api.php @ db2d93dd

1
<?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
  */