# `Ascii.Phoenix`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/phoenix.ex#L2)

Pieces in Phoenix: `player/1` plays one in a page, through its own
LiveView (`Ascii.Phoenix.PlayerLive`); `live_player/1` plays one
inside yours (`Ascii.Phoenix.PlayerComponent`), taking new options as
your assigns change, for live data. For a still, use
`Ascii.Phoenix.Components.ascii/1`.

    <Ascii.Phoenix.player socket={@socket} id="donut" piece="donut" />
    <Ascii.Phoenix.player socket={@socket} id="coast" piece="night-coast" render={:server} />
    <Ascii.Phoenix.player socket={@socket} id="hello" piece="big-text" ink="#ff5f6d,#ffc371" />
    <Ascii.Phoenix.player socket={@socket} id="boot" piece="boot-log" parts />
    <Ascii.Phoenix.live_player id="files" piece="file-tree" options={%{walk: false, paths: @paths}} interactive notify />

Only available when `phoenix_live_view` is a dependency.

# `live_player`

Plays a piece inside your LiveView, taking new options each time it is
rendered with them: for live data (see `Ascii.Phoenix.PlayerComponent`).

    <Ascii.Phoenix.live_player id="load" piece="gauge" options={%{label: "load", value: @load}} />

## Attributes

* `id` (`:string`) (required) - unique on the page.
* `piece` (`:any`) (required) - a slug, or a module implementing `Ascii.Piece`.
* `options` (`:map`) - the piece's options; new ones are taken up as it plays. Defaults to `%{}`.
* `fps` (`:integer`) - frames a second; the piece's own by default. Defaults to `nil`.
* `mono` (`:boolean`) - draw a coloured piece in one ink. Defaults to `false`.
* `ink` (`:any`) - as for `player/1`. Defaults to `nil`.
* `gradient` (`:atom`) - as for `player/1`. Defaults to `nil`.
* `parts` (`:any`) - as for `player/1`. Defaults to `nil`.
* `paper` (`:boolean`) - dark ink on a light page. Defaults to `false`.
* `render` (`:atom`) - as for `player/1`. Defaults to `:client`. Must be one of `:client`, or `:server`.
* `label` (`:string`) - as for `player/1`. Defaults to `nil`.
* `interactive` (`:boolean`) - as for `player/1`. Defaults to `false`.
* `notify` (`:boolean`) - send your LiveView each key and click (see `Ascii.Phoenix.PlayerComponent`). Defaults to `false`.

# `player`

Plays a piece, embedding `Ascii.Phoenix.PlayerLive` with `live_render/3`.

## Attributes

* `socket` (`:any`) (required) - the parent LiveView's socket (or the conn in a dead view).
* `id` (`:string`) (required) - a DOM id, unique on the page.
* `piece` (`:any`) (required) - a slug, or a module implementing `Ascii.Piece`.
* `options` (`:map`) - the piece's options. Defaults to `%{}`.
* `fps` (`:integer`) - frames a second; the piece's own by default. Defaults to `nil`.
* `mono` (`:boolean`) - draw a coloured piece in one ink. Defaults to `false`.
* `ink` (`:any`) - the colour of a piece in one ink: `"#rrggbb"`, or a list (or comma-separated) for a gradient; see `Ascii.Ink`. Defaults to `nil`.
* `gradient` (`:atom`) - which way several inks run; `:horizontal` by default. Defaults to `nil`. Must be one of `nil`, `:horizontal`, `:vertical`, or `:diagonal`.
* `parts` (`:any`) - colours for the piece's parts: a map of part names to colours, or `true` for the ones it suggests; see `Ascii.Parts`. Defaults to `nil`.
* `paper` (`:boolean`) - dark ink on a light page. Defaults to `false`.
* `render` (`:atom`) - `:client` draws in the browser with the hook (loops sent once, then only changes); `:server` patches HTML from the server, with no hook. Defaults to `:client`. Must be one of `:client`, or `:server`.
* `label` (`:string`) - what the picture shows, for screen readers; by default the piece tells it from its options (`Ascii.describe/1`). Defaults to `nil`.
* `interactive` (`:boolean`) - keys and clicks go to the piece (`Ascii.handle_event/2`): its element takes focus, and arrows, space, enter and typing reach it (clicks need the hook). Defaults to `false`.
* `notify` (`:boolean`) - send the LiveView that embeds the player `{:ascii, id, info}` for each key and click (see `Ascii.Phoenix.PlayerComponent`). Defaults to `false`.

---

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