drab v0.5.6 Drab.Core

Drab Module with the basic communication from Server to the Browser. Does not require any libraries like jQuery, works on pure Phoenix.

defmodule DrabPoc.JquerylessCommander do
  use Drab.Commander, modules: []

  def clicked(socket, payload) do
    socket |> console("You've sent me this: #{payload |> inspect}")
  end
end

See Drab.Commander for more info on Drab Modules.

Events

Events are defined directly in the HTML by adding drab-event and drab-handler properties:

<button drab-event='click' drab-handler='button_clicked'>clickme</button>

Clicking such button launches DrabExample.PageCommander.button_clicked/2 on the Phoenix server.

There are few shortcuts for the most popular events: click, keyup, keydown, change. For this event an attribute drab-EVENT_NAME must be set. The following like is an equivalent for the previous one:

<button drab-click='button_clicked'>clickme</button>

Normally Drab operates on the user interface of the browser which generared the event, but it is possible to broadcast the change to all the browsers which are currently viewing the same page. See the bang functions in Drab.Query module.

Event handler functions

The event handler function receives two parameters:

  • socket - the websocket used to communicate back to the page by Drab.Query functions
  • sender - a map contains information of the object which sent the event; keys are binary strings

The sender map:

%{
  "id"      => "sender object ID attribute",
  "name"    => "sender object 'name' attribute",
  "class"   => "sender object 'class' attribute",
  "text"    => "sender node 'text'",
  "html"    => "sender node 'html', result of running .html() on the node",
  "value"   => "sender object value",
  "data"    => "a map with sender object 'data-xxxx' attributes, where 'xxxx' are the keys",
  "event"   => "a map with choosen properties of `event` object"
  "drab_id" => "internal"
  "form"    => "a map of values of the sourrounding form"
  :params   => "a map of values of the sourrounding form, normalized to controller type params"
}

The event map contains choosen properties of event object:

altKey, data, key, keyCode, metaKey, shiftKey, ctrlKey, type, which,
clientX, clientY, offsetX, offsetY, pageX, pageY, screenX, screenY

Example:

def button_clicked(socket, sender) do
  # using Drab.Query
  socket |> update(:text, set: "clicked", on: this(sender))
end

sender may contain more fields, depending on the used Drab module. Refer to module documentation for more.

Form values

If the sender object is inside a

tag, it sends the “form” map, which contains values of all the inputs found withing the form. Keys of that map are “name” attribute of the input or, if not found, an “id” attribute. If neither “name” or “id” is given, the value of the form is not included.

Running Elixir code from the Browser

There is the Javascript method Drab.run_handler() in global Drab object, which allows you to run the Elixir function defined in the Commander.

Drab.run_handler(event_name, function_name, argument)

Arguments:

  • event_name(string) - name of the even which runs the function
  • function_name(string) - function name in corresponding Commander module
  • argument(anything) - any argument you want to pass to the Commander function

Returns:

  • no return, does not wait for any answer

Example:

<button onclick="Drab.run_handler('click', 'clicked', {click: 'clickety-click'});">
  Clickme
</button>

The code above runs function named clicked in the corresponding Commander, with the argument %{"click" => "clickety-click}"

Store

Analogically to Plug, Drab can store the values in its own session. To avoid confusion with the Plug Session session, it is called a Store. You can use functions: put_store/3 and get_store/2 to read and write the values in the Store. It works exactly the same way as a “normal”, Phoenix session.

  • By default, Drab Store is kept in browser Local Storage. This means it is gone when you close the browser or the tab. You may set up where to keep the data with drab_store_storage config entry.
  • Drab Store is not the Plug Session! This is a different entity. Anyway, you have an access to the Plug Session (details below).
  • Drab Store is stored on the client side and it is signed, but - as the Plug Session cookie - not ciphered.

Session

Although Drab Store is a different entity than Plug Session (used in Controllers), there is a way to access the Session. First, you need to whitelist the keys you want to access in access_session/1 macro in the Commander (you may give it a list of atoms or a single atom). Whitelisting is due to security: it is kept in Token, on the client side, and it is signed but not encrypted.

defmodule DrabPoc.PageCommander do
  use Drab.Commander

  onload :page_loaded,
  access_session :drab_test

  def page_loaded(socket) do
    socket
    |> update(:val, set: get_session(socket, :drab_test), on: "#show_session_test")
  end
end

There is no way to update the session from Drab. Session is read-only.

Broadcasting

You may use Drab for broadcasting changes to all connected browsers. Drab uses a subject for distinguishing browsers, which are allowed to receive the change.

Broadcasting function receives socket or subject as the first argument. If socket is used, function derives the subject from the commander configuration. See Drab.Commander.broadcasting/1 to learn how to configure the broadcasting options.

Broadcasting functions may be launched without the socket given. In this case, you need to define it manually, using helper functions: Drab.Core.same_path/1, Drab.Core.same_topic/1 and Drab.Core.same_controller/1. See broadcast_js/3 for more.

List of broadcasting functions:

Link to this section Summary

Functions

Asynchronously executes the javascript on all the browsers listening on the given subject

Synchronously executes the given javascript on the client side

Exception raising version of exec_js/2

Returns the value of the Plug Session represented by the given key

Returns the value of the Plug Session represented by the given key or default when key not found

Returns the value of the Drab store represented by the given key

Returns the value of the Drab store represented by the given key or default when key not found

Saves the key => value in the Store. Returns unchanged socket

Helper for broadcasting functions, returns topic for a given controller

Helper for broadcasting functions, returns topic for a given URL path

Helper for broadcasting functions, returns topic for a given topic string.

iex> same_topic("mytopic")
"topic:mytopic"

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

Like this/1, but returns object ID, so it may be used with broadcasting functions

Link to this section Functions

Link to this function broadcast_js(subject, js, options \\ [])

Asynchronously executes the javascript on all the browsers listening on the given subject.

The subject is derived from the first argument, which could be:

  • socket - in this case broadcasting option is derived from the setup in the commander. See Drab.Commander.broadcasting/1 for the broadcasting options

  • same_path(string) - sends the JS to browsers sharing (and configured as listening to same_path in Drab.Commander.broadcasting/1) the same url

  • same_commander(atom) - broadcast goes to all browsers configured with :same_commander

  • same_topic(string) - broadcast goes to all browsers listening to this topic; notice: this is internal Drab topic, not a Phoenix Socket topic

First argument may be a list of the above.

The second argument is a JavaScript string.

See Drab.Commander.broadcasting/1 to find out how to change the listen subject.

iex> Drab.Core.broadcast_js(socket, "alert('Broadcasted!')")
{:ok, :broadcasted}
iex> Drab.Core.broadcast_js(same_path("/drab/live"), "alert('Broadcasted!')")
{:ok, :broadcasted}
iex> Drab.Core.broadcast_js(same_controller(MyApp.LiveController), "alert('Broadcasted!')")
{:ok, :broadcasted}
iex> Drab.Core.broadcast_js(same_topic("my_topic"), "alert('Broadcasted!')")
{:ok, :broadcasted}
iex> Drab.Core.broadcast_js([same_topic("my_topic"), same_path("/drab/live")], "alert('Broadcasted!')")
{:ok, :broadcasted}

Returns {:ok, :broadcasted}

Link to this function broadcast_js!(subject, js, options \\ [])

Bang version of Drab.Core.broadcast_js/3

Returns subject.

Link to this function exec_js(socket, js, options \\ [])

Synchronously executes the given javascript on the client side.

Returns tuple {status, return_value}, where status could be :ok or :error, and return value contains the output computed by the Javascript or the error message.

Options

  • timeout in milliseconds

Examples

iex> socket |> exec_js("2 + 2")
{:ok, 4}

iex> socket |> exec_js("not_existing_function()")
{:error, "not_existing_function is not defined"}

iex> socket |> exec_js("for(i=0; i<1000000000; i++) {}")
{:error, "timed out after 5000 ms."}

iex> socket |> exec_js("alert('hello from IEx!')", timeout: 500)
{:error, "timed out after 500 ms."}
Link to this function exec_js!(socket, js, options \\ [])

Exception raising version of exec_js/2

Examples

iex> socket |> exec_js!("2 + 2")
  4

  iex> socket |> exec_js!("nonexistent")
  ** (Drab.JSExecutionError) nonexistent is not defined
      (drab) lib/drab/core.ex:100: Drab.Core.exec_js!/2

  iex> socket |> exec_js!("for(i=0; i<1000000000; i++) {}")
  ** (Drab.JSExecutionError) timed out after 5000 ms.
      (drab) lib/drab/core.ex:100: Drab.Core.exec_js!/2

  iex> socket |> exec_js!("for(i=0; i<10000000; i++) {}", timeout: 1000)
  ** (Drab.JSExecutionError) timed out after 1000 ms.
      lib/drab/core.ex:114: Drab.Core.exec_js!/3
Link to this function get_session(socket, key)

Returns the value of the Plug Session represented by the given key.

counter = get_session(socket, :userid)

You must explicit which session keys you want to access in :access_session option in use Drab.Commander.

Link to this function get_session(socket, key, default)

Returns the value of the Plug Session represented by the given key or default when key not found

counter = get_session(socket, :userid, 0)

You must explicit which session keys you want to access in :access_session option in use Drab.Commander.

Link to this function get_store(socket, key)

Returns the value of the Drab store represented by the given key.

uid = get_store(socket, :user_id)
Link to this function get_store(socket, key, default)

Returns the value of the Drab store represented by the given key or default when key not found

counter = get_store(socket, :counter, 0)
Link to this function put_store(socket, key, value)

Saves the key => value in the Store. Returns unchanged socket.

put_store(socket, :counter, 1)
Link to this function same_controller(controller)

Helper for broadcasting functions, returns topic for a given controller.

iex> same_controller(DrabTestApp.LiveController)
"controller:Elixir.DrabTestApp.LiveController"

Helper for broadcasting functions, returns topic for a given URL path.

iex> same_path("/test/live")
"same_path:/test/live"
Link to this function same_topic(topic)

Helper for broadcasting functions, returns topic for a given topic string.

iex> same_topic("mytopic")
"topic:mytopic"

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

def button_clicked(socket, sender) do
  set_prop socket, this(sender), innerText: "already clicked"
  set_prop socket, this(sender), disabled: true
end

Do not use it with with broadcast functions (Drab.Query.update!, Drab.Core.broadcast_js, etc), because it returns the exact DOM object in exact browser. In case if you want to broadcast, use this!/1 instead.

Like this/1, but returns object ID, so it may be used with broadcasting functions.

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

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