componenten

Uploadcomponent

Met de uploadcomponent kun je rechtstreeks vanaf je site uploaden. Je hebt alleen onze componentbibliotheek en een gegenereerd JWT-token nodig.

<script
  type="module"
  src="https://cdn.video-dns.com/npm/@maveio/components/+esm"
></script>

<mave-upload token="<token>"></mave-upload>

Het vereiste token is een gegenereerde JWT (JSON Web Token) waarvoor je de API key van Mave gebruikt.

Met de waarde die je voor sub instelt, bepaal je wat er gebeurt. Je kunt dit zien als de scope van de upload:

1. sub: {space id}: voegt een nieuwe video aan de space toe
2. sub: {collection id}: voegt een nieuwe video aan de collectie toe
3. sub: {embed id}: vervangt de video door de upload

Je space-ID vind je onder Instellingen: ontwikkelaars. De collectie-ID vind je op de pagina van de collectie zelf, onder de titel.

Hoewel je een ‘statische’ JWT kunt genereren, raden we aan tijdelijke JWT’s met een vervaldatum te maken. Zo kun je de JWT op elk moment intrekken en misbruik voorkomen. Dit kun je als volgt implementeren:

Het volgende voorbeeld toont het gebruik in een Node.js-omgeving. JWT wordt breed ondersteund in verschillende talen en frameworks:

// server
const jwt = require("jsonwebtoken");

const token = jwt.sign(
  {
    sub: "XD9HPRtkDDmENLeVy9ripU", // space, collection or embed can be specified
    exp: 1680795697, // until when the user can upload
  },
  "SHJmNHhXNnFublZXajNCNllYUmhoTTpUVDRqZ3ZqYWJtOEtVbmNFb2h2d1RY" // API key
);

// return `token` to frontend

Opmerking: als je uploaden zonder exp toestaat, blijft deze uploadcomponent altijd geldig, totdat je de API-sleutel intrekt. We raden sterk aan een passende exp te gebruiken om misbruik te voorkomen.

Zodra je het token aan <mave-upload token="{token}" /> toevoegt, is de uploadcomponent actief en klaar voor gebruik.

Eigenschappen

Events

Als je de upload bijvoorbeeld in JavaScript wilt opvangen en de component wilt vervangen zodra de gebruiker de upload heeft voltooid, kun je het volgende doen:

const upload = document.querySelector("mave-upload");
upload.addEventListener("completed", (event) => {
  const player = document.createElement("mave-player");
  player.setAttribute("embed", event.detail.embed);
  upload.parentNode.replaceChild(player, upload);
});

De interface aanpassen

<mave-upload> wordt nog steeds met standaardopmaak geleverd, maar je kunt nu voor elke fase van de uploadflow je eigen markup opgeven door benoemde slots toe te voegen.

<mave-upload token="<token>">
  <div slot="initial" class="initial-card">
    <h2>Upload your media</h2>
    <p>Drop a file or use the button below.</p>
    <button type="button" data-mave-upload-select>Choose a file</button>
  </div>

  <div slot="uploading" class="uploading-card">
    <div class="bar">
      <div class="bar__value" style="width: 0%"></div>
    </div>
    <span data-role="progress-value">0%</span>
  </div>

  <div slot="processing" class="processing-card">Processing…</div>
  <div slot="done" class="done-card">All set!</div>
  <div slot="error" class="error-card">
    <p>Something went wrong. Try again.</p>
    <button type="button" data-mave-upload-select>Try again</button>
  </div>
</mave-upload>

• slot="initial" | "uploading" | "processing" | "done" | "error" bepaalt welke indeling voor die status wordt weergegeven.
• Voeg data-mave-upload-select toe aan een element in de eerste slot om de ingebouwde bestandskiezer te openen.
• Luister naar statechange om op wijzigingen in de voortgang of sleepstatus te reageren.

const upload = document.querySelector("mave-upload");
const progressValue = upload.querySelector('[data-role="progress-value"]');
const progressBar = upload.querySelector(".bar__value");

upload.addEventListener("statechange", ({ detail }) => {
  const { state, progress, dragging } = detail;
  progressValue.textContent = `${progress}%`;
  progressBar.style.width = `${progress}%`;
  upload.toggleAttribute("drag-highlight", dragging);
});

Elke status wordt ook op het hostelement beschikbaar gemaakt, zodat je de opmaak volledig met CSS kunt aansturen:

• Hostattributen: state="initial|uploading|processing|done|error", progress="0-100", drag-over, ready.

Wil je mave-upload bijvoorbeeld markeren wanneer iemand er een bestand overheen sleept, dan kun je dit als volgt doen:

mave-upload[drag-over] [slot="initial"] {
  box-shadow: inset 0 0 0 2px rgba(99, 102, 241, 0.5);
}

Methoden

De wrappers voor React en Vue stellen dezelfde methoden beschikbaar via refs. Zo kun je reset() en andere openbare methoden aanroepen zonder het onderliggende custom element handmatig te beheren.

React

import { useRef } from "react";
import { Upload } from "@maveio/components/react";

const uploadRef = useRef<React.ElementRef<typeof Upload>>(null);

return <Upload ref={uploadRef} token="<token>" />;

// whenever you need to trigger a new upload
uploadRef.current?.reset();

Vue 3

<template>
  <Upload ref="upload" token="<token>" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { Upload } from "@maveio/components/vue";

const upload = ref<InstanceType<typeof Upload> | null>(null);

function triggerReset() {
  upload.value?.reset();
}
</script>

Compleet voorbeeld van een aangepaste uploadcomponent

Bekijk onze voorbeeldpagina op GitHub.