Uploading Widget JavaScript API — Initialization

This article comes in handy when you want to alter the default Uploading Widget initialization behavior. That can be done to get more control over Uploading Widget on your system and has to do with the two following boolean parameters:

  • UPLOADCARE_MANUAL_START, the option which defaults to false and controls the start of Uploading Widget initialization.
  • UPLOADCARE_LIVE, the option which defaults to true and controls the character of that initialization.

This means that by default Uploading Widgets are initialized during your page load. And, every ~100 ms we check if there are any new inputs with the specific role [role=uploadcare-uploader].

Automatic vs manual init

All Uploading Widgets on your page are initialized during its load, which may not be the desired behavior when you want to do something before the page load. That is when the UPLOADCARE_MANUAL_START option comes in together with uploadcare.start(). You should pass the settings object into uploadcare.start() to override global settings. However, you can still pass any global settings, but keep in mind that settings keys are camelCased, not CAPITALIZED_WITH_UNDERSCORES:

UPLOADCARE_MANUAL_START = true;

jQuery(function($) {
  var $.getJSON('/uploadcare.json', function(data) {
    uploadcare.start({
      publicKey: data.publicKey, // overrides UPLOADCARE_PUBLIC_KEY
      crop: data.crop // overrides UPLOADCARE_CROP
    });
  });
});javascript

See UPLOADCARE_PUBLIC_KEY and UPLOADCARE_CROP for details about the snippet above.

Checking for new inputs

By default, new [role=uploadcare-uploader] elements on your page are initialized as Uploading Widget in every ~100 ms. Such behavior is caused by a single JavaScript timer. It shouldn’t have any performance impact in typical applications.

However, if you would like to alter this behavior, consider disabling the UPLOADCARE_LIVE option. Then, you will have to manually init any new inputs with the specified role.