getUploadWidgetOptions #164
Description
Discussed in #124
Originally posted by colbyfayock January 12, 2024
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 {
…
}