drab v0.5.0 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
Broadcasting version of insert_html/4
Broadcasting version of set_prop/3
Parses the specified text as HTML and inserts the resulting nodes into the DOM tree at a specified position
Exception-throwing version of insert_html/4
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
Exception raising version of query_one/3
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
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.
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.
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}
Exception-throwing version of insert_html/4
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"}}}
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 themap
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 thedrab-id
attribute and the key became"[drab-id='...']"
.Values of the map are maps of
%{property => property_value}
. Notice that for some properties (likestyle
ordataset
), 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"}}}}
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.
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"}}
Like query_one!/3
, but returns most popular properties. To be used for debugging / inspecting.
Exception raising version of query_one/3
.
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}
Bang version of set_attr/3
. Raises exception on error.
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_data/3
. Raises exception on error.
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]}}}
Bang version of set_prop/3
, raises exception on error.
Returns number of updated element.
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}
Bang version of set_style/3
. Raises exception on error.