Upload widget

Overview

Cloudinary is a cloud-based service that allows uploading images (or any other files) to the cloud, from any source and at any scale. Cloudinary can dynamically process and manipulate uploaded images to match your graphic design and deliver these highly optimized to your users via a fast CDN.

Cloudinary's powerful image uploading APIs support uploads at scale from your server-side applications or directly from your users' browsers or mobile devices.

Cloudinary's upload widget

Cloudinary's upload widget is an interactive, feature rich, simple to integrate method to add Cloudinary support to your website. The widget, requiring just a couple lines of code to integrate, eliminates the need to develop in-house interactive image upload capabilities.

Cloudinary's widget includes a complete graphical interface. With it, a visitor can upload files from any of three sources: local (file system), remote (URL), or by snapping an image directly from the computer or mobile device camera.

The widget supports a drag & drop functionality, interactive cropping, upload progress indication, and thumbnail previews. The widget also monitors and handles uploading errors.

The widget supports unsigned uploading directly from the browser to Cloudinary storage, without involving your servers in the process. The widget sends Javascript callbacks on successful uploads, so you can integrate the upload process back into your existing image pipeline. You can configure Cloudinary to send server-side callbacks as well.

Advanced users can also use the upload widget with signed uploads for a more secure process.

Once uploaded, images can be resized, cropped and manipulated by Cloudinary on-the-fly so they can be embedded as needed in your website or mobile app.

Cloudinary's upload widget requires pure Javascript to integrate and is easy to use with any web development framework. Advanced features are available using jQuery.

Quick example

To use Cloudinary's image upload widget in your site with unsigned uploads, simply include the the remote Javascript file of the widget (delivered optimized via a fast CDN) and specify the cloud_name of your Cloudinary account and an upload preset name when calling the method that activates the widget.

The following sample code binds to the click event of a link in a web page. The cloudinary.openUploadWidget method is called to programmatically open the upload widget when the opener link is clicked.

When the upload completes, the widget automatically closes and a Javascript callback function is called with a list of uploaded images as the result parameter.

<a href="#" id="upload_widget_opener">Upload multiple images</a>

<script src="//widget.cloudinary.com/global/all.js" type="text/javascript"></script>  
          
<script type="text/javascript">  
  document.getElementById("upload_widget_opener").addEventListener("click", function() {

    cloudinary.openUploadWidget({ cloud_name: 'demo', upload_preset: 'a5vxnzbp'}, 
      function(error, result) { console.log(error, result) });

  }, false);
</script>

You can try out a live example by clicking on the following button:

The example above uses standard Javascript code to open the widget and allows multiple image uploading. The following example uses jQuery to convert an existing link to a widget opener button. It uploads to the specified folder and enables interactive cropping of a single uploaded image.

<script src="//widget.cloudinary.com/global/all.js" type="text/javascript"></script>  
          
<script type="text/javascript">  
  $('#upload_widget_opener').cloudinary_upload_widget(
    { cloud_name: 'demo', upload_preset: 'a5vxnzbp', 
      cropping: 'server', folder: 'user_photos' },
    function(error, result) { console.log(error, result) });
</script>

You can try out another live example by clicking on the following button:

How to setup and implement the upload widget

For most needs, you can implement the upload widget for 'unsigned' uploads. Using unsigned uploads with your widget makes it quick and simple for you to provide a UI where users can upload content to your site.

Signed uploads require a bit more setup and coding to implement, but provide a more secure upload process when required.

Unsigned uploads

Unsigned uploads are somewhat less secure than signed uploads. For example, it is possible for a customer to inspect your client-side HTML code to find your cloud name and preset, and use that information to upload unwanted files to your account. For this reason, unsigned uploads have some protective limitations. For example, existing images cannot be overwritten. The options you set in the unsigned preset can also limit the size or type of files that users can upload to your account.

To setup and implement the upload widget for unsigned uploads:

1. Include the cloudinary widget javascript file in your web page:

   
   

   HTTP URL:

   http://widget.cloudinary.com/global/all.js

   HTTPS URL:

   https://widget.cloudinary.com/global/all.js

   Protocol agnostic URL:

   //widget.cloudinary.com/global/all.js

   For example:

   <script src="//widget.cloudinary.com/global/all.js" type="text/javascript">  
   </script>
   

2. Optional. Include jQuery if you want to show thumbnails of uploaded images, creating hidden fields with the identifiers of the uploaded images, or bind to events. The following example is a Javascript include line of the jQuery library.

   <script src='//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js'></script>
   

3. Optional. Set your cloud name globally. If you include multiple widgets in your web page, you can use the setCloudName method to instruct all widgets on the page to upload to your Cloudinary account. Alternatively, you can set the cloud name as a parameter of each widget creation call.
4. Create an unsigned upload preset. In the Management console Upload Settings, create a new, unsigned upload preset. This preset serves as a form of security override, allowing client-side unsigned uploads. You supply the preset name in your widget creation call.

   
   

   If you've never created an unsigned preset, you must first select to enable unsigned uploading. When you do this, an empty upload preset is automatically created for you. Alternatively, you can create an unsigned upload preset using the Admin API.

   
   

   You can optionally edit the preset to modify its name or apply any of the available preset options, such as applying incoming transformations, to control the size or type of image users can upload using your widget, or to automatically generate certain eager transformations on all uploaded images. For details, see Upload Presets.

5. Implement your widget. Use one of the widget creation methods described below. When you call the method, you specify the 'upload_preset' that you created in the previous step, your 'cloud_name' (if you did not set it globally), and any additional widget options you want to apply.

   
   

   For example, in the demo example earlier on this page, the method call includes the 'cropping' option, which enables users to define cropping coordinates, and the 'folder' option, which uploads all images from the widget to a specified folder.

Signed uploads

Instead of providing an upload preset name, you initialize the widget for signed uploads with the public API key and an upload signature that is generated either when the page is loaded or when the upload request is submitted.

To setup and implement the upload widget for signed uploads:

1. Follow steps 1-3 above.
2. Optional. Create a signed upload preset. When you use the upload widget for signed uploads, an upload preset is not necessary. But you can optionally create a signed preset if you want to define incoming or eager transformations on the uploaded image. Define the preset as described in Upload Presets and supply the preset name in the 'upload_preset' option when you call the widget creation method.
3. Select string or function as the upload_signature type and prepare the required code.
   • String:
     • Requires your page to connect to the web server on page load to generate the signature.
     • Requires that all parameters required for signing are known at page load time. If user-input will affect the parameters, for example, if you are using the widget's interactive cropping option, then you must use the function option.
     • The signature string you provide is valid for one hour from the timestamp used in the signature. If a user keeps the page open for a long time, the signature string may expire.

     For details on generating the signature string, see Creating API authentication signatures.

   • Function:
     • Requires you to create a function to generate the signature.
     • The function runs when the upload request is submitted, therefore, the timestamp does not risk expiring if the user keeps the page open.
     • The function receives the final parameters of the upload, including any parameters impacted by user interaction.

     Sample function:

     The following is an example of a function that uses a server-side endpoint to generate the signature.

   <script type="text/javascript">
     var generateSignature = function(callback, params_to_sign){
       $.ajax({
         url     : “http://www.my-domain.com/my_generate_signature %>",
         type    : "GET",
         dataType: "text",
         data    : { data: params_to_sign},
         complete: function() {console.log("complete")},
         success : function(signature, textStatus, xhr) { callback(signature); },
         error   : function(xhr, status, error) { console.log(xhr, status, error); }
       });
     }
   </script>
   

4. Implement your widget. Use one of the widget creation methods described below. When you call the method, you specify your account 'api_key', your 'cloud_name' (if you did not set it globally), the 'upload_signature' string or function, the 'upload_signature_timestamp' (for string signatures only), and any additional widget options you want to apply.
   
   

   For example, the following method creates the upload-widget and calls the signature function shown in the previous step.

    <script type="text/javascript">  
      $('#upload_widget_opener').cloudinary_upload_widget(
        { cloud_name: cloud_name, api_key: api_key,
          cropping: 'server', upload_signature: generateSignature},

        function(error, result) { console.log(error, result) });
    </script>

API methods

The following Javascript method are publicly available for calling from your Website's code after including Cloudinary's upload widget Javascript file.

cloudinary.setCloudName(name)

Globally set the cloud name for all widget method calls.

For example:

<script src="http://widget.cloudinary.com/global/all.js" type="text/javascript">
</script>
<script>
  cloudinary.setCloudName('cadf1nga');
</script>

cloudinary.openUploadWidget(options, result_callback)

Programmatically create a widget frame and open it. options is a map of all widget options, including both client side settings and upload API parameters.

result_callback is an optional function called when the upload widget completes, either successfully uploading all images or when the widget is closed by user. The callback method is of the following signature function(error, result) . While error is either null if successful or an error message if there was a failure. result is an array of upload image infos, as returned by Cloudinary's upload API.

The method returns a widget object that has the following simple methods for opening and widget and closing it: open() and close().

For example:

cloudinary.openUploadWidget({upload_preset: 'a5vxnzbp'}, 
  function(error, result) {console.log(error, result)});

cloudinary.createUploadWidget(options, result_callback)

Same as openUploadWidget except that it creates a widget object and frame but does not display it until the open method of the returned widget object is called.

For example:

var widget = cloudinary.createUploadWidget({ upload_preset: 'a5vxnzbp' },
      function(error, result) {console.log(error, result)});

widget.open();

cloudinary.applyUploadWidget(element, options, result_callback)

Same as createUploadWidget except that it modifies the given element to be a nice blue button (customizable look & feel) that when clicked opens a pre-created upload widget. In addition, the form and thumbnails options are implicitly set by default to the containing form of the given element.

For example:

cloudinary.applyUploadWidget(document.getElementById('opener'), 
  { upload_preset: 'a5vxnzbp' }, 
    function(error, result) {console.log(error, result)});

$.fn.cloudinary_upload_widget

Same as applyUploadWidget. Uses jQuery selector to apply on matching elements.

For example:

$('#opener2').cloudinary_upload_widget({ upload_preset: 'a5vxnzbp' });

API events

If jQuery is loaded in your site and the Cloudinary upload widget Javascript file is included, you can bind to the following events:

'cloudinarywidgetsuccess' - Global success event binding

Receive a success callback at the completion of an upload process. When uploading multiple images, the callback is received after all images have uploaded.

For example:

$(document).on('cloudinarywidgetsuccess', function(e, data) {
  console.log("Global success", e, data);
});

'cloudinarywidgetfileuploadsuccess' - Single file success event binding

Receive a success callback at the completion of each file upload.

For example:

$(document).on('cloudinarywidgetfileuploadsuccess', function(e, data) {
  console.log("Single file success", e, data);
});

'cloudinarywidgeterror' - Upload error event binding

Receive a callback when when an error occurs.

For example:

$(document).on('cloudinarywidgeterror', function(e, data) {
  console.log("Error", data);
});

'cloudinarywidgetdeleted' - Image deletion event binding

If jQuery is loaded in your site, you can bind to the the cloudinarywidgetdeleted event for receiving a callback when an image is deleted using the 'x' within the image thumbnail (after the image upload completes). The event receives an object that includes the details of the deleted image (resource_type, type, public_id).

For example:

$(document).on('cloudinarywidgetdeleted', function(e, data) {
  console.log("Public ID", data.public_id);
});

'cloudinarywidgetclosed' - Close widget event binding

Receive a callback when the widget pop-up is closed.

For example:

$(document).on('cloudinarywidgetclosed', function(e, data) {
  console.log("Widget closed", data);
});

Look & feel customization

The look & feel of the upload widget can be fully customized. You can modify colors, fonts, icons and other elements by providing your custom CSS styles. In addition, Cloudinary provides predefined themes instead of the default one.

Custom styles are specified using the 'stylesheet' option. It accepts either a URL of a CSS file with style override instructions or inline style as a string. See the CSS files of the white and minimal themes as reference implementations.

A theme can be applied by setting the 'theme' option to the name of one of the following predefined themes:

'default'

'white'

'minimal'

'purple'

Upload widget options