Cloudinary Template Filter

Pipit Cloudinary is a Perch template filter that enables you to easily fetch your images to Cloudinary on the fly. Cloudinary also gives you the option to manipulate your images with dynamic URLs.





define('CLOUDINARY_CLOUDNAME', 'your-cloud-name');

You also need to enable template filters in your config:




The filter by default does not rewrite your image URLs if you set your Perch production environment to development:


This is because Cloudinary requires publicly accessible URL to fetch the images from.


To use the cloudinary filter add the attribute filter="cloudinary" to your tag:

<perch:content id="image" type="image" filter="cloudinary">

To add image manipulation and compression options use the opts attribute:

<perch:content id="image" type="image" filter="cloudinary" opts="w_800,h_600,f_auto">

You can also use it on external links (in a regular text field for example) by adding the external attribute.

<perch:content id="image_url" type="text" filter="cloudinary" external>

Adding the external attribute tells the filter not to add your site domain.

Image Manipulation

You can do a lot with Cloudinary that it is best to refer to their documentation for the full options. Here are some common ones:

Option Description Examples
w_ Width w_800
h_ Height h_400
q_ Quality q_80, q_auto, q_auto:good
f_ Format f_auto
c_ Crop c_fill, c_fit, c_limit, c_crop

Using f_auto tells Cloudinary to serve the best file format for the browser. So on Chrome, for example, it will server a JPG as a WebP since the format is supported in Chrome and has a smaller file size.

Using c_limit allows you to limit the image dimensions. For instance, w_1000,c_limit scales the image down if it is larger than 1000 in width, but will not scale it up if it is already smaller.

Using c_fill fills the image in a given dimensions similar to CSS’s object-fit: cover and background-size: cover. Example usage: w_800,h_600,c_fill.

On the other hand c_fit is like CSS’s object-fit: contain and background-size: contain as it resizes the image to take up as much space as possible in a given dimension while maintaining the aspect ratio and keeping the whole image visible. Example usage: w_800,h_600,c_fit.

Helpful References: