RFC - MediaLibrary

[Baroshem]

Hey there and welcome to this RFC about Media Library component powered by Cloudinary!

What is Cloudinary Media Library widget?

By integrating the Cloudinary Media Library widget into your CMS or any other web application, all your users can easily select images, videos, PDFs, or other stored raw files directly from Cloudinary and insert them in a way that exactly fits your application design, required behavior, and overall workflow.

The integration involves only a few lines of code and provides you (and your users) all the benefits of Cloudinary's responsive Media Library UI with its rich search capabilities and optimized media asset delivery.

Usage

Users can use the CldMediaLibrary component like following:

<script setup lang="ts">
const buttonId = 'open-btn'
const apiKey = '12345'
</script>

<template>
  <div>
    <button :id="buttonId">
      Select Image or Video
    </button>
    <CldMediaLibrary
      :api-key="apiKey"
      :button-id="buttonId"
    />
  </div>
</template>

The component accepts following props:

Prop Name	Type	Example
cloudName	string	"demo"
apiKey	string	"12345"
buttonId	string	"my-btn"
username	string	"user"
useSaml	boolean	false
params	object	{}

Users can customize default behavior like following:

<script setup lang="ts">
const buttonId = "open-btn";
const apiKey = useRuntimeConfig().public.cloudinary.apiKey;

const params = {
  sortProps: {
    button_caption: "Open Media Library",
    insert_caption: "Insert",
    remove_header: false,
    max_files: 6,
  },
};
</script>

<template>
  <div>
    <button :id="buttonId">Select Image or Video</button>
    <ClsMediaLibrary :api-key="apiKey" :button-id="buttonId" :params="params" />
  </div>
</template>

And there is also an option to react to events like following:

ClsMediaLibrary emits following events:

Event Name	Type	Example
onInsert	function	(data) => { }

You can use this event like following:

<script setup lang="ts">
const buttonId = "open-btn";
const apiKey = useRuntimeConfig().public.cloudinary.apiKey;

function handleInsert(data: unknown) {
  console.log(data)
}
</script>

<template>
  <div>
    <button :id="buttonId">Select Image or Video</button>
    <ClsMediaLibrary
      :api-key="apiKey"
      :button-id="buttonId"
      :params="params"
      @on-insert="handleInsert"
    />
  </div>
</template>

Summary

This was the implementation that I have created for Nuxt so let's consider it as a beta which we can modify to support more examples and be more usable in general. I am open for any feedback from you :)

[colbyfayock]

thanks for putting this together @Baroshem

a few thoughts:

• i wonder if we could provide a pattern similar to the Upload Widget as far as how the button is added to the page, so perhaps along the lines of:

<CldMediaLibrary>
  <button>Open</button>
</CldMediaLibrary>

it would be more consistent to the current components and i think it would be a bit more intuitive

• Could we take advantage of the environment variables for hte API key like we do the Upload Widget rather than having a prop?
• I would think we'd want to have a config prop pattern for those who want to configure the credentials directly (such as using multiple environments)
• I'd like to be able to provide some top level options, but having a params prop is okay to start off until we discover what the top level props should be. though again, i can't help but wonder if instead of params we use options to have API consistency with the Upload Widget
  https://cloudinary.nuxtjs.org/components/clduploadwidget#general-props

i think we'll be able to also set up similar functions for something like getMediaLibraryProps to make it consistent across frameworks

[ghostdevv]

+1 I can see it being similar to the upload widget, and we should use the standard props and options shape we have across other components