drab v0.10.0 Drab.Element View Source

HTML element query and manipulation library.

All functions are based on the CSS selectors, for example query/3 runs document.querySelector and returns selected properties of found HTML elements.

Passed values could be a string or Phoenix safe html. It is recommended to use safe html, when dealing with values which are coming from outside world, like user inputs.

import Phoenix.HTML # for sigil_E
username = sender.params["username"]
html = ~E"User: <%= username %>"
set_prop socket, "#div1", innerHTML: html

set_prop/3 is a general function for update elements properties. There are also a bunch of helpers (set_style/3 or set_attr/3), for updating a style of attributes of an element.

Automatic Conversion of Collections

Some of the properties, both whem using getters and setters, are converted automatically from JS collections (eg. HTMLOptionsCollection) to plain objects, so they can be get and set as an Elixir map:

  • attributes (used getAttribute() and setAttribute())
  • style
  • dataset
  • options (only when it is instance of HTMLOptionsCollection)
  • classList

Example:

iex> set_prop socket, "#select_input", options: %{"One" => "Jeden", "Two" => "Dwa"}
{:ok, 1}
iex> query socket, "#select_input", :options
{:ok, %{"#select_input" => %{"options" => %{"One" => "Jeden", "Two" => "Dwa"}}}}

Link to this section Summary

Functions

Parses the specified text as HTML and inserts the resulting nodes into the DOM tree at a specified position

Like query!/3, but returns most popular properties. To be used for debugging / inspecting

Like query/3, but raises instead of returning {:error, reason}

Like query/3, but returns most popular properties. To be used for debugging / inspecting

Queries for the selector in the browser and collects found element properties

Like query_one!/3, but returns most popular properties. To be used for debugging / inspecting

Like query_one/3, but returns most popular properties. To be used for debugging / inspecting

Queries the browser for elements with selector. Expects at most one element to be found

Bang version of set_attr/3. Raises exception on error

Helper for setting the attributes of found elements. A shorthand for

Bang version of set_data/3. Raises exception on error

Helper for setting the dataset of elements. A shorthand for

Bang version of set_html/3, raises exception on error

Finds all html elements using selector and sets their innerHTML property. Html may be a plain string or safe html

Bang version of set_prop/3, raises exception on error

Finds all html elements using selector and sets their properties

Bang version of set_style/3. Raises exception on error

Helper for setting the style property of found elements. A shorthand for

Link to this section Functions

Link to this function broadcast_attr(subject, selector, attributes) View Source

Broadcasting version of set_attr/3.

It does exactly the same as set_attr/3, but instead of pushing the message to the current browser, it broadcasts it to all connected users.

Always returns {:ok, :broadcasted}.

See Drab.Core.broadcast_js/2 for broadcasting options.

Link to this function broadcast_data(subject, selector, dataset) View Source

Broadcasting version of set_data/3.

It does exactly the same as set_data/3, but instead of pushing the message to the current browser, it broadcasts it to all connected users.

Always returns {:ok, :broadcasted}.

See Drab.Core.broadcast_js/2 for broadcasting options.

Link to this function broadcast_html(subject, selector, html) View Source

Broadcasting version of set_html/3.

It does exactly the same as set_html/3, but instead of pushing the message to the current browser, it broadcasts it to all connected users.

Always returns {:ok, :broadcasted}.

See Drab.Core.broadcast_js/2 for broadcasting options.

Link to this function broadcast_insert(subject, selector, position, html) View Source

Broadcasting version of insert_html/4.

It does exactly the same as insert_html/4, but instead of pushing the message to the current browser, it broadcasts it to all connected users.

Always returns {:ok, :broadcasted}.

See Drab.Core.broadcast_js/2 for broadcasting options.

Link to this function broadcast_prop(subject, selector, properties) View Source

Broadcasting version of set_prop/3.

It does exactly the same as set_prop/3, but instead of pushing the message to the current browser, it broadcasts it to all connected users.

Always returns {:ok, :broadcasted}.

See Drab.Core.broadcast_js/2 for broadcasting options.

Link to this function broadcast_style(subject, selector, properties) View Source
broadcast_style(Drab.Core.subject(), String.t(), map() | Keyword.t()) ::
  Drab.Core.bcast_result()

Broadcasting version of set_style/3.

It does exactly the same as set_style/3, but instead of pushing the message to the current browser, it broadcasts it to all connected users.

Always returns {:ok, :broadcasted}.

See Drab.Core.broadcast_js/2 for broadcasting options.

Link to this function insert_html!(socket, selector, position, html) View Source

Exception-throwing version of insert_html/4

Link to this function insert_html(socket, selector, position, safe) View Source

Parses the specified text as HTML and inserts the resulting nodes into the DOM tree at a specified position.

Position is the position relative to the element found by the selector, and must be one of the following strings or atoms:

  • :beforebegin - before the found element
  • :afterbegin - inside the element, before its first child
  • :beforeend - inside the element, after its last child
  • :afterend - after the element itself

Visit https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML for more information.

Returns tuple {:ok, number} with number of updated elements or {:error, description}.

Examples:

ex> insert_html(socket, "div", :beforebegin, "<b>MORE</b>")
{:ok, 3}

Like query!/3, but returns most popular properties. To be used for debugging / inspecting.

Link to this function query!(socket, selector, property_or_properties_list) View Source

Like query/3, but raises instead of returning {:error, reason}.

Like query/3, but returns most popular properties. To be used for debugging / inspecting.

Example:

iex> query socket, "a"
{:ok,
 %{"[drab-id='13114f0a-d65c-4486-b46e-86809aa00b7f']" => %{
       "attributes" => %{"drab-id" => "13114f0a-d65c-4486-b46e-86809aa00b7f",
       "href" => "http://tg.pl"}, "classList" => [], "className" => "",
     "dataset" => %{}, "drab_id" => "13114f0a-d65c-4486-b46e-86809aa00b7f",
     "id" => "", "innerHTML" => "tg.pl", "innerText" => "tg.pl", "name" => "",
     "style" => %{}, "tagName" => "A"}}}
Link to this function query(socket, selector, property_or_properties_list) View Source

Queries for the selector in the browser and collects found element properties.

property_or_properties_list specifies what properties will be returned. It may either be a string, an atom or a list of strings or atoms.

Returns:

  • {:ok, map} - where the map contains queried elements.

    The keys are selectors which clearly identify the element: if the object has an id declared - a string of "#id", otherwise Drab declares the drab-id attribute and the key became "[drab-id='...']".

    Values of the map are maps of %{property => property_value}. Notice that for some properties (like style or dataset), the property_value is a map as well.

  • {:error, message} - the browser could not be queried

Examples:

iex> query socket, "button", :clientWidth
{:ok, %{"#button1" => %{"clientWidth" => 66}}}

iex(170)> query socket, "div", :id
{:ok,
 %{"#begin" => %{"id" => "begin"}, "#drab_pid" => %{"id" => "drab_pid"},
   "[drab-id='472a5f90-c5cf-434b-bdf1-7ee236d67938']" => %{"id" => ""}}}

iex> query socket, "button", ["dataset", "clientWidth"]
{:ok,
 %{"#button1" => %{"clientWidth" => 66,
     "dataset" => %{"d1" => "[1,2,3]", "d1x" => "[1,2,3]", "d2" => "[1, 2]",
       "d3" => "d3"}}}}
Link to this function query_one!(socket, selector) View Source

Like query_one!/3, but returns most popular properties. To be used for debugging / inspecting.

Link to this function query_one!(socket, selector, property_or_properties_list) View Source
query_one!(Phoenix.Socket.t(), String.t(), atom() | list()) ::
  Drab.Core.return() | no_return()

Exception raising version of query_one/3.

Link to this function query_one(socket, selector) View Source

Like query_one/3, but returns most popular properties. To be used for debugging / inspecting.

Link to this function query_one(socket, selector, property_or_properties_list) View Source
query_one(Phoenix.Socket.t(), String.t(), atom() | list()) :: Drab.Core.result()

Queries the browser for elements with selector. Expects at most one element to be found.

Similar to query/3, but always returns a map of properties of one element (or {:ok, nil} if not found). Returns {:error, message} if found more than one element.

Examples:

iex> query_one socket, "button", :innerText
{:ok, %{"innerText" => "Button"}}

iex> query_one socket, "button", ["innerHTML", "dataset"]
{:ok,
 %{"dataset" => %{"d1" => "1", "d2" => "[1, 2]", "d3" => "d3"},
   "innerHTML" => "\n  Button\n"}}
Link to this function set_attr!(socket, selector, attributes) View Source

Bang version of set_attr/3. Raises exception on error.

Link to this function set_attr(socket, selector, attributes) View Source

Helper for setting the attributes of found elements. A shorthand for:

set_prop(socket, selector, %{"attributes" => attributes})

Examples:

iex> set_attr socket, "a", href: "https://tg.pl/drab"
{:ok, 1}
Link to this function set_data!(socket, selector, dataset) View Source

Bang version of set_data/3. Raises exception on error.

Link to this function set_data(socket, selector, dataset) View Source

Helper for setting the dataset of elements. A shorthand for:

set_prop(socket, selector, %{"dataset" => dataset})

Examples:

iex> set_data socket, "button", foo: "bar"
{:ok, 1}

Bang version of set_html/3, raises exception on error.

Returns number of updated element.

Finds all html elements using selector and sets their innerHTML property. Html may be a plain string or safe html.

Returns tuple {:ok, number} with number of updated elements or {:error, description}.

Examples:

iex> set_html socket, "#my_element", "<p>Hello, World!</p>"
{:ok, 1}
Link to this function set_prop!(socket, selector, properties) View Source

Bang version of set_prop/3, raises exception on error.

Returns number of updated element.

Link to this function set_prop(socket, selector, properties) View Source

Finds all html elements using selector and sets their properties.

Takes a map or keyword list of properties to be set, where the key is a property name and the value is the new value to be set. If the property is a Javascript object (like style or attributes), it expects a map.

Returns tuple {:ok, number} with number of updated elements or {:error, description}.

Examples:

iex> set_prop socket, "a", %{"attributes" => %{"class" => "btn btn-warning"}}
{:ok, 1}

iex> set_prop socket, "button", style: %{"backgroundColor" => "red", "width" => "200px"}
{:ok, 1}

iex> set_prop socket, "div", innerHTML: "updated"
{:ok, 3}

You may store any JS encodable value in the property:

iex> set_prop socket, "#button1", custom: %{example: [1, 2, 3]}
{:ok, 1}
iex> query_one socket, "#button1", :custom
{:ok, %{"custom" => %{"example" => [1, 2, 3]}}}

The value of the property may be either a string, or a safe html. It is recommended to use safe html in case of using values from outside the application, like user inputs.

set_prop socket, "#div1", value: ~E/<%=first_name%> <%=last_name%>/
Link to this function set_style!(socket, selector, properties) View Source

Bang version of set_style/3. Raises exception on error.

Link to this function set_style(socket, selector, properties) View Source

Helper for setting the style property of found elements. A shorthand for:

set_prop(socket, selector, %{"style" => properties}})

Examples:

iex> set_style socket, "button", %{"backgroundColor" => "red"}
{:ok, 1}

iex> set_style socket, "button", height: "100px", width: "200px"
{:ok, 1}