cw-image-handler

Clockwork Image Handler

The Clockwork Image Handler is a module designed to help developers easily integrate image uploading and picture taking (via the device's camera or webcam) into any web interface. This module is Promise-based, and includes a polyfill for browsers that do not support promises.

The images you want to upload, or the pictures you take are converted to a base64 string, that can be used in any frontend, or sent to any backend.

features include:

• Reading locally stored images via the File Upload API
• Image cropping
• Image resizing
• Taking pictures with the webcam. Devices supporting this feature are:
  • Chrome (desktop and mobile)
  • Firefox (desktop and mobile)
  • Edge (desktop and mobile)
  • Safari (desktop and mobile)
  • Attempting to use this feature on unsupported browsers will result in a rejected promise
• Preview the image in a target DOM node

---

Installation

npm install cw-image-handler --save

Usage

The image handler is natively an ES6 package. Once installed, it can be imported as follows:

import { ImageHandler } from 'cw-image-handler';

Using the image handler requires a new instance of it:

  const imageHandler = new ImageHandler('#target-element');
  imageHandler.uploadImage();
  ...

The image handler also comes with a UMD package, so it can be imported via a require statement or a script tag (under the global cw namespace)

API

Table of Contents

• preview
• crop
• resize
• uploadImage

preview

Generates an image and injects it into the specified target

Parameters

• opts Object The parameters required to execute the preview function
  • opts.target (string | Element | NodeList)? The target element the image will be appended into

Returns Promise A promise - The resolved promise will have a response argument containing the result of the request

crop

Crops an image (base64 string) that is passed to the function. You must include at least a width or a height or a target. Crop will always centre the image before cropping

Parameters

• opts Object The parameters required to execute the crop function
  • opts.image string A base64 string representation of an image. You can use your own base64 string, or use the base64 string returned from a uploadImage or takePicture call
  • opts.width number The final width you want the image to have. (optional, default undefined)
  • opts.height number The final height you want the image to have. (optional, default undefined)
  • opts.target (string | Element | NodeList) - A target element that will be used as the basis for resizing the image.
    • param.target can be a querySelector, a DOM element, or a DOM node list (optional, default undefined)

Returns Promise A promise - The resolved promise will have a response argument containing the result of the request

resize

Resizes an image (base64 string) that is passed to the function. You must include at least a width or a height or a target. The aspect ratio of the image will always be maintained, even if the width, height, or target establish dimensions that do not match the aspect ratio of the image. If you need a specific shape, you should run crop after resize

Parameters

• opts Object The parameters required to execute the resize function
  • opts.image string A base64 string representation of an image. You can use your own base64 string, or use the base64 string returned from a uploadImage or takePicture call
  • opts.width number The final width you want the image to have. (optional, default undefined)
  • opts.height number The final height you want the image to have. (optional, default undefined)
  • opts.target (string | Element | NodeList) - A target element that will be used as the basis for resizing the image.
    • param.target can be a querySelector, a DOM element, or a DOM node list (optional, default undefined)
  • opts.constrain string - The way in which you want to constrain the image in the target (container) element. Constrain values can be:
    • "contain". Make sure the whole image fits within the boundaries of the container. This could mean that the width or height could be smaller than the container, depending on the aspect ratio of the image
    • "fill". Fill the entire container is filled. This could mean that the width or height could overflow beyond the boundaries of the container, depending on the aspect ratio of the image (optional, default fill)

Returns Promise A promise - The resolved promise will have a response argument containing the result of the request

uploadImage

Initialises the image uploading functionality, that will kick in once a specified event has been triggered

Parameters

• params Object The parameters required to execute the uploadImage function
  • params.event string The event that will trigger the file upload dialog
  • params.target (string | Element | NodeList) The target element that will receive an event specified in the "event" param. param.target can be a querySelector, a DOM element, or a DOM node list

Examples

imageHandler.uploadImage({
 target: '#myButton',
 event: 'click'
}).then(function (response) {
 var fileSize = response.fileSize;
 var imageFormat = repsonse.fileType;
 var fileName = response.fileName;
 var base64String = response.image;
});

Returns Promise A promise - The resolved promise will have a response argument containing the result of the request