Editor Documentation

Jump to section

  1. Requirements
  2. Installation
  3. License Registration
  4. Image Hopper Field
  5. Browser Support
  6. Translations
  7. Developers

Requirements

  1. Image Hopper 1.1.0+

The plugin cannot be used without Image Hopper Core (view the Core requirements).

Installation

After completing the checkout process for the Ultimate + Editor license you will be redirected to the Purchase Confirmation page. Here you will be able to download Image Hopper Core and the Editor plugin zip files. Both plugins need to be installed and activated to use the Editor functionality.

A screenshot of the Purchase Confirmation page with the product download links highlighted.
After purchase, download the two plugin zip packages for installation on your WordPress website

Follow the Core installation process, and then repeat the steps to install and activate the Editor add-on too.

License Registration

The Editor add-on shares the Image Hopper Core license key, and you can register both plugins using the same license key in one convenient location.

Image Hopper Field

An example of the image editor.
The Image Editor has an impressive set of features

The Editor add-on extends the capabilities of the Image Hopper field available in Core. You can find the Image Hopper field in the Advanced Fields section of the Gravity Forms Editor.

With the Editor functionality enabled, users will be able to edit their images in the following ways:

  1. Crop, rotate, flip, and zoom
  2. Apply image filters such as Monochrome or Sepia
  3. Adjust brightness, contrast, exposure, and saturation
  4. Annotate or markup the image
  5. Resize
The Gravity Forms Editor page with the Image Hopper field added to the form.
Start using the image editor feature by including an Image Hopper field in your Gravity Forms form and ticking the Enable Image Editor setting.

Field Settings

The following settings are included in the Image Hopper field when the Editor add-on is installed and activated on your WordPress website:

Crop to Dimensions

Included as an option in the Downscale Image setting, when enabled the image will be automatically cropped to Downscale Image dimensions, provided that the image provided is larger than those dimensions to begin with. While there will be a quality loss, you can enable the Upscale to Crop Dimensions setting to force uniformity in all the uploaded images.

This feature can be enabled with or without the Image Editor. When the Image Editor is disabled, the image will be automatically cropped to the set dimensions, using the middle of the image as the crop centre point. If the Image Editor is enabled, the user can adjust the positioning of the image in relation to the fixed crop area to change the focal point.

For a seamless user experience, but still allowing control of the image crop area, enable the Image Editor and leave the Open Editor on Upload setting disabled. Image Hopper will automatically apply your crop to any images, but allow the editor to be manually opened to adjust the crop focal point.

Enable Image Editor

When enabled, it converts the Image Hopper field from a smart uploader to a smart image editor.

Open Editor on Upload

When enabled, for every image uploaded the Image Editor will automatically open so the user can make appropriate adjustments. If it’s disabled, a user can click the edit icon on an image to manually open the editor.

Showing Image Hopper with the Editor icon available for users to select.
Users can click the “pencil” icon to open the Image Editor

Features

You have total control over what image editing capabilities you want to give users, and this allows Image Hopper to be easily used for a variety of use cases. We’ve even included a number of helpful presets to get you started fast (but you don’t have to use them and can pick and choose the features you need).

Available Presets:

  • Essentials – enables the crop and rotate features.
  • Color – enables the filter and color correction features
  • Annotate – enables the draw, arrow, and text markup features, as well as crop and manual rotation.
  • All – enable every image editing feature

Available Features

Below is the full list of features that you can enable or disable in the Image Editor:

  • Crop – crop an image to a specific size
    • Rotate Left – rotates the image 90 degrees counterclockwise.
    • Rotate Right – rotates the image 90 degrees clockwise.
    • Flip Horizontal – flips the image 180 degrees on the X axis.
    • Flip Vertical – flips the image 180 degrees on the Y axis.
    • Manual Rotation – allows the image rotation to be adjusted up to -45 degrees or +45 degrees.
    • Display Size – shows the current size the image will be cropped to
  • Filter – apply a photo effect to the image using one of the 13 available filters
    • Pastel
    • Chrome
    • Fade
    • Warm
    • Cold
    • Mono
    • Mono Noir
    • Mono Wash
    • Mono Stark
    • Sepia
    • Sepia Blues
    • Sepia Rust
    • Sepia Color
  • Color – control the brightness, contrast, exposure, and saturation
  • Markup – annotate, draw, and write notes on the image
    • Draw – set the color and line thickness and start free-hand drawing.
    • Arrow – make it a single / double arrow, or turn off the arrow heads to add a line instead. The color and line thickness is also controllable.
    • Text – add notes to the image, with options to change the font style (serif, sans-serif, or monospaced), text size, and color.
    • Square – draw a solid or stroked square onto the image, controlling the color and line thickness.
    • Circle – draw a solid or stroked circle onto the image, controlling the color and line thickness.
  • Resize – allows the user to downscale or upscale the image dimensions at will. The image is locked to the aspect ratio by default, but the user can disable it.

Default Editor View

When the Image Editor is first open, this determines which of the primary setting tabs will be displayed by default: Crop, Filter, Color, Markup, or Resize. If a primary setting is disabled in Features it will be automatically hidden as an option.

If you use a preset, this setting is automatically adjusted to the relevant option (but you can override it):

  • Essentials -> Crop
  • Color -> Filter
  • Annotate -> Markup
  • All -> Crop

Default Filter

Automatically apply a filter to the uploaded image. This setting can be used with or without the Image Editor enabled.

Upscale to Crop Dimensions

Located in the Advanced tab/section of the Image Hopper field, this setting is only available if you’ve also enabled Crop to Dimensions. When toggled on, it ensures the uploaded image will get scaled up to the width and height specified in Downscale Images when it has smaller dimensions. While this does ensure all uploaded images have uniformity, this will save an image that has a noticeable drop in image quality.

The Image Hopper field in the Form Editor with the Advanced tab selected.

Browser Support

The Image Hopper field makes use of a progressive enhancement strategy to support a wide range of modern browsers, offering more features to modern browsers who support it. For example, older browsers may not support the dropping of directories, pasting files, or external links. While browsers that do support these features will have them automatically enabled.

The following browsers and devices can successfully use Image Hopper for uploads:

Desktop

  • Firefox
  • Chrome
  • Safari
  • Edge
  • Internet Explorer 11

Mobile

  • Safari iOS (version 9 and higher)
  • Chrome Android
  • Firefox Android

Translations

Image Hopper ships with the following translations out of the box:

  • English (en_US)
  • French (fr_FR)
  • Spanish (es_ES)
  • German (de_DE)

If you’d like your language to be supported natively, please get in touch and let us know. The more demand for a specific language the greater the chance of it getting added.

Self-Translation

You can use the free Loco Translate plugin to write your own translations specifically for Image Hopper Editor. The Gravity PDF team have an excellent guide which shows you how to go about translating a plugin. Just substitute Gravity PDF for Image Hopper Editor when completing the steps.

If you prefer to generate a PO/MO file for your chosen language using a tool like POEdit, you can find the POT language file at /languages/image-hopper-editor.pot in the plugin zip file.

Developers

Below is useful actions/filters that can be used to change how Image Hopper functions:

Javascript Actions/Filters

image_hopper_filepond_config(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, fileInput)

This filter allows you to manipulate the FilePond instance configuration, and when the Image Editor is enabled config.imageEditEditor is made available and holds the Doka instance, allowing you to adjust its properties on demand.

config {object} – The FilePond configuration object, which accepts all the properties listed in the FilePond instance documentation. The config.imageEditEditor object will accept any of the properties listed in the Doka instance documentation.
FilePond {object}The FilePond public API object.
$form {object} – A jQuery object matching the encompassing Gravity Forms <form> element
currentPage {int} – The current page number of the Gravity Forms form.
formId {int} – The Gravity Forms form ID
fieldId {int} – The Image Hopper field ID
entryId {int} – The Gravity Forms entry ID (if one exists)
files {array} – A list of the files already uploaded at the time of initialisation
fileInput {object} – The <input type="file"> object currently being Image Hopper’d

Examples

Add multiple aspect ratio options which the user can select in the Crop primary setting:

gform.addFilter('image_hopper_filepond_config', function(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
   config.imageEditEditor.setOptions( {
      cropAspectRatioOptions: [
        {
            label: 'Free',
            value: null
        },
        {
            label: 'Portrait',
            value: 1.5
        },
        {
            label: 'Square',
            value: '1:1'
        },
        {
            label: 'Landscape',
            value: 0.75
        }
    ]
   } )
   return config
} )

Add a “stickers” feature, which allows emojis, custom text, or images to be overlaid onto the image:

gform.addFilter('image_hopper_filepond_config', function(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
   config.imageEditEditor.setOptions( {
    utils: ['crop', 'filter', 'color', 'markup', 'resize', 'sticker'],
    stickers: [
        '👍',
        '😀',
        '🥳',
        '❤',
        '🙃',
    ]
   } )
   return config
} )

Usage

While you could create a separate JavaScript file and enqueue it when your desired Gravity Forms form is displayed, it’s far easier to add an HTML field to your form and wrap the filter in <script type="text/javascript"></script> tags.

A Gravity Forms HTML Block field with the custom filter code included
Easily add the filter to your website via an HTML field

Additional Info

You can manipulate any of the properties listed in the Doka documentation, but we recommended you steer clear of the following (so you don’t break the core functionality):

  • element
  • id
  • src
  • allowAutoDestroy
  • outputData
  • outputFile

It’s also worth noting that Doka is integrated directly into FilePond, so many of FilePond’s settings override the Doka settings.

PHP Actions/Filters

image_hopper_editor_file_path( $file_path, $url )

This filter allows you to adjust the reference URL for an image when updating an existing image that has been edited. It’s most useful when you change the Gravity Forms upload directory using the gform_upload_path filter.

$file_path {string} – The path of the image stored on the server
$url {string} – The original URL of the image stored on the server

Examples

Use an alternate upload directory for the images:

/* Change the upload path */
add_filter( "gform_upload_path", function( $path_info, $form_id ) {
	$path_info["path"] = WP_CONTENT_DIR . "/uploads/Images/" . $form_id . "/";
	$path_info["url"]  = WP_CONTENT_URL . "/uploads/Images/" . $form_id . "/";

	return $path_info;
}, 10, 2 );

/* Ensure the new upload path is used when deleting files */
add_filter( 'gform_file_path_pre_delete_file', function( $file_path, $url ) {
	$wp_upload_dir = wp_upload_dir();
	$file_path     = str_replace( $wp_upload_dir['baseurl'], $wp_upload_dir['basedir'], $file_path );

	return $file_path;
}, 1, 2 );

/* Ensure the new upload path is used when overriding files when using the editor */
add_filter( 'image_hopper_editor_physical_file_path', function( $file_path, $url ) {
	$wp_upload_dir = wp_upload_dir();
	$file_path     = str_replace( $wp_upload_dir['baseurl'], $wp_upload_dir['basedir'], $file_path );

	return $file_path;
}, 10, 2 );

Usage

The standard place to include the snippet is in your active theme’s functions.php file.