first import

sites/all/modules/imagecache_actions/customactions/README.txt

@@ -0,0 +1,146 @@
+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 the font file
+  open after a text operation, so you cannot delete, move or rename it anymore.
+- This module does a better job with Imagemagick (see below).
+
+
+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 associative array containing:
+- 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);
+    }
+  }
+}
+?>