drab

v0.10.5

drab

drab v0.10.5 Drab.Query View Source

Drab Module which provides interface to jQuery on the server side. You may query (select/2) or manipulate (update/2, insert/2, delete/2, execute/2) the selected DOM object.

This module is optional and is not loaded by default. You need to explicitly declare it in the commander:

use Drab.Commander, modules: [Drab.Query]

This module requires jQuery installed as global, see README.

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) functions return socket. Query select/2 returns either a found value (when using singular version of jQuery method, eg :html), or a Map of %{name|id|__undefined_XX => value}, when using plural - like :htmls.

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, same controller, or having the same channel topic (see Drab.Commander.broadcasting/1 to find out more).

Link to this section Summary

Types

selected()

The return value of select functions

Functions

delete!(socket, options)

Like Dom.Query.delete/2, but broadcasts instead of pushing the change

delete(socket, options)

Removes nodes, classes or attributes from selected node

execute!(socket, options)

Like Drab.Query.execute/2, but broadcasts instead of pushing the change

execute!(socket, method, options)

See Drab.Query.execute!/2

execute(socket, options)

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

execute(socket, method, options)

See Drab.Query.execute/2

insert!(socket, options)

Like Drab.Query.insert/2, but broadcasts instead of pushing the change

insert!(socket, html, options)

See Drab.Query.insert/2

insert(socket, options)

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

insert(socket, html, options)

See Drab.Query.insert/2

select(socket, options)

Returns a value get by executing jQuery method on selected DOM object, or a Map of %{name|id|_undefined[INCREMENT]: value} when method name is plural, or a Map of %{ method => returns_of_methods}, when the method is :all

select(socket, method, options)

See Drab.Query.select/2

update!(socket, options)

Like Drab.Query.update/2, but broadcasts instead of pushing the change

update!(socket, method, options)

See Drab.Query.update!/2

update(socket, options)

Updates the DOM object corresponding to the jQuery method

update(socket, method, options)

See Drab.Query.update/2

Link to this section Types

Link to this type selected() View Source 
selected() :: String.t() | map() | no_return()

The return value of select functions

Link to this section Functions

Link to this function delete!(socket, options) View Source 
delete!(Drab.Core.subject(), Keyword.t() | String.t()) ::
  Drab.Core.subject() | no_return()

Like Dom.Query.delete/2, but broadcasts instead of pushing the change.

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

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

Link to this function delete(socket, options) View Source 
delete(Phoenix.Socket.t(), Keyword.t() | String.t()) ::
  Phoenix.Socket.t() | no_return()

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")
Link to this function execute!(socket, options) View Source 
execute!(Drab.Core.subject(), Keyword.t()) :: Drab.Core.subject() | no_return()

Like Drab.Query.execute/2, but broadcasts instead of pushing the change.

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

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

Link to this function execute(socket, options) View Source 
execute(Phoenix.Socket.t(), Keyword.t()) :: Phoenix.Socket.t() | no_return()

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")
Link to this function insert!(socket, options) View Source 
insert!(Drab.Core.subject(), Keyword.t()) :: Drab.Core.subject() | no_return()

Like Drab.Query.insert/2, but broadcasts instead of pushing the change.

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

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

Link to this function insert(socket, options) View Source 
insert(Phoenix.Socket.t(), Keyword.t()) :: Phoenix.Socket.t() | no_return()

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 selectors; only applies with :class
  • 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")
Link to this function select(socket, options) View Source 
select(Phoenix.Socket.t(), Keyword.t()) :: selected()

Returns a value get by executing jQuery method on selected DOM object, or a Map of %{name|id|_undefined[INCREMENT]: value} when method name is plural, or a Map of %{ method => returns_of_methods}, when the method is :all.

Plural version uses name attribute as a key, or id, when there is no name, or __undefined_[INCREMENT], when neither id or name are specified.

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: “att” - returns the value of jQuery data("attr") method

Examples:

name = socket |> select(:val, from: "#name")
# "Stefan"
name = socket |> select(:vals, from: "#name")
# %{"name" => "Stefan"}
font = socket |> select(css: "font", from: "#name")
# "normal normal normal normal 14px / 20px \"Helvetica Neue\", Helvetica, Arial, sans-serif"
button_ids = socket |> select(datas: "button_id", from: "button")
# %{"button1" => 1, "button2" => 2}

Available jQuery methods:

html text val
width height
innerWidth innerHeight outerWidth outerHeight
position offset scrollLeft scrollTop
attr: val prop: val css: val data: val

Available jQuery plural methods:

htmls texts vals
widths heights
innerWidths innerHeights outerWidths outerHeights
positions offsets scrollLefts scrollTops
attrs: val props: val csses: val datas: val

:all

In case when method is :all, executes all known methods on the given selector. Returns Map %{name|id => medthod_return_value}. The Map key are generated in the same way as those with plural methods.

socket |> select(:all, from: "span")
%{"first_span" => %{"height" => 16, "html" => "Some text", "innerHeight" => 20, ...

Additionally, id and name attributes are included into a Map.

Link to this function update!(socket, options) View Source 
update!(Drab.Core.subject(), Keyword.t()) :: Drab.Core.subject() | no_return()

Like Drab.Query.update/2, but broadcasts instead of pushing the change.

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

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

Link to this function update(socket, options) View Source 
update(Phoenix.Socket.t(), Keyword.t()) :: Phoenix.Socket.t() | no_return()

Updates the DOM object corresponding to the jQuery 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, returns socket so it can be stacked.

Options:

  • on: selector - DOM selector, on which the changes are made
  • set: value - new value
  • attr: attribute - DOM attribute
  • prop: property - DOM property
  • class: class - class name to be replaced by another class
  • css: updates a given css
  • data: sets the jQuery data storage by calling data("key", value); it does not update the data-* attribute

Examples:

socket |> update(:text, set: "saved...", on: "#save_button")
socket |> update(attr: "style", set: "width: 100%", on: ".progress-bar")
# the same effect:
socket |> update(css: "width", set: "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")

You can also cycle between values - switch to the next value from the list or to the first element, if the actual value is not on the list:

socket |> update(:text, set: ["One", "Two", "Three"], on: "#thebutton")
socket |> update(css: "font-size", set: ["8px", "10px", "12px"], on: "#btn")

When cycling through the class attribute, system will update the class if it is one in the list. In the other case, it will add the first from the list.

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

Please notice that cycling is only possible on selectors which returns one node.

Another possibility is to toggle (add if not exists, remove in the other case) the class:

socket |> update(:class, toggle: "btn-success", on: "#btn")

Available jQuery methods: see Drab.Query.select/2