No programmer could imagine a world without variables. Neither can Cloudinary. That’s why Cloudinary now offers image transformations that support user-defined variables.
Using Cloudinary, you can already deliver transformed images with a variety of transformations, including resizing, cropping, rotating, a huge toolbox of special effects and filters, text and image overlays, and more, all of which you can deliver responsively, on-the-fly, and optimized for quick delivery via CDN.
But there are many scenarios when you may want to set up a fixed set of transformations to be applied to a variety of media assets, with one or a few variations depending on the specific image to be delivered, or on other factors that are determined at a later time.
By including user-defined variables in your transformations, you can assign different values to specific elements of the transformation when you deliver the file. For example, you could:
Apply resizing, cropping, and certain special effect transformations to all images, but use a variable for the text overlay element of the transformation, so that each image can be customized with a user’s name.
Calculate the required width of an overlay based on the evaluation of a condition, and then pass that number as a variable value to the transformation component where the overlay is applied.
Set certain elements of your Web site profile images, such as size, circular shape, quality, and more, but allow your users to select from special effects and artistic filters to apply.
Until now, goals like these could only be accomplished through a combination of transformation API and your own application code. Now you can do it all within the transformation code.
User-defined variables can be useful in conjunction with conditional transformations. You can simplify and improve the legibility of conditional transformation code by assigning different values to variables based on conditions, and then pass the relevant value to the transformation code in a separate component of a chained transformation.
You can also now apply arithmetic operators to numeric parameters or user-defined variables representing numeric parameters. To make it more interesting, your user-defined variables can even take on the value of an already known parameter value adjusted by some arithmetic expression. For example, you could assign the textwidth variable to be equal to the width of the image minus 10. Then you could create a text overlay whose width is assigned the value of the textwidth variable.
User-defined variables are even more valuable when working with named transformations, which enable you to keep your transformation code completely separate from your URL delivery code, and now enable you to keep variable values separate from your transformation code as well.
Between variables, conditional transformations, arithmetic expressions, and the function-like named transformations, you've nearly got everything you need to consider the Cloudinary transformation API a programming language in and of itself.
The basics
In general, to include a user-defined variable in your transformation, you just specify any variable name of your choice preceded by the $ sign, instead of a static parameter value, and you assign values to your variable similar to the way you would for a regular parameter.
Numbers
This is all it takes to create a basic user-defined variable for a numeric parameter:
As you can see in this simplified example, we created a user-defined variable named imgwidth, initialized it with the value 270, and then later assigned the imgwidth variable to the width parameter.
Strings
You use variables for string parameters in a similar way, but you bound the string value with ! ! characters in the assignment, for example, !MyStringValue!.
For example, have a look at this basket of strings. There are several transformations, but the value of the effect gets a different string value in each case, controlled by a variable:
Below, we show how to deliver the sepia image on the right: we assign the !sepia! string to the $effect variable, and then we set the effect transformation parameter to use whatever value is in the $effect parameter:
Text overlays
You can also use string variables for the text, or even part of the text, in a text overlay. To differentiate the variable from the rest of the text in the text overlay, there's a special variable syntax: $(variablename). Below, the text overlay has fixed text © followed by the variable name, using the syntax $(name).
cl_image_tag("canyons.jpg", :variables=>[["$name", "!Jane Smith!"]], :transformation=>[ {:width=>1080, :crop=>"scale"}, {:overlay=>{:font_family=>"MS", :font_size=>36, :text=>"%20%C2%A9%24%28name%29%20"}, :gravity=>"south_east", :x=>10, :y=>10, :background=>"#e7e5e5", :opacity=>75, :radius=>15} ])
cl_image_tag("canyons.jpg", array("variables"=>array("$name"=>"!Jane Smith!"), "transformation"=>array( array("width"=>1080, "crop"=>"scale"), array("overlay"=>array("font_family"=>"MS", "font_size"=>36, "text"=>"%20%C2%A9%24%28name%29%20"), "gravity"=>"south_east", "x"=>10, "y"=>10, "background"=>"#e7e5e5", "opacity"=>75, "radius"=>15) )))
(new ImageTag('canyons.jpg')) ->addVariable(Variable::set('name', 'Jane Smith')) ->resize(Resize::scale()->width(1080)) ->overlay( Overlay::source(Source::text(' ©$(name) ', (new TextStyle('Comic Sans MS', 36))) ->backgroundColor(Color::rgb('e7e5e5')) ->transformation((new ImageTransformation()) ->roundCorners(RoundCorners::byRadius(15)) ->adjust(Adjust::opacity(75)))) ->position((new Position()) ->gravity(Gravity::compass(Compass::southEast())) ->offsetX(10)->offsetY(10) ));
CloudinaryImage("canyons.jpg").image(variables={"$name": "!Jane Smith!"}, transformation=[ {'width': 1080, 'crop': "scale"}, {'overlay': {'font_family': "MS", 'font_size': 36, 'text': "%20%C2%A9%24%28name%29%20"}, 'gravity': "south_east", 'x': 10, 'y': 10, 'background': "#e7e5e5", 'opacity': 75, 'radius': 15} ])
cloudinary.image("canyons.jpg", {variables: [["$name", "!Jane Smith!"]], transformation: [ {width: 1080, crop: "scale"}, {overlay: {font_family: "MS", font_size: 36, text: "%20%C2%A9%24%28name%29%20"}, gravity: "south_east", x: 10, y: 10, background: "#e7e5e5", opacity: 75, radius: 15} ]})
cloudinary.url().transformation(new Transformation() .variables(variable("$name","!Jane Smith!")).chain() .width(1080).crop("scale").chain() .overlay(new TextLayer().fontFamily("MS").fontSize(36).text("%20%C2%A9%24%28name%29%20")).gravity("south_east").x(10).y(10).background("#e7e5e5").opacity(75).radius(15)).imageTag("canyons.jpg");
cloudinary.imageTag('canyons.jpg', {variables: [["$name", "!Jane Smith!"]], transformation: [ {width: 1080, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("MS").fontSize(36).text("%20%C2%A9%24%28name%29%20"), gravity: "south_east", x: 10, y: 10, background: "#e7e5e5", opacity: 75, radius: 15} ]}).toHtml();
$.cloudinary.image("canyons.jpg", {variables: [["$name", "!Jane Smith!"]], transformation: [ {width: 1080, crop: "scale"}, {overlay: new cloudinary.TextLayer().fontFamily("MS").fontSize(36).text("%20%C2%A9%24%28name%29%20"), gravity: "south_east", x: 10, y: 10, background: "#e7e5e5", opacity: 75, radius: 15} ]})
<Image publicId="canyons.jpg" variables={[["$name", "!Jane Smith!"]]}> <Transformation width="1080" crop="scale" /> <Transformation overlay={{fontFamily: "MS", fontSize: 36, text: "%20%C2%A9%24%28name%29%20"}} gravity="south_east" x="10" y="10" background="#e7e5e5" opacity="75" radius="15" /> </Image>
<cld-image publicId="canyons.jpg" :variables="[['$name', '!Jane Smith!']]"> <cld-transformation width="1080" crop="scale" /> <cld-transformation :overlay="{fontFamily: 'MS', fontSize: 36, text: '%20%C2%A9%24%28name%29%20'}" gravity="south_east" x="10" y="10" background="#e7e5e5" opacity="75" radius="15" /> </cld-image>
<cl-image public-id="canyons.jpg" variables="[['$name', '!Jane Smith!']]"> <cl-transformation width="1080" crop="scale"> </cl-transformation> <cl-transformation overlay="text:Comic%20Sans%20MS_36:%20%C2%A9%24%28name%29%20" gravity="south_east" x="10" y="10" background="#e7e5e5" opacity="75" radius="15"> </cl-transformation> </cl-image>
cloudinary.Api.UrlImgUp.Transform(new Transformation() .Width(1080).Crop("scale").Chain() .Overlay(new TextLayer().FontFamily("MS").FontSize(36).Text("%20%C2%A9%24%28name%29%20")).Gravity("south_east").X(10).Y(10).Background("#e7e5e5").Opacity(75).Radius(15)).BuildImageTag("canyons.jpg")
MediaManager.get().url().transformation(new Transformation() .variables(variable("$name","!Jane Smith!")).chain() .width(1080).crop("scale").chain() .overlay(new TextLayer().fontFamily("MS").fontSize(36).text("%20%C2%A9%24%28name%29%20")).gravity("south_east").x(10).y(10).background("#e7e5e5").opacity(75).radius(15)).generate("canyons.jpg");
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation() .setWidth(1080).setCrop("scale").chain() .setOverlay("text:Comic%20Sans%20MS_36:%20%C2%A9%24%28name%29%20").setGravity("south_east").setX(10).setY(10).setBackground("#e7e5e5").setOpacity(75).setRadius(15)).generate("canyons.jpg")!, cloudinary: cloudinary)
%20,g_south_east,x_10,y_10,b_rgb:e7e5e5,o_75,r_15/canyons.jpg "Photo with photographer name as text overlay")
Note: You can substitute user-defined variables for the value of all single-value numeric transformation parameters and some of the string transformation parameters. (See the documentation for the exact list.)
Achieving full separation
To simplify the examples above, we demonstrated assigning variable values and using the variables within transformations, together in the same delivery URL.
However, in most real-life scenarios, you will probably use variable transformations within a named transformation. A named transformation is kind of like a transformation function you can 'call' from any transformation URL. But until now, you couldn't pass any external values to the named transformation. Now with user-defined variables you can.
User-defined variables thus enable a complete separation of the transformation from the values used for delivery; a separation of the design and content logic from the technical logic.
This separation takes named transformations to a whole new level, making it significantly easier to reuse common transformations for many images, even when some specific adjustments must be made to the transformation depending on the specific image, the location where the image is displayed, or other dependencies.
For example, we've saved a transformation similar to the one used in the canyon photo above, in a named transformation called signed_photos. The named transformation sets the font type and size, the location of the text overlay, parameters that define the semi-transparent background for the text, and also includes variables for the photographer's name and for the final width of the photo to deliver:
signed_photos transformation: c_scale,w_1080/b_rgb:e7e5e5,g_south_east,l_text:Comic Sans MS_30: © $(name)%20,o_60,r_15,x_10,y_10/c_scale,w_$finalwidth
Using that named transformation, you could then deliver any image by assigning the relevant photographer name and the final width you want for the resulting image, and then specifying the named transformation and any public ID:
Getting more creative
Now that you've got the idea, let's take a look at some more cool stuff you can achieve with variables.
Adjusting image size for art direction
Suppose you have a news site that always displays the two most recent news stories in the form of large square thumbnail links of 220x220 pixels, with 20 pixels between each. Below those, older news stories are displayed with small square image links (100x100), also with 20 pixels between each photo.
You could create a named transformation that sets the quality, crop type, gravity, and other image improvements, and additionally sets both the width and height to a $size variable that will be defined externally. For example, the t_news_square named transformation might be defined as: c_fill,e_improve,g_auto:faces,z_0.7,q_auto,w_$size,h_$size,
The delivery URLs for the large image thumbnails would set the $size variable to a value of 220:
The transformation for the small images would reference the same named transformation, but with a size value of 100:
Generating various profile pictures
Imagine that users upload a profile photo to your social media app and you need to display the photo on their profile page as a portrait-oriented rectangle with rounded corners, on their homepage as a square, and as a small circular chat head on the chat page. The zooming on each photo should adjust according to the size and shape of the image. And of course you know that as your site design changes in the future, these values might change.
But regardless of the above adjustments, you always want to use the same quality, format, and face recognition settings for all photos.
With variables, you simply create a named transformation (called profile_pic in our example) with static settings for the permanent elements, and variables for the size (aspect ratio & final width) and the radius (rounding):
The profile_pic named transformation looks like this:
$zoom_$aratio_sub_0.4/
ar_$aratio,c_thumb,f_auto,g_face,q_auto,r_$rounding,w_$width,z_$zoom
This named transformation takes advantage of arithmetic operators (subtraction in this case) to achieve a zoom that changes with the aspect ratio. Thus the 1:1 images (aspect ratio = 1) end up with a closer zoom, achieving a headshot, but not too close, while portrait images (aspect ratio < 1) have a smaller zoom, and thus show more of the whole body.
The round chat head picture shown above on the right would be delivered with a value of 1.0 for $aratio, 75 for $width, and 20 for $rounding:
Going all out
Let's say you want to post the winners of a photo contest. The winning photos are delivered with a banner graphic overlay displaying the name of the winner and the place that he or she won. You want to post all photos at their original size, but both the width of the banner overlay and total width of the text (regardless of the length of the winners’ names) must be relative to the size of the photo.
For example:
You can accomplish this by creating user-defined variables for all the varying elements along with arithmetic operators and relative values. For example, we want the banner to be 90% of the photo's width and 15% of it's height. The text fits well on the banner when it's about 45% of the total image width, but the distance of the text from the bottom of the image has to be relative to the height of the resized banner. Of course we want the winner's name and where they placed, to be variables as well.
The transformation that achieves all this is somewhat complex, but that's OK. We just need to work it out once and then put it into a named transformation.
So the delivery of each winning photo is a snap!
For example, all we have to do to deliver the first place photo is set the $name variable to "Jen Fine" and the $award variable to "First":
Change is the only constant
"Change is the only constant." The phrase was coined by Greek philosophers over 2500 years ago, but it has never been truer than it is today. With the supersonic pace of Web technology development and non-stop improvements and new directions in UI design, having static values anywhere can be a hinderance.
But static values no longer need to weigh down your image transformation code. Take advantage of user-defined variables in named transformations to enable quick and flexible adjustments while maximizing code reuse and consistency across a variety of media assets.
This article demonstrated a bunch of ideas to get you started with user-defined variable transformations, but the sky's the limit. User-defined variables are supported with all Cloudinary plans, including the free one, so if you don't have a Cloudinary account yet, take a few seconds to get a free account now, and show us what you've got!
