DevactionUI.Dropzone (devaction_ui v0.2.3)

Copy Markdown View Source

The place to drop a file: a dashed area with an icon, what it takes and the limits. It wraps a LiveView upload (allow_upload/3), so the same area takes a drop and a click, and highlights while a file is over it (DevactionUI.Dropzone hook). What went wrong with a file is shown under it, from errors, tied to the file field with aria-describedby, and the errors of the upload itself (upload_errors/1, such as too many files) are added to them, written with the texts of error_labels.

The limits the browser already knows are in the upload config: limits_label (such as "%{types} · up to %{size}") writes them as the hint, from the accept list and the max_file_size of the upload, so they cannot drift from what is enforced; limits/1 and size_text/1 give the pieces to write them by hand. The accept list also goes to the file input, so the file picker filters by it.

The files chosen are listed under the area. By default each is a row with the name, a DevactionUI.Progress bar that fills as it goes up, its own errors (upload_errors/2) and, with cancel_event, a button that removes it (the event gets phx-value-ref, to call cancel_upload/3). To draw the row yourself give the entry slot, which gets the Phoenix.LiveView.UploadEntry; the cancel button is still added beside it. over_label is announced politely while a file is dragged over the area, so the state is not only colour.

queue/1 is the same drop area with a gridded face and, under it, the whole queue: one row per file with its state (sent, uploading, stopped, waiting, refused), a progress bar, the size, a "Try again" button for a file that stopped and a button that cancels or removes it, above a summary line with a "Clear finished" action. The rows come from the entries of a LiveView upload (upload) or, for a queue of your own, from plain maps (entries).

Summary

Functions

dropzone(assigns)
limits(arg)

The limits of an upload as text: types (such as .txt, .mp3; blank for any) and size (such as 200 MB).

queue(assigns)
size_text(bytes)

A size in bytes as text in decimal units, such as 200 MB or 1.5 KB.

Functions

dropzone(assigns)

Attributes

  • id (:string) (required)
  • upload (Phoenix.LiveView.UploadConfig) (required)
  • title (:string) (required) - what to drop, e.g. Drop the transcript or the audio.
  • hint (:string) - what it takes, e.g. .mp3, .m4a, .txt · up to 200 MB. Defaults to nil.
  • limits_label (:string) - the hint written from the upload's own limits when there is no hint; %{types} and %{size} are filled in, as in "%{types} · up to %{size}". Defaults to nil.
  • errors (:list) - messages about the files, already translated. Defaults to [].
  • error_labels (:map) - the text of each upload error (%{too_large: "Too large", not_accepted: "Not accepted", too_many_files: "Too many"}); an error with no text shows its name. Defaults to %{}.
  • disabled (:boolean) - takes neither a click nor a drop. Defaults to false.
  • over_label (:string) - announced while a file is dragged over the area, such as Drop to upload. Defaults to nil.
  • cancel_event (:string) - shows a button on each file that sends this event with phx-value-ref, for cancel_upload/3. Defaults to nil.
  • cancel_label (:string) - names the cancel button of a file, as in "Remove %{name}". Defaults to nil.
  • target (:any) - a phx-target (a @myself) when used inside a LiveComponent. Defaults to nil.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.

Slots

  • icon - the upload icon, drawn by the caller; it gets a box of 22px.
  • cancel_icon - replaces the typographic × of the cancel button.
  • entry - one chosen file, drawn by the caller instead of the default row; gets the UploadEntry, with progress from 0 to 100.

limits(arg)

@spec limits(Phoenix.LiveView.UploadConfig.t()) :: %{
  types: String.t(),
  size: String.t()
}

The limits of an upload as text: types (such as .txt, .mp3; blank for any) and size (such as 200 MB).

queue(assigns)

Attributes

  • id (:string) (required)
  • upload (Phoenix.LiveView.UploadConfig) - the upload whose entries are the rows, and whose input takes the click and the drop; leave it out for a queue of your own. Defaults to nil.
  • entries (:list) - the rows when there is no upload: maps with name and, as they apply, ref, size (bytes or text), progress (0 to 100), state (:sent, :uploading, :failed, :queued or :rejected), message (replaces the state's text) and hint (replaces the line under a refused file). Defaults to [].
  • failed (:list) - the refs of the upload entries that stopped (LiveView does not know a connection dropped; the server does). Defaults to [].
  • title (:string) (required) - what to drop, e.g. Drop files or click to choose.
  • hint (:string) - what it takes, e.g. PDF, PNG or JPG · up to 25 MB each. Defaults to nil.
  • over_title (:string) - replaces the title while a file is over the area, e.g. Release to upload. Defaults to nil.
  • over_hint (:string) - replaces the hint while a file is over the area, e.g. 3 files · 4.2 MB. Defaults to nil.
  • dragging (:boolean) - draws the area as if a file were over it (for a page that shows the state). Defaults to false.
  • summary (:string) - the line over the rows, written by the caller: 5 files · 1 uploading · 1 with an error. Defaults to nil.
  • clear_label (:string) - the action beside the summary, e.g. Clear finished; it shows with clear_event. Defaults to nil.
  • labels (:map) (required) - the words of the rows, by key: sent, uploading (uploading · %{size}), queued, failed, stopped (stopped at %{percent}%), rejected, rejected_hint, retry, cancel and remove (Cancel %{name}, Remove %{name}).
  • error_labels (:map) - the text of each upload error, as in dropzone/1; the text of a refused file comes from here. Defaults to %{}.
  • retry_event (:any) - sent with phx-value-ref by the button of a stopped file: a string or a %JS{}. Defaults to nil.
  • cancel_event (:any) - sent with phx-value-ref by the button that cancels a file that is not sent and removes one that is (cancel_upload/3). Defaults to nil.
  • clear_event (:any) - sent by the clear action. Defaults to nil.
  • target (:any) - a phx-target (a @myself) when used inside a LiveComponent. Defaults to nil.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.

Slots

  • icon - the upload icon in the box of the area; it gets 22px.
  • retry_icon - before the text of the retry button; a ↻ when empty.
  • cancel_icon - the icon of the cancel button; a × when empty.
  • remove_icon - the icon of the remove button of a sent file; a × when empty.

size_text(bytes)

@spec size_text(non_neg_integer()) :: String.t()

A size in bytes as text in decimal units, such as 200 MB or 1.5 KB.