197 lines
6.4 KiB
Plaintext
197 lines
6.4 KiB
Plaintext
README
|
|
------
|
|
README for the custom actions effect module.
|
|
|
|
|
|
Dependencies
|
|
------------
|
|
Hard dependencies:
|
|
- Imagecache actions.
|
|
- Image (Drupal core).
|
|
|
|
Soft dependencies/recommended modules:
|
|
- Imagemagick (preferred toolkit).
|
|
- PHP filter (Drupal core).
|
|
|
|
|
|
Which toolkit?
|
|
--------------
|
|
Personally, I prefer the imagemagick toolkit:
|
|
- It is better in anti-aliasing, try to rotate an image using both toolkits and
|
|
you will see what I mean.
|
|
- It does not execute in the PHP memory space, so is not restricted by the
|
|
memory_limit PHP setting.
|
|
- The GD toolkit will, at least on my Windows configuration, keep font files
|
|
open after a text operation, so you cannot delete, move or rename it anymore.
|
|
|
|
|
|
Installing
|
|
----------
|
|
As usual. After enabling the module you can add custom actions to images.
|
|
|
|
|
|
Custom action PHP snippets
|
|
--------------------------
|
|
Given the correct permission, the custom action effect allows you to write your
|
|
own PHP snippet that does the requested processing on the image. How it can do
|
|
so, depends on the toolkit.
|
|
|
|
For all toolkits, the snippet should return true to indicate success and false
|
|
to indicate failure.
|
|
|
|
GD
|
|
--
|
|
The GD image resource is available in $image->resource. You can call the GD
|
|
functions on this resource. This effect will query the width and height after
|
|
your processing, so you don't have to change that yourself.
|
|
|
|
Imagemagick
|
|
-----------
|
|
All real image processing is done at the end, if all effects have added their
|
|
command line arguments to the $image->ops array. So your custom action should
|
|
add the imagemagick commands and its parameters by adding new string entries to
|
|
the end of that array.
|
|
|
|
If your commands change the width or height of the resulting image, you should
|
|
record so by changing $image->info['width'] and/or $image->info['height'].
|
|
|
|
General
|
|
-------
|
|
To ease your task, this effect makes some information regarding the image being
|
|
processed available in a number of variables: $image, $image_context,
|
|
$image_style, and $image_effect_id. These variables are readily available in
|
|
your snippet.
|
|
|
|
$image is an object containing the following properties:
|
|
- source: string, the source of the image, e.g. public://photo.jpg
|
|
- info: array, example data:
|
|
- width (int) 180
|
|
- height (int) 180
|
|
- extension (string) png
|
|
- mime_type (string) image/png
|
|
- file_size (int) 4417
|
|
- toolkit: string, imagemagick or GD
|
|
- resource: resource. The GD image resource.
|
|
- ops: array. An array of strings with the ImageMagick commands.
|
|
|
|
$image_context is an associative array containing:
|
|
- effect_data: array, the data of this image effect, example data for the custom
|
|
action effect:
|
|
- php (string)
|
|
- managed_file: object|null. A managed file object containing these properties:
|
|
- fid (string) 2
|
|
- uid (string) 1
|
|
- filename (string) photo.jpg
|
|
- uri (string) public://photo.jpg
|
|
- filemime (string) image/jpeg
|
|
- filesize (string) 445751
|
|
- status (string) 1
|
|
- timestamp (string) 1327525851
|
|
- metatags Array [0]
|
|
- rdf_mapping Array [0]
|
|
- referring_entities: array|null. A nested array with (fully loaded) entities
|
|
referring to the current image. The 1st level of entries is keyed by the field
|
|
name, the 2nd by entity type, and the 3rd by entity id. Example data:
|
|
- field_photo Array [1]
|
|
- node Array [1]
|
|
- 12 Object of: stdClass
|
|
- nid (string) 12
|
|
- vid (string) 12
|
|
- type (string) page
|
|
- author ...
|
|
- timestamp ...
|
|
- ...
|
|
- entity: object|null, the 1st entity in referring_entities. This is for easy
|
|
access to the referring entity if it may be assumed that only 1 entity is
|
|
referring to the current image.
|
|
- image_field: array|null, the 1st image field in entity that is referring to
|
|
the current image. This is for easy access to the image field data if it may
|
|
be assumed that only 1 image field is referring to the current image. Example
|
|
data:
|
|
- fid (int) 2
|
|
- alt (string) ...
|
|
- title (string) ...
|
|
- ...
|
|
|
|
$image_style is an associative array containing the current image style being
|
|
processed. It ocntians a.o.:
|
|
- isid: the unique image style id
|
|
- name: machine name.
|
|
- label: Human readable name.
|
|
- effects: An array with the effects of this image style, ordered in the way
|
|
they should be applied.
|
|
|
|
$image_effect_id is an int containng the unique id of the current image effect
|
|
being applied. This can be used to look the current image effect up in the
|
|
$image_style array.
|
|
|
|
Of course there are many other possible useful globals. Think of:
|
|
- base_url
|
|
- base_path
|
|
- base_root
|
|
- is_https
|
|
- user
|
|
- language
|
|
and of course $_SERVER and $_GET.
|
|
|
|
Using these information you can access entity data as follows:
|
|
|
|
Specific case (1 entity, of known entity_type, referring to the image):
|
|
<?php
|
|
$entity_type = 'node';
|
|
$field_name = 'my_field';
|
|
$entity = $image_context['entity'];
|
|
$field = field_get_items($entity_type, $entity, $field_name);
|
|
?>
|
|
|
|
Or the more general case (not knowing the referring type, or multiple entities
|
|
that may be referring to the image):
|
|
<?php
|
|
$referring_entities = $image_context['referring_entities'];
|
|
foreach ($referring_entities as $field_name => $field_referring_entities) {
|
|
foreach ($field_referring_entities as $entity_type => $entities) {
|
|
foreach ($entities as $entity_id => $entity) {
|
|
$field = field_get_items($entity_type, $entity, $field_name);
|
|
}
|
|
}
|
|
}
|
|
?>
|
|
|
|
"Dynamic" parameters
|
|
--------------------
|
|
Thee are many requests for adding token support or allowing for dynamic
|
|
parameters in another way. However, the current image style processing does not
|
|
easily allow for this. But for these cases we have the custom action to our
|
|
rescue. It is quite easy to:
|
|
- Create you own array of parameters.
|
|
- Call the effect callback yourself
|
|
|
|
Exanple, calling the watermark/canvas overlay effect:
|
|
<?php
|
|
$data = array(
|
|
'xpos' => 'center',
|
|
'ypos' => 'center',
|
|
'alpha' => '100',
|
|
'scale' => '',
|
|
'path' => 'module://imagecache_actions/tests/black-ribbon.gif',
|
|
);
|
|
return canvasactions_file2canvas_effect($image, $data);
|
|
?>
|
|
|
|
Or, to be on the safe side with effect info altering:
|
|
<?php
|
|
$definition = image_effect_definition_load('canvasactions_file2canvas');
|
|
$callback = $definition['effect callback'];
|
|
if (function_exists($callback)) {
|
|
$data = array(
|
|
'xpos' => 'center',
|
|
'ypos' => 'center',
|
|
'alpha' => '100',
|
|
'scale' => '',
|
|
'path' => 'module://imagecache_actions/tests/black-ribbon.gif',
|
|
);
|
|
return $callback($image, $data);
|
|
}
|
|
return FALSE;
|
|
?>
|