The Builder Cloudinary plugin provides an easy-to-use component block with access to your Cloudinary images.
Follow the steps below to enable Cloudinary in your Builder Space.
To create an API key in Cloudinary:
- Go to your Cloudinary dashboard.
- Go to Settings.
- Click API Keys.
- Click + Generate New API Key.
- A confirmation code is sent to the account email. Use this confirmation code to approve the new API key.
- Optionally, rename the API key from Untitled to something more descriptive, ilke Builder API Key.
To enable the Cloudinary plugin in Builder:
- Go to Plugins in Builder.
- Find the Cloudinary tile, either by scrolling or using the search bar.
- Toggle on the Cloudinary plugin.
Next, you'll need to create a custom component. This component is the block that can be added to individual content entries within Builder.
Below is an example of a Cloudinary component using the React Gen 2 SDK.
import { RegisteredComponent } from "@builder.io/sdk-react";
const CustomCloudinaryComponent = ({ cloudinaryOptions }: any) => {
const url = cloudinaryOptions?.url;
const alt = cloudinaryOptions?.context?.custom?.alt || "Cloudinary Asset";
const component = url ? (
<img src={url} alt={alt} />
) : (
<img
src="https://placehold.co/600x400?text=Cloudinary+Asset+Placeholder"
alt="Cloudinary placeholder"
/>
);
return component;
};
export const cloudinaryImageConfig: RegisteredComponent = {
component: CustomCloudinaryComponent, // Your custom Cloudinary Component
name: "Cloudinary Assets",
inputs: [{ name: "cloudinaryOptions", type: "cloudinaryImageEditor" }],
};The code above does the following:
- Imports
RegisteredComponentfrom the appropriate Builder SDK. - Creates a custom component called
CustomCloudinaryComponent. This component displays the selected Cloudinary image, or a placeholder image if none has been selected. - Creates a registered component configuration object.
Make sure to register your component, as is appropriate for your framework and Builder SDK generation. For more details, visit Register custom components.
For the React Gen 2 SDK, include your custom components as an attribute on the returned component of your content entry.
return (
<Content
content={content}
model="page"
apiKey={BUILDER_API_KEY}
customComponents={[cloudinaryImageConfig]}
/>
);Once your component is registered, go to a content entry within your Builder Space and do the following:
- Under the Insert menu, go to Custom Components and drag your Cloudinary Block to your content entry.
- Click Set Credentials.
- Add your API key and Cloud name. This configuration step only needs to happen one time.
- Click the Choose Image button.
- Select your image from Cloudinary.
Below is an example of the payload delivered by Cloudinary to your custom component. All data is stored within the key cloudinaryOptions.
{
"public_id": "sample",
"resource_type": "image",
"type": "upload",
"format": "jpg",
"version": 1511474034,
"url": "http://res.cloudinary.com/demo/image/upload/v1511474034/sample.jpg",
"secure_url": "https://res.cloudinary.com/demo/image/upload/v1511474034/sample.jpg",
"width": 864,
"height": 576,
"bytes": 120257,
"duration": null,
"tags": [],
"metadata": [],
"created_at": "2023-02-08T08:38:51Z",
"derived": [
{
"url": "http://res.cloudinary.com/demo/image/upload/c_scale,e_grayscale,f_auto,q_auto,w_100/v1511474034/sample.jpg",
"secure_url": "https://res.cloudinary.com/demo/image/upload/c_scale,e_grayscale,f_auto,q_auto,w_100/v1511474034/sample.jpg"
}
],
"access_mode": "public",
"access_control": [],
"created_by": {
"type": "user",
"id": "abc123def456ghiabc123def456ghi"
},
"uploaded_by": {
"type": "user",
"id": "xyz789efg456qrsxyz789efg456qrs"
},
"id": "ede59e6d3befdc65a8adc2f381c0f96f",
"folder_id": "abcs432p8xyz0q532wqpoirnk0138",
"context": {
"custom": {
"alt": "Text that describes the image",
"caption": "Caption or title that is presented along with the image"
}
}
}For more details on custom components, visit Register custom components. For more details on plugins, visit Intro to plugins.