Widget initialization

  • This documentation is for the version 3.3.0 of the widget. If you're looking for the widget v2 docs, check here.

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

  • UPLOADCARE_MANUAL_START which defaults to false and controls the start of widget initialization.
  • UPLOADCARE_LIVE which defaults to true and controls the character of that initialization.

This means that by default 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 widgets on your page are initialized during its load. When you would like to introduce some preparations, that might not be the desired behavior. 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, 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
    });
  });
});

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 widgets 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.

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.