Edit this page

CloudinaryImage Field

Stores an Object in the model.

Displayed as an image upload field in the Admin UI.

Automatically manages images stored in Cloudinary, including uploading, resizing and deleting.

See the Cloudinary configuration documentation for details on how to set up Cloudinary in KeystoneJS.

Example

{ type: Types.CloudinaryImage }

Options

generateFilename function; default: random filename

Method to generate a public_id in Cloudinary for the uploaded file. Gets passed the file data, the attempt number and the callback to call with the filename. Note: Cloudinary supported file extensions will automatically be removed from returned filename.

  • See keystone-storage-namefunctions for additional filename generators, including content hash filename and original filename. See its source for more information on how to write your own.
{ type: Types.CloudinaryImage, generateFilename: function(file, attemptNumber, callback) {
    var originalname = file.originalname;
    var filenameWithoutExtension = originalname.substring(0, originalname.lastIndexOf('.'));
    var timestamp = new Date().getTime();
    return `${filenameWithoutExtension}-${timestamp}`;
  },
}

whenExists string; default: 'overwrite'

Specifies what to do when the file exists already. Can be one of 'retry', 'error' or 'overwrite'.

{ type: Types.CloudinaryImage, whenExists: 'retry' }

retryAttempts number; default: 3

If whenExists is set to 'retry', how many times keystone should try to generate a unique filename before returning an error

{ type: Types.CloudinaryImage, whenExists: 'retry', retryAttempts: 5 }

folder String

Specifies a custom folder/prefix for the Cloudinary image public_id when cloudinary folders is set to true.

{ type: Types.CloudinaryImage, folder: 'path/to/image' }

Note: If you want Cloudinary to automatically create folders when the cloudinary folders option is set to true, make sure you enable "Auto-create folders" in your Cloudinary account "Upload Settings".

autoCleanup Boolean

When true, changes Keystone's default behavior from remove (which only removes the Cloudinary image from the database) to delete (which removes the image from both the database and Cloudinary storage). Additionally, this option replaces an existing image (if one already exists) during upload. This only occurs on calls to updateItem

{ type: Types.CloudinaryImage, autoCleanup : true }

select Boolean

When true, a select field is displayed with a list of images currently available in Cloudinary storage. Only images with IDs that begin with the selectPrefix will be displayed when the selectPrefix is specified. Otherwise, images with IDs that begin with the folder will be displayed. If neither selectPrefix nor folder are configured, then only images with IDs that begin with [{prefix}]/{list.path}/{field.path}/ will be displayed.

{ type: Types.CloudinaryImage, select : true }

selectPrefix String specifies the the prefix of the images that will be available for selection when select option is true.

{ type: Types.CloudinaryImage, select: true, selectPrefix: 'path/to/images' }

Schema

public_id String

version Number

signature String

format String

resource_type String

url String

width Number

height Number

secure_url String

Virtuals

exists Boolean - whether there is a stored image

Special paths

{path}_upload

When a file is provided to the updateHandler, it will be uploaded to cloudinary and the details will be stored in the field.

Underscore methods

src(options) String - returns the url of the image, accepts all options cloudinary supports

tag(options) String - returns an <img> tag

scale(width, height, options) String - scales the image to fit the exact width and height, retaining aspect ratio

fit(width, height, options) String - scales the image to fit within the specified width and height, retaining aspect ratio

lfit(width, height, options) String - scales the image to fit within the specified width and height, retaining aspect ratio (without exceeding the original dimensions)

limit(width, height, options) String - scales the image (down only) to fit within the specified width and height, retaining aspect ratio

fill(width, height, options) String - scales the image to fill the specified width and height

crop(width, height, options) String - crops the image to fill the specified width and height

pad(width, height, options) String - pads the image to fill the specified width and height

lpad(width, height, options) String - pads the image to fill the specified width and height (without exceeding the original dimensions)

thumbnail(width, height, options) String - crops the image to fill the specified width and height

In all methods, options is an optional Object. See Cloudinary's Transformation Documentation for more information on the supported options and transformations.

Note: Remember that if you are uploading images to a CloudinaryImage field using an HTML form, you need to specify enctype="multipart/form-data" in your form tag.