Phx.Live.Head (Phoenix Live Head v1.0.0)

View Source

Provides commands for manipulating the HTML Head of Phoenix Live View applications while minimizing data over the wire.

The available command actions support a variety of utility operations useful for HTML Head manipulation. Such as setting or removing tag attributes and adding or removing CSS classes for vector (SVG) favicons.

Note

This lib is not meant to be used directly. Have a look at Phx.Live.Favicon and Phx.Live.Metadata. Those libs provide a cleaner syntax and specific documentation for their intended usage.

Query

The query is used by the the Javascript client to select HTML elements using document.querySelectorAll(query).

Actions

Nodes / Elements

  • snap - Takes a snapshot of all selected nodes.
  • restore - Restores a saved snapshot.
  • dynamic - Set the value of a {placeholder}.

Attributes

The actions are applied to an attribute in all selected HTML elements.

Supported actions on the "class" attribute:

  • set - Set class name(s).
  • add - Add to list of class names.
  • remove - Remove from list of class names.
  • toggle - Toggle class name.
  • initial - Reset attribute to it's intial value.

Supported actions on other attributes:

  • set - Set value of attribute.
  • initial - Reset attribute to it's intial value.
  • snap - Take a snapshot of all selected nodes.
  • restore - Restore attributes using a saved snapshot

Dynamic attributes / placeholders

To use a dynamic value for an attribute, the element must have an additional data-dynamic-[attribute] attribute with a value containing a named placeholder. For example: {sub}.

Example

  <!-- data-dynamic-href is set -->
  <!-- {sub} is used in it's value -->
<link rel='icon' href="default_fav.png" data-dynamic-href="favs/{sub}/fav-16x16.png">

When an event is pushed with target = "link[rel*=icon]", action = :dynamic, attr = "sub", and value = "new_message" the result will look like:

<link rel='icon' href="favs/new_message/fav-16x16.png" [...]>

Summary

Types

action()
attr()
change()
name()
query()
value()

Functions

push(socket, query, action, attr, value \\ nil)

Pushes action to apply on attribute of elements matching query. See Actions for available actions.

push_content(socket, query, action, value)

Pushes action to apply on textContent property of elements matching query.

reset(socket, query)

Reset all attributes of elements matching query to their initial value.

reset(socket, query, attr)

Reset an attribute of elements matching query to it's initial value.

restore(socket, query, name, attr \\ "*")

Restore an attribute from snapshot with named name.

snap(socket, query, name, attr \\ "*")

Create a snapshot named name of an attribute from all favicon link element

Types

action()

@type action() ::
  :add | :dynamic | :initial | :remove | :set | :toggle | :snap | :restore

attr()

@type attr() :: String.t() | atom()

change()

@type change() :: [...]

name()

@type name() :: String.t() | atom()

query()

@type query() :: String.t()

value()

@type value() :: String.t() | atom() | integer()

Functions

push(socket, query, action, attr, value \\ nil)

@spec push(Phoenix.LiveView.Socket.t(), query(), action(), attr(), value() | nil) ::
  Phoenix.LiveView.Socket.t()

Pushes action to apply on attribute of elements matching query. See Actions for available actions.

push_content(socket, query, action, value)

@spec push_content(socket :: Phoenix.LiveView.Socket.t(), query(), action(), value()) ::
  Phoenix.LiveView.Socket.t()

Pushes action to apply on textContent property of elements matching query.

Comments

Why textContent and not innerHTML? As per MDN web docs, Node: textContent property,

"...there is still a security risk whenever you use innerHTML to set strings over which you have no control. ... For that reason, it is recommended that instead of innerHTML you use ... Node.textContent when inserting plain text, as this inserts it as raw text rather than parsing it as HTML."

reset(socket, query)

@spec reset(Phoenix.LiveView.Socket.t(), query()) :: Phoenix.LiveView.Socket.t()

Reset all attributes of elements matching query to their initial value.

reset(socket, query, attr)

@spec reset(Phoenix.LiveView.Socket.t(), query(), attr()) ::
  Phoenix.LiveView.Socket.t()

Reset an attribute of elements matching query to it's initial value.

restore(socket, query, name, attr \\ "*")

@spec restore(Phoenix.LiveView.Socket.t(), query(), name(), attr()) ::
  Phoenix.LiveView.Socket.t()

Restore an attribute from snapshot with named name.

snap(socket, query, name, attr \\ "*")

@spec snap(Phoenix.LiveView.Socket.t(), query(), name(), attr()) ::
  Phoenix.LiveView.Socket.t()

Create a snapshot named name of an attribute from all favicon link element