RFC: getUploadWidgetOptions

[colbyfayock]

The Cloudinary Upload Widget provides developers a way to easily drop in a clientside upload experience including drag and drop, the ability to select from multiple sources, and ways to easily configure upload controls. The CldUploadWidget component is a wrapper around this widget giving an easier way to set up and configure the widget in framework applications (Next.js, Nuxt, Svelte).

CldUploadWidget currently utilizes the Script installation method, which is a bit beyond the scope of this, but ultimately it requires a group of options to be passed into it in order to initialize and make use of the wide variety of features available to the Upload Widget.

In order to provide as much parity as possible between the libraries maintaining a CldUploadWidget component, the maintainers and contributors must rewrite or copy and paste similar code within each of their frameworks, which is slow and prone to creating implementation differences. To help alleviate this, we can abstract some of the work to a utility library, much like we're currently doing for building URLs with CldImage.

The Challenge

Unlike CldImage, CldUploadWidget doesn't take a URL as the primary input, and instead takes a configuration object which is composed of the different options available. This means there's not a single interface that can compose the entirety of CldUploadWidget.

Additionally, some of the initialization and work needed to manage the component is different depending on the framework, leaving no point to try to deduplicate that work.

Proposed Solution

While we can't fully abstract the component into a single function, we can think about how we can compose different parts in a reusable fashion.

This proposal suggests to abstract out the options that are passed into the player upon initialization as well as the Types that are used, both from the Cloudinary Upload Widget itself, but also the props that are passed in as part of the options configuration.

getUploadWidgetOptions

The getUploadWidgetOptions function will compose the options that need to be passed into the Cloudinary Upload Widget createUploadWidget method upon initialization.

Usage would look like the following:

const options = getUploadWidgetOptions(props);
cloudinary.createUploadWidget(ref, options)

This will simplify the ability to support all Upload Widget features while looking forward to creating different API surfaces for a better Upload Widget developer experience.

Types

There are two Types that are needed to be maintained for the Upload Widget:

• Cloudinary Upload Widget (which are not publicly available)
• getUploadWidgetOptions

Cloudinary Upload Widget types can be maintained in a new utility package of @cloudinary-util such as @cloudinary-util/types, which will make it easy to import these types into any project, though with this abstract, may possibly be no longer needed in the framework layer.

getUploadWidgetOptions will be the primary interface that the frameworks interact with, which can be used as the foundational interface that creates the component's Types, for instance

interface CldUploadWidget extends GetUploadWidgetOptions {
   …
}

Relevant Issues

• [Feature] Create a new Types package for native Cloudinary types #122

Other Similar RFCs

• RFC: getVideoPlayerOptions #86

[colbyfayock]

@Baroshem @matiasfha this is mostly a clone of getVideoPlayerOptions but still scoping this out. if you have any Upload Widget specific thoughts please add them here

[Baroshem]

I looked at other methods in UploadWidget and other ones unfortunately use Vue specific things like Refs, watchers, etc

[colbyfayock]

Question: is there anything framework specific about the generateSignature function?

https://github.com/cloudinary-community/next-cloudinary/blob/main/next-cloudinary/src/components/CldUploadWidget/CldUploadWidget.tsx#L144

[Baroshem]

I dont think there is. I am using exactly the same code:

function generateSignature(callback: Function, paramsToSign: object) {
  if (typeof signatureEndpoint === "undefined") {
    throw Error("Failed to generate signature: signatureEndpoint undefined.");
  }
  fetch(signatureEndpoint, {
    method: "POST",
    body: JSON.stringify({
      paramsToSign,
    }),
  })
    .then((r) => r.json())
    .then(({ signature }) => {
      callback(signature);
    });
}