You are here

README.txt in ImageCache Actions 7

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;
?>

File

customactions/README.txt
View source
  1. README
  2. ------
  3. README for the custom actions effect module.
  4. Dependencies
  5. ------------
  6. Hard dependencies:
  7. - Imagecache actions.
  8. - Image (Drupal core).
  9. Soft dependencies/recommended modules:
  10. - Imagemagick (preferred toolkit).
  11. - PHP filter (Drupal core).
  12. Which toolkit?
  13. --------------
  14. Personally, I prefer the imagemagick toolkit:
  15. - It is better in anti-aliasing, try to rotate an image using both toolkits and
  16. you will see what I mean.
  17. - It does not execute in the PHP memory space, so is not restricted by the
  18. memory_limit PHP setting.
  19. - The GD toolkit will, at least on my Windows configuration, keep font files
  20. open after a text operation, so you cannot delete, move or rename it anymore.
  21. Installing
  22. ----------
  23. As usual. After enabling the module you can add custom actions to images.
  24. Custom action PHP snippets
  25. --------------------------
  26. Given the correct permission, the custom action effect allows you to write your
  27. own PHP snippet that does the requested processing on the image. How it can do
  28. so, depends on the toolkit.
  29. For all toolkits, the snippet should return true to indicate success and false
  30. to indicate failure.
  31. GD
  32. --
  33. The GD image resource is available in $image->resource. You can call the GD
  34. functions on this resource. This effect will query the width and height after
  35. your processing, so you don't have to change that yourself.
  36. Imagemagick
  37. -----------
  38. All real image processing is done at the end, if all effects have added their
  39. command line arguments to the $image->ops array. So your custom action should
  40. add the imagemagick commands and its parameters by adding new string entries to
  41. the end of that array.
  42. If your commands change the width or height of the resulting image, you should
  43. record so by changing $image->info['width'] and/or $image->info['height'].
  44. General
  45. -------
  46. To ease your task, this effect makes some information regarding the image being
  47. processed available in a number of variables: $image, $image_context,
  48. $image_style, and $image_effect_id. These variables are readily available in
  49. your snippet.
  50. $image is an object containing the following properties:
  51. - source: string, the source of the image, e.g. public://photo.jpg
  52. - info: array, example data:
  53. - width (int) 180
  54. - height (int) 180
  55. - extension (string) png
  56. - mime_type (string) image/png
  57. - file_size (int) 4417
  58. - toolkit: string, imagemagick or GD
  59. - resource: resource. The GD image resource.
  60. - ops: array. An array of strings with the ImageMagick commands.
  61. $image_context is an associative array containing:
  62. - effect_data: array, the data of this image effect, example data for the custom
  63. action effect:
  64. - php (string)
  65. - managed_file: object|null. A managed file object containing these properties:
  66. - fid (string) 2
  67. - uid (string) 1
  68. - filename (string) photo.jpg
  69. - uri (string) public://photo.jpg
  70. - filemime (string) image/jpeg
  71. - filesize (string) 445751
  72. - status (string) 1
  73. - timestamp (string) 1327525851
  74. - metatags Array [0]
  75. - rdf_mapping Array [0]
  76. - referring_entities: array|null. A nested array with (fully loaded) entities
  77. referring to the current image. The 1st level of entries is keyed by the field
  78. name, the 2nd by entity type, and the 3rd by entity id. Example data:
  79. - field_photo Array [1]
  80. - node Array [1]
  81. - 12 Object of: stdClass
  82. - nid (string) 12
  83. - vid (string) 12
  84. - type (string) page
  85. - author ...
  86. - timestamp ...
  87. - ...
  88. - entity: object|null, the 1st entity in referring_entities. This is for easy
  89. access to the referring entity if it may be assumed that only 1 entity is
  90. referring to the current image.
  91. - image_field: array|null, the 1st image field in entity that is referring to
  92. the current image. This is for easy access to the image field data if it may
  93. be assumed that only 1 image field is referring to the current image. Example
  94. data:
  95. - fid (int) 2
  96. - alt (string) ...
  97. - title (string) ...
  98. - ...
  99. $image_style is an associative array containing the current image style being
  100. processed. It ocntians a.o.:
  101. - isid: the unique image style id
  102. - name: machine name.
  103. - label: Human readable name.
  104. - effects: An array with the effects of this image style, ordered in the way
  105. they should be applied.
  106. $image_effect_id is an int containng the unique id of the current image effect
  107. being applied. This can be used to look the current image effect up in the
  108. $image_style array.
  109. Of course there are many other possible useful globals. Think of:
  110. - base_url
  111. - base_path
  112. - base_root
  113. - is_https
  114. - user
  115. - language
  116. and of course $_SERVER and $_GET.
  117. Using these information you can access entity data as follows:
  118. Specific case (1 entity, of known entity_type, referring to the image):
  119. $entity_type = 'node';
  120. $field_name = 'my_field';
  121. $entity = $image_context['entity'];
  122. $field = field_get_items($entity_type, $entity, $field_name);
  123. ?>
  124. Or the more general case (not knowing the referring type, or multiple entities
  125. that may be referring to the image):
  126. $referring_entities = $image_context['referring_entities'];
  127. foreach ($referring_entities as $field_name => $field_referring_entities) {
  128. foreach ($field_referring_entities as $entity_type => $entities) {
  129. foreach ($entities as $entity_id => $entity) {
  130. $field = field_get_items($entity_type, $entity, $field_name);
  131. }
  132. }
  133. }
  134. ?>
  135. "Dynamic" parameters
  136. --------------------
  137. Thee are many requests for adding token support or allowing for dynamic
  138. parameters in another way. However, the current image style processing does not
  139. easily allow for this. But for these cases we have the custom action to our
  140. rescue. It is quite easy to:
  141. - Create you own array of parameters.
  142. - Call the effect callback yourself
  143. Exanple, calling the watermark/canvas overlay effect:
  144. $data = array(
  145. 'xpos' => 'center',
  146. 'ypos' => 'center',
  147. 'alpha' => '100',
  148. 'scale' => '',
  149. 'path' => 'module://imagecache_actions/tests/black-ribbon.gif',
  150. );
  151. return canvasactions_file2canvas_effect($image, $data);
  152. ?>
  153. Or, to be on the safe side with effect info altering:
  154. $definition = image_effect_definition_load('canvasactions_file2canvas');
  155. $callback = $definition['effect callback'];
  156. if (function_exists($callback)) {
  157. $data = array(
  158. 'xpos' => 'center',
  159. 'ypos' => 'center',
  160. 'alpha' => '100',
  161. 'scale' => '',
  162. 'path' => 'module://imagecache_actions/tests/black-ribbon.gif',
  163. );
  164. return $callback($image, $data);
  165. }
  166. return FALSE;
  167. ?>