# `Kotoba.Nodes.Attachment`
[🔗](https://github.com/hattoriai/kotoba/blob/v0.5.0/lib/kotoba/nodes/attachment.ex#L1)

A file in the document (type `"attachment"`), for example an image.

The JSON keys are camelCase, as in Lexical: `key`, `url`, `name`,
`contentType`, `bytes`, `width`, `height`, `preview` and `caption`.

In HTML, an attachment is a `figure` with the class `kotoba-attachment`.
Its caption, when it has one, is its text; else its file name:

  * An image has an `img`, with the caption (else the name) as its `alt`,
    and a `figcaption` with the caption (else the name).
  * A PDF (`figure.kotoba-attachment-pdf`) has an `object` that shows it
    in the browser's viewer, with a download link inside for a browser
    that has none; with a `preview`, a link to the PDF with the preview
    image instead.
  * A video (`figure.kotoba-attachment-video`) has a `video` with
    controls, `preload="metadata"`, no autoplay, the `preview` as its
    poster, and a download link inside.
  * Another file has only its `figcaption`. The `figcaption` of a PDF, a
    video and another file is a download link, with the caption (else
    the name) as its text; the caption also names the viewer and the
    player (`aria-label`).

As plain text, an attachment is its caption, else its name; in Markdown,
`![caption](url)` for an image and `[caption](url)` for another file,
with the name when there is no caption. With the `:untrusted` policy,
only the caption (else the name) is rendered, escaped.

  * `key` - the storage key of the file.
  * `url` - the URL of the file.
  * `name` - the file name.
  * `content_type` - the media type, for example `"image/png"`.
  * `bytes` - the size of the file.
  * `width` and `height` - the size of an image in pixels, or `nil`.
  * `preview` - the URL of an image of a PDF's first page or a video's
    poster frame, or `nil`. The app makes it (see the `:preview` option of
    `Kotoba.Live.consume_uploads/4`).
  * `caption` - what the attachment shows, written by the person, or
    `nil`: for an image, its alternative text and caption. The editor
    writes it under the selected attachment; `Kotoba.Content.from_markdown/2`
    reads it from the alternative text of `![caption](attachment:name)`.

# `t`

```elixir
@type t() :: %Kotoba.Nodes.Attachment{
  bytes: term(),
  caption: term(),
  content_type: term(),
  extra: term(),
  height: term(),
  key: term(),
  name: term(),
  preview: term(),
  url: term(),
  version: term(),
  width: term()
}
```

# `image?`

```elixir
@spec image?(t()) :: boolean()
```

Returns `true` when the attachment is an image.

## Examples

    iex> Kotoba.Nodes.Attachment.image?(%Kotoba.Nodes.Attachment{content_type: "image/png"})
    true

# `label`

```elixir
@spec label(t()) :: String.t()
```

Returns the text of the attachment: its caption, or its name when it has
none (or a blank one).

## Examples

    iex> Kotoba.Nodes.Attachment.label(%Kotoba.Nodes.Attachment{name: "timeline.png", caption: "The timeline"})
    "The timeline"

    iex> Kotoba.Nodes.Attachment.label(%Kotoba.Nodes.Attachment{name: "timeline.png", caption: nil})
    "timeline.png"

# `pdf?`

```elixir
@spec pdf?(t()) :: boolean()
```

Returns `true` when the attachment is a PDF.

# `video?`

```elixir
@spec video?(t()) :: boolean()
```

Returns `true` when the attachment is a video (`video/mp4` or `video/webm`).

---

*Consult [api-reference.md](api-reference.md) for complete listing*