Experimental project

This is a sandbox project, which contains experimental code for developer use only.


Project Application issue: #2451223: [D7] Imager - Image viewing and editing module

This module allows users to easily view and edit full size images within Drupal. It currently works with a media gallery created from file entities and displayed with Views. I have plans to make imager into a formatter similar to Colorbox so that it can be easily configured to work anywhere images are displayed within Drupal.

This module provides four major capabilities for images:

  • View full-sized images from thumbnails - pan, zoom, full screen mode, previous/next image
  • Edit images - rotate, crop, brightness/contrast, hue/saturation/lightness
  • Save, download, email or print the edited image
  • View and edit file entity fields - currently being refactored, should be it's own sub module.

In the process of creating a Drupal media site with 30,000 images I created a program to automatically load images. If the image needed to be rotated, cropped or have the contrast changed the user had to unload the image, edit it elsewhere, and then reload the image into Drupal. Not exactly user friendly. I created this module so users can edit images directly in Drupal.

View full-sized images from thumbnails

Any drupal page (called the "Source Page") that displays images can use the imager module to view and edit full size images.

The imager module uses popups that cover a portion of the Source Page. The Source Page is never exited and remains active underneath the popups. Images can be viewed, edited, saved, deleted, and emailed without ever requiring a single page load.

The Imager Viewer provides the following capabilities:

  • User clicks on a thumbnail and the Imager Viewer pops up displaying the full image.
  • Zoom in and out using the mouse thumbwheel. The zoom is centered on the mouse cursor.
  • Pan the image by clicking and holding the left mouse button and dragging the image.
  • Select full screen mode to view the image using the entire monitor.
  • Select left or right arrow buttons to view the previous or next image from the source page.

Edit images

  • Enter crop mode and use the mouse to drag out an area to crop, click on scissors icon to execute the crop.
  • Rotate the image 90 degrees clockwise or clockwise.
  • Change the brightness and contrast
  • Change the Hue, Saturation and Lightness
  • Reset image back to original image

Save, download, email or print edited image

  • Overwrite existing image for the original file entity or create a new file entity.
  • Download image to local file system
  • Send image to clipboard
  • Open users email client with a new message to send and attach the image.
  • Open the image by itself in a new browser window for easy printing. A future enhancement would be to include the file entity fields in a very minimal html page.

View and edit file entity fields - currently broken and does not work

  • Pressing the 'I' icon (for information) pops up a dialog displaying the rendered file_entity.
  • Additional fields are included - File Owner, File ID, Geometry, File size
  • Editable fields have a pencil icon prepended to them. Clicking that icon pops up a dialog with the form widget for that field.
  • The user can edit the value for the field and press save.
  • Edited values are immediately saved using AJAX and the information popup is updated. (Future enhancement is an API to update the underlying Source Page.)

Demonstration site

To see a demo of the module go here. The first image with multiple nebulae is my favorite.
It shows off the Imagers ability to zoom and pan.

To bring up the Imager Viewer, click on a thumbnail. To close the Imager Viewer, double click anywhere in the large image.

This demo site has some very large images - The first image of the nebulae is over 30MB in size. Be patient when images are loading.

Installation and Configuration

Download and install the sandbox module.

  • Go to the imager sandbox version control page and copy the git clone command to your clipboard - Imager sandbox Version control page - Setting up repository for the first time
  • In a terminal window change directory to the modules directory you want to install the sandbox in - Ex: cd $DRUPAL_ROOT/sites/all/modules/contrib
  • Copy the git clone command into the terminal window and execute it.

Getting the icons

The icons I used were gathered from the web and then modified to fit. However in Drupal.org's eyes they aren't legal and can't be stored on drupal.org. Download the icons here and unzip them into the imager/icons directory - Ex: sites/default/modules/imager/icons. Use at your own risk.

Using with Views output

Create a View of files. The format should be 'Unformatted list' with the Show setting set to fields.

In the bottom right corner of the Views configuration screen under 'Other' configure a 'CSS class' of 'imager'.

In the Fields section display the thumbnail image as a 'Rendered: file'. Under 'Style settings' select 'Customize field HTML' and select to 'Create a CSS class'. Enter a class name of 'imager-thumbnail'.

Using with other Drupal pages

I'm working to make imager a formatter that can be selected any time images are displayed. This will allow imager to be used just about anywhere images are displayed.


Mobile Phones

The initial purpose for the Imager project was to easily view images on a 60 inch display. It needs considerable work to run on a phone or touch tablet. If you can offer advice for how to proceed please add a comment to issue 2292871.

Known Problems

This is a fully working module and is being used by a customer. It has a few glitches but they are not show stoppers. Most of the problems listed below are more related to getting it approved as my first module, not making it function correctly.

Help Wanted!

This is my first Drupal module and my first Open Source project. I've learned a lot but still have a ways to go. I would love to have a Drupal expert take a look at the project and give me ideas on how to proceed. Should the project be broken into 2 or 3 modules. Should the JavaScript image be made pluggable so it can do other edits - sharpness, tinting, etc.. What Drupal API's should I be using I'm not - especially for converting the thumbnail URI to the full size image URI. How can I cache the file_entity_edit form, it's loaded with every page but not needed unless the user wants to edit a field.

Similar Projects

Image Editor - This module sends your image to an online image editing program such as Pixlr, PicMonkey, Aviary Web Editor and many more. These online image editors can do many types of edits but they require a knowledgeable user. I didn't need the ability for a sepia filter or the ability to add pretty frames. In addition it takes several mouse clicks and time to send the image to the online editor and transfer it back to Drupal. I created the Imager module because I needed something easy and fast.

Crop - Crop allows users to define crop points for an image. It stores this information and uses an image style to apply the cropping at the time the image is created. The Crop module does not change the original image. This concept would be much harder to apply for multiple edits to an image - cropping, rotation, brightness/contrast, hue/saturation/lightness.

Future plans

  • Refactor to be an image formatter that can be selected similar to Colorbox.
  • Convert imager viewer to use theme function and template file.
  • Fix File entity viewer (or file information) popup. Shows values of fields attached to a file entity.
  • Fix File entity field editor - from the File entity viewer you can select a field and a popup allows you to edit that field.
  • Add google map - clicking on map icon brings up a google map showing markers for where this image and all other images on the current source page are located. Clicking on a marker show that image in the viewer.
  • Port to Drupal 8

Project Information