What is your developer-dependent CMS actually costing you? Calculate your costs and get a full report

Marketplace Apps

Cloudinary

Connect your Cloudinary assets with Agility

The Cloudinary App for Agility lets editors search, select and attach Cloudinary resources — images and videos — to their content, without leaving the content form.

Cloudinary is an amazing tool to help you unleash the full potential of your online media. Optimize, transform, and combine your images to create great digital experiences. Upload and stream high quality adaptive videos from your website.

The field stores Cloudinary’s own asset metadata as JSON, so your front end can hand the public_id straight to any Cloudinary SDK and get delivery, transformation and optimisation for free.

Features

Link to Cloudinary resources directly from Agility CMS content
Browse, search and upload to your Cloudinary media library
Choose the transformation, quality, and optimized versions of the resource
Preview the selected resource, and set alt text on images
Stores the selected resource metadata in a JSON object which is returned from the Agility API

The Cloudinary Image Field

Shows a preview of the attached image alongside its Cloudinary public ID, type, size and URL. The alt text box writes to the asset’s Cloudinary metadata, so it travels with the value to your front end.

The Cloudinary Video Field

The same, for video. The attached video plays inline so an editor can confirm they picked the right one.

Browsing your Cloudinary assets

Click Browse (or Change, when something is already attached) and Cloudinary’s own Media Library opens inside Agility — search, folders, tags, upload and the transformation editor, exactly as your team knows them. The field filters the library to the right resource type, so an image field only offers images.

The Cloudinary Media Library, filtered to videos

The first time an editor opens the browser they are asked to sign in to Cloudinary, or are passed through your Cloudinary SSO. That is Cloudinary’s own authentication, and it is what scopes what they can see and upload.

Requirements

In order to use this integration, some set up is required.

Ensure you have setup Agility and Cloudinary accounts.
Install the app from the Marketplace.
Create Content Models that use the Cloudinary Image / Video custom fields.
Output the Cloudinary assets in your digital solution (i.e. website or app).

Retrieve your Cloudinary API Credentials

Log in to the Cloudinary console. Take note of the Cloud name and API Key from the main dashboard. You do not need the API Secret, and you should not paste it into the app.

Install the App

Install the app from the Settings > Apps section of Agility, then fill in its two configuration values:

Cloud Name — your Cloudinary product environment, e.g. demo
API Key — the API Key from the same dashboard

Until both are filled in, the fields show a “Cloudinary is not configured yet” notice naming what is missing.

Set Up Content Models to use Cloudinary Fields

In order to use Cloudinary fields, you need to have Content Models or Page Modules in Agility CMS that utilize these new field types.

Navigate to Models -> Content Models -> {Your Content Model}
To add an Image field, click Add Field
- Field Name: Cloudinary Image
- Field Type: Custom Field
- Custom Field Type: Cloudinary Image
To add a Video field, click Add Field
- Field Name: Cloudinary Video
- Field Type: Custom Field
- Custom Field Type: Cloudinary Video

Next, create some content using your Content Model.

Navigate to an instance of your content that is based off your Content Model
Click + New
Fill out the fields
- On the Cloudinary Image field, click Browse. Your Cloudinary media library opens — upload or choose an existing image.
- On the Cloudinary Video field, click Browse to choose a video.

Render/Output the Cloudinary Assets in your Solution

Now that you have set up the field and allowed editors to reference assets from Cloudinary, the next thing you will need to do is actually output these fields in your digital solution (i.e. website or app).

Cloudinary Field Values

The value of an Image or Video Cloudinary field is a JSON string returned from the Content Fetch or GraphQL API. Parse it to an object with JSON.parse(value) before reading it. An empty field is an empty string, so guard for that first — JSON.parse("") throws.

API Response Format

{
  "public_id": "pexels-juan-salamanca-61143_o51ss6",
  "resource_type": "image",
  "type": "upload",
  "format": "jpg",
  "version": 1623349590,
  "width": 5184,
  "height": 3456,
  "bytes": 1992294,
  "created_at": "2021-06-10T18:26:30Z",
  "secure_url": "https://res.cloudinary.com/agility-cms/image/upload/v1623349590/grass.jpg",
  "url": "http://res.cloudinary.com/agility-cms/image/upload/v1623349590/grass.jpg",
  "tags": [],

  // alt text typed in the field lives here
  "context": { "custom": { "alt": "This is a grass field" } },

  // present ONLY when a transformation was chosen. This is an ARRAY.
  "derived": [
    {
      "raw_transformation": "c_fill,h_600,w_1200",
      "secure_url": "https://res.cloudinary.com/agility-cms/image/upload/c_fill,h_600,w_1200/v1623349590/grass.jpg"
    }
  ]
}

A few things worth knowing:

public_id is the asset’s identity, and the argument every Cloudinary SDK takes. It is the only key you can rely on always being there.
derived is an array, and it is absent when the editor picked the original rather than a transformation. derived[0] is what the editor saw in the field, so it is usually what the page should render.
alt text is at context.custom.alt. It is absent rather than empty when unset, so ?? fallback works.
duration is present on videos only, in seconds.
Cloudinary’s payload varies by resource type, account features and over time — treat everything except public_id as optional.

Rendering Example

With no Cloudinary SDK at all — take the URL the editor saw:

const asset = JSON.parse(item.fields.heroImage)
const src = asset.derived?.[0]?.secure_url ?? asset.secure_url

<img
  src={src}
  alt={asset.context?.custom?.alt ?? ""}
  width={asset.width}
  height={asset.height}
/>

Or apply your own transformations from the public_id, using Cloudinary’s current React SDK:

import { Cloudinary } from "@cloudinary/url-gen"
import { AdvancedImage } from "@cloudinary/react"
import { fill } from "@cloudinary/url-gen/actions/resize"

const cld = new Cloudinary({ cloud: { cloudName: "agility-cms" } })
const asset = JSON.parse(item.fields.heroImage)

<AdvancedImage
  cldImg={cld.image(asset.public_id).resize(fill().width(1200).height(600))}
  alt={asset.context?.custom?.alt ?? ""}
/>

Video, with the browser’s own player:

const video = JSON.parse(item.fields.promoVideo)

<video
  src={video.secure_url}
  controls
  playsInline
  width={video.width}
  height={video.height}
/>

Using Cloudinary Libraries

Cloudinary builds and maintains front-end SDKs to assist with rendering images and videos, complete with handling transformations and much more.

Source Code

The app is open source (MIT) at github.com/agility/agility-cms-app-cloudinary.

On this page