drab v0.1.0 Drab.Query

Provides interface to DOM objects on the server side. You may query (select/2) or manipulate (update/2, insert/2, delete/2, execute/2) the selected DOM object.

General syntax:

return = socket |> select(what, from: selector)
socket |> update(what, set: new_value, on: selector)
socket |> insert(what, into: selector)
socket |> delete(what, from: selector)
socket |> execute(what, on: selector)

where:

  • socket - websocket used in connection
  • selector - string with a DOM selector
  • what - a representation of jQuery method; an atom (eg. :html, :val) or key/value pair (like attr: name). An atom will launch the corresponding jQuey function without any arguments (eg. .html()). Key/value pair will launch the method named as the key with arguments taken from its value, so text: "some" becomes .text("some").

Object manipulation (update/2, insert/2, delete/2, execute/2) returns tuple {:ok, number_of_objects_affected}. Query select/2 returns list of found DOM object properties (list of htmls, values etc) or empty list when nothing found.

Select queries always refers to the page on which the event were launched. Data manipulation queries (update/2, insert/2, delete/2, execute/2) changes DOM objects on this page as well, but they have a broadcast versions: update!/2, insert!/2, delete!/2 and execute!/2, which works the same, but changes DOM on every currently connected browsers, which has opened the same URL.

Summary

Functions

Asynchronously broadsasts given javascript to all browsers displaying current page

Removes nodes, classes or attributes from selected node

Like Dom.Query.delete/2, but broadcasts to all currently connected browsers, which have the same URL opened

Synchronously executes the given javascript on the client side and returns value

Execute given jQuery method on selector. To be used in case built-in method calls are not enough

Like Drab.Query.execute/2, but broadcasts to all currently connected browsers, which have the same URL opened

Adds new node (html) or class to the selected object

Like Drab.Query.insert/2, but broadcast to all currently connected browsers, which have the same URL opened

Returns an array of values get by executing jQuery method on selected DOM objects

Finds the DOM object which triggered the event. To be used only in event handlers

Like Drab.Query.this/1, but returns CSS ID of the object, so it may be used with broadcasting functions

Sets the DOM object property corresponding to method

Like Drab.Query.update/2, but broadcasts to all currently connected browsers, which have the same URL opened

Functions

broadcastjs(socket, js)

Asynchronously broadsasts given javascript to all browsers displaying current page.

delete(socket, options)

Removes nodes, classes or attributes from selected node.

With selector and no options, removes it and all its children. With given from: selector option, removes only the content, but element remains in the DOM tree. With options class: class, from: selector removes class from given node(s). Given option prop: property or attr: attribute it is able to remove property or attribute from the DOM node.

Waits for the browser to finish the changes and returns socket so it can be stacked.

Options:

  • class: class - class name to be deleted
  • prop: property - property to be removed from selected node(s)
  • attr: attribute - attribute to be deleted from selected node(s)
  • from: selector - DOM selector

Example:

socket |> delete(".btn")       # remove all `.btn`
socket |> delete(from: "code") # empty all `<code>`, but node remains
socket |> delete(class: "btn-success", from: "#button")
delete!(socket, options)

Like Dom.Query.delete/2, but broadcasts to all currently connected browsers, which have the same URL opened.

Broadcast functions are asynchronous, do not wait for the reply from browsers, immediately return :sent.

execjs(socket, js)

Synchronously executes the given javascript on the client side and returns value.

execute(socket, options)

Execute given jQuery method on selector. To be used in case built-in method calls are not enough.

Waits for the browser to finish the changes and returns socket so it can be stacked.

socket |> execute(:click, on: "#mybutton")
socket |> execute(trigger: "click", on: "#mybutton")
socket |> execute("trigger("click")", on: "#mybutton")
execute(socket, method, options)

See Drab.Query.execute/2

execute!(socket, options)

Like Drab.Query.execute/2, but broadcasts to all currently connected browsers, which have the same URL opened.

Broadcast functions are asynchronous, do not wait for the reply from browsers, immediately return :sent.

execute!(socket, method, options)

See Drab.Query.execute!/2

insert(socket, options)

Adds new node (html) or class to the selected object.

Waits for the browser to finish the changes and returns socket so it can be stacked.

Options:

  • class: class - class name to be inserted
  • into: selector - class will be added to specified selector(s)
  • before: selector - creates html before the selector
  • after: selector - creates html node after the selector
  • append: selector - adds html to the end of the selector (inside the selector)
  • prepend: selector - adds html to the beginning of the selector (inside the selector)

Example:

socket |> insert(class: "btn-success", into: "#button")
socket |> insert("<b>warning</b>", before: "#pane")
insert(socket, html, options)

See Drab.Query.insert/2

insert!(socket, options)

Like Drab.Query.insert/2, but broadcast to all currently connected browsers, which have the same URL opened.

Broadcast functions are asynchronous, do not wait for the reply from browsers, immediately return socket.

insert!(socket, html, options)

See Drab.Query.insert/2

select(socket, options)

Returns an array of values get by executing jQuery method on selected DOM objects.

In case the method requires an argument (like attr()), it should be given as key/value pair: method_name: “argument”.

Options:

  • from: “selector” - DOM selector which is queried
  • attr: “attribute” - DOM attribute
  • prop: “property” - DOM property
  • css: “css”
  • data: “data”

Examples:

name = socket |> select(:val, from: "#name") |> List.first
font = socket |> select(css: "font", from: "#name") |> List.first()

The first example above translates to javascript:

$('name').map(function() {
  return $(this).val()
}).toArray()

Available methods: see @methods, @methods_with_argument

select(socket, method, options)

See Drab.Query.select/2

this(dom_sender)

Finds the DOM object which triggered the event. To be used only in event handlers.

def button_clicked(socket, dom_sender) do
  socket |> update(:text, set: "alread clicked", on: this(dom_sender))
  socket |> update(attr: "disabled", set: true, on: this(dom_sender))
end        

Do not use it with with broadcast functions (Drab.Query.update!, Drab.Query.insert, Drab.Query.delete, Drab.Query.execute!), because it returns the exact DOM object. In case if you want to broadcast, use Drab.Query.this!/1 instead.

this!(dom_sender)

Like Drab.Query.this/1, but returns CSS ID of the object, so it may be used with broadcasting functions.

def button_clicked(socket, dom_sender) do
  socket |> update!(:text, set: "alread clicked", on: this!(dom_sender))
  socket |> update!(attr: "disabled", set: true, on: this!(dom_sender))
end

Raises exception when being used on the object without an ID.

update(socket, options)

Sets the DOM object property corresponding to method.

In case when the method requires an argument (like attr()), it should be given as key/value pair: method_name: “argument”.

Waits for the browser to finish the changes and returns socket so it can be stacked.

Options:

  • on: selector - DOM selector, on which the changes are made
  • attr: attribute - DOM attribute
  • prop: property - DOM property
  • class: class - class name to be changed
  • css: updates given css
  • data: updates data-* attribute
  • set: value - new value

Examples:

socket |> update(:text, set: "saved...", on: "#save_button")
socket |> update(attr: "style", set: "width: 100%", on: ".progress-bar")

Update can also switch the classes in DOM object (remove one and insert another):

socket |> update(class: "btn-success", set: "btn-danger", on: "#save_button")

Available methods: see @methods, @methods_with_argument, :class

update(socket, method, options)

See Drab.Query.update/2

update!(socket, options)

Like Drab.Query.update/2, but broadcasts to all currently connected browsers, which have the same URL opened.

Broadcast functions are asynchronous, do not wait for the reply from browsers, immediately return socket.

update!(socket, method, options)

See Drab.Query.update!/2