Filarr Drop · Developers

Embed Filarr Drop in your website.

One script and one HTML element. The form renders in a frame served by drop.filarr.eu; your page never sees a file or an answer go by.

← Filarr Drop

The minimal snippet

The app writes it for you, with the right form ID and key (Collection › Website forms › Embed). The inner link shows when JavaScript is off.

<script src="https://drop.filarr.eu/v1/drop.js" defer></script>
<filarr-drop form="frm_8KQ2M7WZ4D1X" pk="<public key>" lang="en">
  <a href="https://drop.filarr.eu/f/frm_8KQ2M7WZ4D1X#pk=<public key>">Send documents</a>
</filarr-drop>

The key, the reference, the language, the theme and your page’s origin reach the frame in the fragment of its address (after #): they are never sent to a server.

Attributes

Attributes of the filarr-drop element
attribute	rule
`form`	Required. The form ID, frm_ followed by 12 characters.
`pk`	Required. The form’s public key. Without it, the element only shows its inner link. The frame only encrypts to this key: if the server hands out a different one, it refuses to load.
`lang`	Optional. fr, en, de, es or it. Defaults to the language chosen in the editor.
`mode`	Optional. inline (the default) shows the form; button shows a button that loads the form when clicked.
`theme`	Optional. light, dark or auto.
`reference`	Optional, at most 200 characters. A case reference, added to the submission and encrypted with it.

Attributes are read when the element enters the page, and only then. To switch form, key or reference, replace the element.

Events

The frame talks to your page, never the other way round. drop.js relays its messages as DOM events on the element. They bubble up: a listener on a parent receives them too.

Events emitted by the filarr-drop element
event	detail
`filarr:ready`	`{}`	The form is displayed.
`filarr:submitted`	`{ receipt, files }`	A submission is complete. receipt is the 12-character receipt code, without dashes: display it as XXXX-XXXX-XXXX, like the frame does. files is the number of files sent.
`filarr:error`	`{ code }`	A submission failed. code is a short code, for example form_paused, rate or 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);
});

Never a file name, an answer or a reference in an event.

Events are only emitted to a page whose origin is among the form’s allowed websites.

Allowed websites

In the form editor, list the origins where it may display. The frame only displays there; anywhere else, the browser blocks it. A change takes effect within a minute.

https://host, or https://host:port, exactly: no wildcard, no path.
To try it on your machine: http://localhost:port or http://127.0.0.1:port, with the port.
An empty list: the form displays on no website. Its page on drop.filarr.eu stays open.

Content Security Policy

If your website has a CSP, add drop.filarr.eu to these two directives. drop.js makes no request other than the frame, and sets no cookie.

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

Pinned version

/v1/drop.js follows v1 fixes. For code that never changes, load the pinned version with its integrity hash:

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

React

Load the script once. Give the element a key that changes with the form, the key or the reference: React replaces it, and the new element reads its attributes again.

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}`}>Send documents</a>
    </filarr-drop>
  );
}

Next.js

The component touches the DOM: it is a client component. next/script loads drop.js only once, even if the component appears on several pages.

'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}`}>Send documents</a>
      </filarr-drop>
    </>
  );
}

WordPress

A WordPress plugin is on its way. In the meantime, paste the minimal snippet into a “Custom HTML” block.

What about the server side?

There is no API or webhook in this version: submissions arrive, encrypted, in the Filarr of whoever created the form.