Media Plugins Upload

In this section we'll further drill into media upload and error handling in Ricos.

Upload Functions API#

This functions should be passed to the media plugins via config \ helpers (i.e image, gallery, video , audio and file upload).

handleFileUpload: (files: File[], updateEntity: UpdateEntityFunction) => void
handleFileSelection: (updateEntity: UpdateEntityFunction) => void

handleFileUpload is a function provided to handle media uploads from the native file input.
handleFileSelection is a function provided to handle media uploads from a custom file input.

In both functions when the upload phase is done the updateEntity callback should be called with an object containing the data, error (upon faliure) and index (for multiple file uploads).

UpdateEntityFunction<T>: ({ data: T, error: MediaUploadError, index: number }) => void

Media Plugins `data` schemes#

Image and Gallery#

data?: {
  id: string,
  original_file_name: string,
  file_name: string,
  width: number,
  height: number,
}

Video#

data?: {
  pathname: string,
  thumbnail: {
    pathname: string,
    height: number,
    width: number,
  },
}

Audio#

data?: {
  name?: string,
  authorName?: string,
  audio: {
    src: {id?: string, url?: string},
    duration?: number,
  },
  html?:string,
}

File Upload#

data?: {
  name: string;
  type: string;
  url?: string;
  id?: string;
}

Errors#

In order to take advantage of Ricos stunning error toasts and general error handling a proper error object of type MediaUploadError should be passed.
Passing an error object triggers a toast indicating what caused the upload to fail as well as an indication of the error on the block.
Using the getContent method of RicosEditor would also remove all blocks with errors from the content, thus they won't be seen on Viewer nor saved.

MediaUploadError?: {
  msg?: string | JSX.Element;
  key?: MediaUploadErrorKey;
  args?: Record<string, string | number>;
}

msg is a simple string or JSX Element to use for custom error messages to be displayed.
key is an enum with our built in supported and localized error types.
args are arguments needed for the built in toasts.

enum MediaUploadErrorKey {
  GENERIC,
  SIZE_LIMIT,
  QUOTA_STORAGE_VISITOR,
  QUOTA_STORAGE_OWNER,
  QUOTA_VIDEO_VISITOR,
  QUOTA_VIDEO_OWNER,
}

GENERIC a general error with no specific reason
SIZE_LIMIT the file is too big to upload, supports an argument maxLimit for maximum file size indication.
QUOTA_STORAGE_VISITOR file storage exceeded the limit (UoU).
QUOTA_STORAGE_OWNER file storage exceeded the limit (User), supports an argument upgradeUrl to upgrade the site's plan.
QUOTA_VIDEO_VISITOR video hours on the site have reached the maximum (UoU).
QUOTA_VIDEO_OWNER video hours on the site have reached the maximum (User), supports an argument upgradeUrl to upgrade the site's plan.