# `LivePanels.Item.Content.LiveView.Commands`
[🔗](https://github.com/livepanels/livepanels/blob/v0.1.0/lib/livepanels/item/content/live_view/commands.ex#L1)

Socket-first helpers for LivePanels item content.

`use LivePanels.Item.Content.LiveView` imports these helpers for LiveViews mounted inside a
canvas item. Item LiveViews that own `mount/3` directly can import this
module after calling `LivePanels.Item.Content.LiveView.mount_runtime/4`.

These helpers dispatch requests to the parent canvas LiveView and return the
socket they receive. Helpers without an explicit item id read the current
item id from `LivePanels.Context`; during disconnected mount that id
may be absent, so those self-scoped helpers log a debug message and return
without dispatching.

`notify/3` publishes to another item's topic. `request/2` sends a
app-defined message to the parent canvas LiveView as
`{:livepanels_item_request, message}`.

# `command_opts`

```elixir
@type command_opts() :: keyword()
```

# `socket`

```elixir
@type socket() :: Phoenix.LiveView.Socket.t()
```

# `add`

```elixir
@spec add(socket(), term(), command_opts()) :: socket()
```

Requests that the parent canvas add an item of `type`.

`opts` accepts the same item creation options as `LivePanels.Canvas.Item.add/3`.

# `add_attached`

```elixir
@spec add_attached(socket(), term(), command_opts()) :: socket()
```

Requests that the parent canvas add an item attached to the current item.

During disconnected mount, the current item id may not be assigned yet;
in that case this helper logs a debug message and returns `socket` without
dispatching.

# `add_attached`

```elixir
@spec add_attached(socket(), String.t(), term(), command_opts()) :: socket()
```

Requests that the parent canvas add an item attached to `parent_item_id`.

# `canvas_id`

```elixir
@spec canvas_id(socket()) :: String.t()
```

Returns the canvas id for this item content LiveView.

# `item_id`

```elixir
@spec item_id(socket()) :: String.t() | nil
```

Returns the current item's id, or `nil` before an item id is assigned.

# `merge_props`

```elixir
@spec merge_props(socket(), map()) :: socket()
```

Requests a props merge for the current item.

During disconnected mount, the current item id may not be assigned yet;
in that case this helper logs a debug message and returns `socket` without
dispatching.

# `merge_props`

```elixir
@spec merge_props(socket(), String.t(), map()) :: socket()
```

Requests a props merge for the item identified by `item_id`.

# `notify`

```elixir
@spec notify(socket(), String.t(), term()) :: socket()
```

Publishes `message` to the item-scoped topic of another item LiveView.

The receiving item LiveView gets the message in `handle_info/2`. Item
LiveViews are subscribed to their own item topic automatically at mount.

# `place`

```elixir
@spec place(socket(), map()) :: socket()
```

Requests placement of the current item.

During disconnected mount, the current item id may not be assigned yet;
in that case this helper logs a debug message and returns `socket` without
dispatching.

# `place`

```elixir
@spec place(socket(), String.t(), map()) :: socket()
```

Requests placement of the item identified by `item_id`.

# `present`

```elixir
@spec present(socket(), String.t(), command_opts()) :: socket()
```

Requests that the parent canvas present an existing item.

`opts` accepts the same presentation options as `LivePanels.Canvas.Item.present/3`.

# `put_props`

```elixir
@spec put_props(socket(), map()) :: socket()
```

Requests replacement of props on the current item.

During disconnected mount, the current item id may not be assigned yet;
in that case this helper logs a debug message and returns `socket` without
dispatching.

# `put_props`

```elixir
@spec put_props(socket(), String.t(), map()) :: socket()
```

Requests replacement of props on the item identified by `item_id`.

# `remove`

```elixir
@spec remove(socket()) :: socket()
```

Requests removal of the current item.

During disconnected mount, the current item id may not be assigned yet;
in that case this helper logs a debug message and returns `socket` without
dispatching.

# `remove`

```elixir
@spec remove(socket(), String.t()) :: socket()
```

Requests removal of the item identified by `item_id`.

# `request`

```elixir
@spec request(socket(), term()) :: socket()
```

Sends an app-defined request to the parent canvas LiveView.

The parent receives `{:livepanels_item_request, message}` in `handle_info/2`.
The runtime does not interpret the payload.

---

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