Core Documentation

Jump to section

  1. Requirements
  2. Installation
  3. License Registration
  4. Image Hopper Field
  5. Merge Tags
  6. Notification Attachments
  7. Browser Support
  8. Add-ons Support
  9. Slim Image Cropper
  10. Translations
  11. Developers

Requirements

  1. PHP 5.6+
  2. WordPress 5.2.0+
  3. Gravity Forms 2.4.0+

The plugin cannot be used without Gravity Forms.

Installation

After completing the checkout process you will be redirected to the Purchase Confirmation page. Here you will be able to download your PDF invoice, access the plugin support page, copy your license key, and download the plugin zip file.

Image shows the Purchase Confirmation page, where users can download the plugin zip file.
The Purchase Confirmation page. The area highlighted red is where you can download the plugin zip file.

Once you’ve downloaded the zip, login to your WordPress Admin Area and navigate to Plugins -> Add New. When the page loads, click the Upload Plugin button at the top of the page (right next to the page title) to bring up the file selector. Choose the zip file you just downloaded and click Install Now. If the installation is a success, click the Activate Plugin button to enable Image Hopper on your website.

Image shows the WordPress "Add Plugins" screen with the Upload Plugin functionality selected.
Select the zip and click the Install Now button.
Image shows the screen shows after successfully installing the plugin on WordPress.
After the plugin is successfully installed, click the Activate Plugin button

Note: if your browser auto-extracts zip file, and you’re having trouble uploading the file to your website, you may need to temporarily deactivate this feature and download the plugin again.

License Registration

It’s important to activate your license key on your site(s) so you can receive WordPress one-click updates and support by the Image Hopper team.

To do this, after activating the plugin you can click the Settings link shown next to the Deactivate link on the Image Hopper item shown in the plugins list. You can also reach the settings page by navigating to Forms -> Settings -> Image Hopper.

Copy your license key to the License Key setting and click the Update Settings button to save. If successful you will see a tick icon show up next to the input area. If there is a problem a cross will be shown.

The Image Hopper Settings page where you can save your License Key.
A green tick next to the License Key field means

You can deactivate and remove your license key from the site by deleting it from the License Key setting and saving.

Image Hopper Field

An image showing how the Image Hopper looks to the user filling out the Gravity Forms form.
How the user sees the Image Hopper field when filling out a form

The Image Hopper field is available under the Advanced section of the Gravity Forms Editor. The field is very versatile and you can:

  1. Allow multiple images to be uploaded in a single Image Hopper field
  2. Add multiple Image Hopper fields to a single Gravity Form
  3. Automatically downscale images (reducing the image size) to fit within the width/height you set
  4. Set a maximum number of images that can be uploaded per Image Hopper field
  5. Set the maximum file size allowed to be uploaded to the server (calculated using the downscaled image size and not the original file size)
  6. Set the image output quality for JPG/JPEG images
  7. Automatically rotate images based on their EXIF data. This is great for mobile and tablet uploads, where devices are usually rotated when taking photos.
  8. Include Image Hopper fields on any page in your form
  9. Use Image Hopper with the Save and Continue feature
  10. Automatically include uploaded images as attachments in your Notifications
  11. Upload all common image file types, including JPG/JPEG, GIF, and PNG
Start using the image upload feature by including an Image Hopper field in your Gravity Forms form

Field Settings

The Image Hopper field supports many of Gravity Forms common field settings, including:

  • Field Label
  • Description
  • Rule: Required
  • Field Label Visibility
  • Description Placement
  • Custom Validation Message
  • Custom CSS Class
  • Admin Field Label
  • Visibility
  • Conditional Logic

For information about these common field types please refer to Gravity Forms documentation.

Custom Field Settings

The following additional settings are available for the Image Hopper field:

Downscale Images

With modern phones and cameras producing higher quality images, users are more likely to be uploading huge images to your server and this can easily become a storage, bandwidth, and backup nightmare. While the standard File Upload field in Gravity Forms allows you to set a Maximum File Size, it puts the burden on the user to optimize the images prior to upload. With Image Hopper, all you need to do is set a conservative downscale Width/Height and the image(s) will be automatically processed in the user’s browser before uploading. It’s a win-win for everyone involved!

If a user uploads an image that is already below your downscale size it will not be scaled up.

Maximum Number of Files

You can specify the maximum number of images that can be uploaded to an Image Hopper field. You can leave this setting blank for unlimited files, just bear in mind the actual number of files permitted may be limited by your server’s specifications and configuration.

Output Quality

Optimize images even more by setting the output quality of JPG/JPEG images. Set to 0 for the worse possible quality, and 100 for the best. If you don’t set a value, Image Hopper will default to 90.

Maximum File Size

Specify the maximum file size in megabytes allowed for each of the files. When used in conjunction with the Downscale Images setting, the file size is checked after the image has been downscaled.

Viewing Entry

After the form has been submitted, the Image Hopper field will display the number of uploaded images in the Entry List and the actual images on the Entry Details page.

The Gravity Forms Entry List screen showing how the Image Hopper column displays.
If multiple images are uploaded you’ll see the number of images saved. Single uploads will include a direct link to the file.
The Gravity Forms Entry Details screen showing how the Image Hopper field displays.
Entry Details: the uploaded images are shown on the screen.

Save and Continue

Image Hopper is fully supported when using Gravity Forms Save and Continue feature. Provided the images are successfully uploaded during the initial form submission (and don’t show an error), they will be automatically rehydrated when the recovery link is used.

Note: if the recovery link is used and an image is then deleted without generating a new recovery link, it can put the Image Hopper into an invalid state if the original recovery link is accessed a second time. The image showing an error can either be ignored (the invalid image will be discarded during form submission) or deleted to proceed.

An image showing how the Image Hopper field can get into an invalid state if the Save and Continue feature is used incorrectly.
An invalid image state can occur if the Save and Continue feature is used incorrectly.

Export Entries

When the Image Hopper field is included in a CSV export of your entries it will include the full URL to each image, separated by a space/comma/space ( , ). If only a single image is uploaded the separator will not be included.

Merge Tags

Image Hopper has its own individual field tags, but also integrates nicely with Gravity Forms {all_fields} merge tag.

Field Tag

Usage

{Field Name:2:modifier}

Without any modifiers, and when in an HTML-output context, all images will be displayed on screen using <img /> tags. If in a text-output context the output is the same as using the :url modifier.

Modifiers

  • :url
    Denotes that the output should show the plain-text secure/masked URL(s) of the uploaded images, separated by a comma (,)
  • :raw
    Denotes that the output should show the plain-text direct URL(s) of the uploaded images, separated by a comma (,)

All Fields Tag

When using the {all_fields} tag (or its variants) in an HTML-output context, all images will be displayed on screen using <img /> tags. If in a text-output context the output is the same as using the :url modifier.

Notification Attachments

The Gravity Forms Notifications settings, with the Attachments option in view.
Enable the Notification ‘Attachments’ setting to include Image Hopper as email attachments

You can choose to include the uploaded Image Hopper images as attachments in your Notification emails. To enable, go to your Notification setting and enable the Attach uploaded files to notification option.

Pay attention to how many Image Hopper fields you have in the form and what the Maximum File Size setting is for each field. Many email providers have a conservative attachment size limit, so it’s best to keep the total size under 10MB. As an example, if you had two Image Hopper fields in your form, you’ll want to set the Maximum File Size to 5MB for each field so you don’t exceed 10MB total.

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

Assistive Technology

  • Safari with VoiceOver
  • Chrome with VoiceOver
  • Chrome with NVDA
  • Firefox with NVDA

Add-ons Support

Gravity Forms has a rich first- and third-party add-on ecosystem, and ensuring you can use Image Hopper with all your favourite add-ons is a high priority for us. We’ve support for the following:

Gravity PDF

Gravity PDF is a popular PDF-generation plugin for Gravity Forms. Image Hopper solves all the technical challenges Gravity PDF faces when displaying images in PDFs. The two main issues are:

  1. Images can be automatically downscaled in the browser before upload, which means reasonable image sizes Gravity PDF is working with (keeping the PDFs under 10MB if sending as an attachment, or 20MB otherwise is recommended).
  2. Images are auto-rotated by reading the EXIF data before upload. That means no heavy server-side image rendering and no rotated images in the PDFs.

Since those challenges are resolved, the images uploaded via an Image Hopper field are automatically displayed in the Core (free templates) and Universal PDFs. This is usually without risk of PDF generation issues (but depends on your hosting provider), but if you find there are problems use a smaller downscale width/height and set a smaller Maximum File Size Limit.

Unlike its predecessor, Image Hopper does not wrap the images displayed in the PDFs in an anchor tag, and users won’t be able to click the images to open up the full-sized version in their browser.

An image of a PDF that includes Image Hopper, generated using Gravity PDF.
Image Hopper automatically displaying images in the Zadani PDF template.

Pro Tip: if you limit the Image Hopper field to 1 image you can use the {Field Name:2:raw} merge tag in the Background Image PDF setting (available in the Template section of some PDF templates) to use the uploaded image as a full-page background. Cool, eh!?

Previewer Add-on

The Gravity PDF Previewer add-on allows generated documents to be viewed on screen before the form is submitted. Image Hopper is fully supported, either on the same page as the Previewer or on an earlier page in the form.

An image showing the Gravity PDF Previewer add-on with the Image Hopper field.
Gravity PDF Previewer field in action with Image Hopper

Gravity Flow

Gravity Flow is THE way to build automated business processes into your WordPress website, and Image Hopper natively supports the User Input and Approval Steps (both the WordPress Admin Inbox and the [gravityflow page="inbox"] shortcode methods). The merge tags will also be processed and used anywhere Gravity Flow accepts them, including Notifications and the Outgoing Webhook step.

The Gravity Flow inbox currently displaying the Approval Step with an Image Hopper field
Gravity Flow Approval Step with Image Hopper field
The Gravity Flow inbox currently displaying the User Inputl Step with an Image Hopper field
Gravity Flow User Input Step with Image Hopper field

GravityView

GravityView is a powerful page builder that uses Gravity Forms data for the source. Image Hopper is fully supported in the Listing / Table Views, and on the Multiple Entries, Single Entry, and Edit Entry View pages.

GravityView's Table view with an Image Hopper field displayed
Image Hopper included in the Multiple Entries Table View
GravityView's Edit Entry admin view with the Image Hopper field included.
Adding the Image Hopper field to the Edit Entry View
GravityView's Edit Entry view with an Image Hopper field displayed.
Rendering Image Hopper on the Edit Entry View

Caution: GravityView has a long-running bug which prevents the correct functionality of upload fields (including Image Hopper) when a validation error occurs on the Edit Entry View. There is currently no workaround.

WooCommerce Gravity Forms Product Add-on

The Woo Gravity Forms add-on (for short) connects WooCommerce and Gravity Forms together to build advanced product configuration forms. The Image Cropper plugins works seamlessly when used in this combination, including when a user might go back and edit the Product/Gravity Form.

An image of the Image Hopper field when used with the WooCommerce Gravity Forms Product add-on.
Image Hopper displayed in a Woo Gravity Forms Product
An image of the WooCommerce cart that shows how the Image Hopper field is displayed when used with the WooCommerce Gravity Forms Product add-on.
The Cart after adding a Woo Gravity Forms product with an Image Hopper field.

Gravity Perks Nested Forms

Nested Forms is a powerful Perk created by Gravity Wiz which allows you to build repeater functionality into Gravity Forms (by linking a parent form to a nested child form) and Image Hopper is fully supported when used in the nested form.

An image of the Image Hopper field when used with the Gravity Perks Nested Forms plugin.
Using the alternate Nested Forms dialog box with Image Hopper

Note: Nested Forms has two different dialog boxes that can be used to display child forms. During testing we found the default layout had issues scrolling after adding images. A workaround is to switch to the alternate dialog box which functions perfectly. To use the alternate dialog box add the following code snippet to your active theme’s functions.php file (or a similar location):

add_filter( 'gpnf_use_jquery_ui', '__return_true' );

Slim Image Cropper

The Slim Image Cropper for Gravity Forms plugin has been discontinued by the original developer and Image Hopper is the recommended replacement. Image Hopper has many of the same features as Slim Image Cropper (and even surpasses it in many areas), but it doesn’t have 100% feature parity (at this stage).

Feature Parity

This is a list of features both Slim Image Cropper and Image Hopper support:

  • Responsive and beautifully animated
  • Correctly handles device orientation
  • Very fast
  • Easy to Configure
  • High Quality User Experience
  • Drag and Drop
  • Resize images automatically
  • User can adjust the crop and rotation (Ultimate + Editor edition only)
  • Define max file upload size
  • Define JPEG compression ratio
  • Define required input image type
  • Customize output image size
  • Supports touch interaction on mobile devices
  • Validate images before upload
  • Multiple fields per form

Not Supported

This is a list of features Slim Image Cropper supports, but Image Hopper doesn’t:

  • Post Image field type
  • Minimum image dimensions
  • Image quality warning (like the minimum image dimensions, but still allows the image to be uploaded)
  • Set image ratio – you can set the image size with the ‘crop’ option enabled to achieve similar results (Ultimate + Editor edition only)
  • Force output format (either JPEG or PNG)

New Features

This is a list of features Image Hopper supports, but Slim Image Cropper doesn’t:

  • Upload multiple images to the same upload field (you are not limited to one image per field)
  • Attach uploaded images to Notification emails
  • Deep integration with the Gravity Forms ecosystem, including native support for popular add-ons like Gravity PDF, GravityView, Gravity Flow, Gravity Perks Nested Forms, and the WooCommerce Gravity Forms add-on.
  • Intuitive Settings – Image Hopper takes a convention over configuration approach to using the plugin, meaning it is easier to setup and configure.

Migrate from Slim Image Cropper

These are the steps you should take after you deactivate Slim Image Cropper and install and activate Image Hopper:

  1. In your admin area, navigate to the Gravity Forms editor for a form that contains a Slim Image Cropper field
  2. Add a new Image Hopper field below each of your Slim Image Cropper fields, and configure accordingly. Because Image Hopper can support multiple images per field, you may be able to consolidate multiple Slim Image Cropper fields.
  3. Leave your existing Slim Image Cropper fields in the form (Image Hopper will automatically hide the Slim and Slim Post fields from your end user, but still display the images in your admin area).
  4. Save your Gravity Form
  5. Test that you can now upload images using Image Hopper and that you don’t see the Slim Image Cropper fields while filling out the form.
  6. Verify you can see the Image Hopper images on the Entry Details page for your newly-submitted test entry
  7. Verify that you can still see the Slim Image Cropper images on the Entry Details page for older entries
  8. Repeat step 1-7 for each of your Gravity Forms

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. 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 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.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. FilePond is the library used to handle the image uploading functionality, so being able to change how it works based on your needs can be very useful.

config {object} – The FilePond configuration object, which accepts all the properties listed in the FilePond 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

Disable instant upload on image selection/drop:

gform.addFilter('image_hopper_filepond_config', function(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
   config.instantUpload = false
   return config
} )

Insert additional images at the start of the list (instead of after), but limit this behaviour to a specific form and field:

gform.addFilter('image_hopper_filepond_config', function(config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
   if(formId == 2 && fieldId == 6) {
      config.itemInsertLocation = "before"
   }
   return config
} )

Automatically add an image watermark to the bottom-right of every uploaded images:

gform.addFilter('image_hopper_filepond_config', function (config, FilePond, $form, currentPage, formId, fieldId, entryId, files, inputField) {
  FilePond.setOptions({
    fileMetadataObject: {

      // The `markup` property is how we define our watermark
      markup: [
        [
          'image',
          {
            right: '10px',
            bottom: '10px',
            width: '150px',
            height: '150px',
            src: 'https://example.com/wp-content/uploads/2020/12/watermark.png', // set full URL to image uploaded to your media library. Use a transparent PNG for transparency
            fit: 'contain'
          }
        ],
      ]
    }
  })
  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 FilePond documentation, but we recommended you steer clear of the following (so you don’t break the core functionality, or use unsupported features):

  • name
  • status
  • element
  • server
  • captureMethod
  • allowReorder