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