You are here

README.txt in ImageCache Actions 8

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 2 variables: $image and $image_context. 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) ...
   - ...

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

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 2 variables: $image and $image_context. These variables
  48. are readily available in your snippet.
  49. $image is an object containing the following properties:
  50. - source: string, the source of the image, e.g. public://photo.jpg
  51. - info: array, example data:
  52. - width (int) 180
  53. - height (int) 180
  54. - extension (string) png
  55. - mime_type (string) image/png
  56. - file_size (int) 4417
  57. - toolkit: string, imagemagick or GD
  58. - resource: resource. The GD image resource.
  59. - ops: array. An array of strings with the ImageMagick commands.
  60. $image_context is an associative array containing:
  61. - effect_data: array, the data of this image effect, example data for the custom
  62. action effect:
  63. - php (string)
  64. - managed_file: object|null. A managed file object containing these properties:
  65. - fid (string) 2
  66. - uid (string) 1
  67. - filename (string) photo.jpg
  68. - uri (string) public://photo.jpg
  69. - filemime (string) image/jpeg
  70. - filesize (string) 445751
  71. - status (string) 1
  72. - timestamp (string) 1327525851
  73. - metatags Array [0]
  74. - rdf_mapping Array [0]
  75. - referring_entities: array|null. A nested array with (fully loaded) entities
  76. referring to the current image. The 1st level of entries is keyed by the field
  77. name, the 2nd by entity type, and the 3rd by entity id. Example data:
  78. - field_photo Array [1]
  79. - node Array [1]
  80. - 12 Object of: stdClass
  81. - nid (string) 12
  82. - vid (string) 12
  83. - type (string) page
  84. - author ...
  85. - timestamp ...
  86. - ...
  87. - entity: object|null, the 1st entity in referring_entities. This is for easy
  88. access to the referring entity if it may be assumed that only 1 entity is
  89. referring to the current image.
  90. - image_field: array|null, the 1st image field in entity that is referring to
  91. the current image. This is for easy access to the image field data if it may
  92. be assumed that only 1 image field is referring to the current image. Example
  93. data:
  94. - fid (int) 2
  95. - alt (string) ...
  96. - title (string) ...
  97. - ...
  98. Of course there are many other possible useful globals. Think of:
  99. - base_url
  100. - base_path
  101. - base_root
  102. - is_https
  103. - user
  104. - language
  105. and of course $_SERVER and $_GET.
  106. Using these information you can access entity data as follows:
  107. Specific case (1 entity, of known entity_type, referring to the image):
  108. $entity_type = 'node';
  109. $field_name = 'my_field';
  110. $entity = $image_context['entity'];
  111. $field = field_get_items($entity_type, $entity, $field_name);
  112. ?>
  113. Or the more general case (not knowing the referring type, or multiple entities
  114. that may be referring to the image):
  115. $referring_entities = $image_context['referring_entities'];
  116. foreach ($referring_entities as $field_name => $field_referring_entities) {
  117. foreach ($field_referring_entities as $entity_type => $entities) {
  118. foreach ($entities as $entity_id => $entity) {
  119. $field = field_get_items($entity_type, $entity, $field_name);
  120. }
  121. }
  122. }
  123. ?>