Filarr Drop · Sviluppatori

Integrare Filarr Drop nel tuo sito.

Uno script e un elemento HTML. Il modulo appare in un riquadro servito da drop.filarr.eu; la tua pagina non vede passare né file né risposte.

← Filarr Drop

Il codice minimo

L’app lo genera per te, con l’identificativo e la chiave giusti (Collection › Website forms › Embed). Il link interno appare se JavaScript è disattivato.

<script src="https://drop.filarr.eu/v1/drop.js" defer></script>
<filarr-drop form="frm_8KQ2M7WZ4D1X" pk="<chiave pubblica>" lang="it">
  <a href="https://drop.filarr.eu/f/frm_8KQ2M7WZ4D1X#pk=<chiave pubblica>">Invia documenti</a>
</filarr-drop>

La chiave, il riferimento, la lingua, il tema e l’origine della tua pagina arrivano al riquadro nel frammento del suo indirizzo (dopo #): non vengono mai inviati a un server.

Attributi

Attributi dell’elemento filarr-drop
attributo	regola
`form`	Obbligatorio. L’identificativo del modulo, frm_ seguito da 12 caratteri.
`pk`	Obbligatorio. La chiave pubblica del modulo. Senza, l’elemento mostra solo il suo link interno. Il riquadro cifra solo con questa chiave: se il server ne fornisce un’altra, si rifiuta di apparire.
`lang`	Facoltativo. fr, en, de, es o it. Per impostazione predefinita, la lingua scelta nell’editor.
`mode`	Facoltativo. inline (predefinito) mostra il modulo; button mostra un pulsante che carica il modulo al clic.
`theme`	Facoltativo. light, dark o auto.
`reference`	Facoltativo, al massimo 200 caratteri. Un riferimento di pratica, aggiunto all’invio e cifrato con esso.

Gli attributi vengono letti quando l’elemento entra nella pagina, e solo allora. Per cambiare modulo, chiave o riferimento, sostituisci l’elemento.

Eventi

Il riquadro parla alla tua pagina, mai il contrario. drop.js inoltra i suoi messaggi come eventi DOM sull’elemento. Risalgono nella pagina: anche un listener su un elemento padre li riceve.

Eventi emessi dall’elemento filarr-drop
evento	detail
`filarr:ready`	`{}`	Il modulo è visualizzato.
`filarr:submitted`	`{ receipt, files }`	Un invio è terminato. receipt è il codice di ricevuta di 12 caratteri, senza trattini: mostralo nel formato XXXX-XXXX-XXXX, come il riquadro. files è il numero di file inviati.
`filarr:error`	`{ code }`	Un invio non è riuscito. code è un codice breve, per esempio form_paused, rate o too_large.

document.addEventListener('filarr:submitted', (event) => {
  const { receipt, files } = event.detail;
  const code = receipt.replace(/(.{4})(?=.)/g, '$1-'); // XXXX-XXXX-XXXX
  console.log(code, files);
});

Mai un nome di file, una risposta o un riferimento in un evento.

Gli eventi sono emessi solo verso una pagina la cui origine è tra i siti autorizzati del modulo.

Siti autorizzati

Nell’editor del modulo, elenca le origini in cui può apparire. Il riquadro appare solo lì; altrove, il browser lo blocca. Una modifica vale entro un minuto al massimo.

https://host, o https://host:porta, esattamente: niente caratteri jolly, niente percorso.
Per provare sul tuo computer: http://localhost:porta o http://127.0.0.1:porta, con la porta.
Un elenco vuoto: il modulo non appare in nessun sito. La sua pagina su drop.filarr.eu resta aperta.

Content Security Policy

Se il tuo sito ha una CSP, aggiungi drop.filarr.eu a queste due direttive. drop.js non fa altre richieste oltre al riquadro e non imposta cookie.

script-src … https://drop.filarr.eu;
frame-src … https://drop.filarr.eu;

Versione fissa

/v1/drop.js segue le correzioni della v1. Per un codice che non cambia mai, carica la versione fissa con la sua impronta di integrità:

<script src="https://drop.filarr.eu/v1.0.0/drop.js" integrity="sha384-iVPTsGWrlmwF1PZCIEmxKnyKWcVQIZnXG5VnZHWaFx8geCP7G0RbQoy/gguyTibX" crossorigin="anonymous" defer></script>

React

Carica lo script una sola volta. Dai all’elemento una key che cambia con il modulo, la chiave o il riferimento: React lo sostituisce, e il nuovo elemento rilegge i suoi attributi.

import { useEffect, useRef } from 'react';

const LOADER = 'https://drop.filarr.eu/v1/drop.js';

function loadDropOnce() {
  if (document.querySelector(`script[src="${LOADER}"]`)) return;
  const script = document.createElement('script');
  script.src = LOADER;
  script.defer = true;
  document.head.appendChild(script);
}

export function FilarrDrop({ form, pk, reference, onSubmitted }) {
  const ref = useRef(null);
  useEffect(loadDropOnce, []);
  useEffect(() => {
    const el = ref.current;
    if (!el || !onSubmitted) return;
    const handle = (event) => onSubmitted(event.detail);
    el.addEventListener('filarr:submitted', handle);
    return () => el.removeEventListener('filarr:submitted', handle);
  }, [form, pk, reference, onSubmitted]);
  return (
    <filarr-drop
      key={`${form}:${pk}:${reference ?? ''}`}
      ref={ref}
      form={form}
      pk={pk}
      reference={reference}
    >
      <a href={`https://drop.filarr.eu/f/${form}#pk=${pk}`}>Invia documenti</a>
    </filarr-drop>
  );
}

Next.js

Il componente tocca il DOM: è un componente client. next/script carica drop.js una sola volta, anche se il componente compare in più pagine.

'use client';

import Script from 'next/script';

export function FilarrDrop({ form, pk }) {
  return (
    <>
      <Script src="https://drop.filarr.eu/v1/drop.js" strategy="afterInteractive" />
      <filarr-drop key={`${form}:${pk}`} form={form} pk={pk}>
        <a href={`https://drop.filarr.eu/f/${form}#pk=${pk}`}>Invia documenti</a>
      </filarr-drop>
    </>
  );
}

WordPress

Un plugin WordPress è in preparazione. Nel frattempo, incolla il codice minimo in un blocco «HTML personalizzato».

E lato server?

In questa versione non ci sono API né webhook: gli invii arrivano, cifrati, nel Filarr di chi ha creato il modulo.