drab v0.6.0-pre.1 Drab.Element

HTML element query and manipulation library.

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

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.

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

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

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_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

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

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

Bang version of set_attr/3. Raises exception on error

Helper for setting the dataset of elements. A shorthand for

Bang version of set_data/3. Raises exception on error

Finds all html elements using selector and sets their properties

Bang version of set_prop/3, raises exception on error

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

Bang version of set_style/3. Raises exception on error

Link to this section Functions

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

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)

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 insert_html(socket, selector, position, html)

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}
Link to this function insert_html!(socket, selector, position, html)

Exception-throwing version of insert_html/4

Link to this function query(socket, selector)

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)

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!(socket, selector)

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)

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

Link to this function query_one(socket, selector)

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)

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 {:too_many, 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 query_one!(socket, selector)

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)

Exception raising version of query_one/3.

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

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_attr!(socket, selector, attributes)

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

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

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}
Link to this function set_data!(socket, selector, dataset)

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

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

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]}}}
Link to this function set_prop!(socket, selector, properties)

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

Returns number of updated element.

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

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}
Link to this function set_style!(socket, selector, properties)

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