drab v0.4.1 Drab behaviour

Drab allows to query and manipulate the User Interface directly from the Phoenix server backend.

To enable it on the specific page you must find its controller and enable Drab by use Drab.Controller there:

defmodule DrabExample.PageController do
  use Example.Web, :controller
  use Drab.Controller 

  def index(conn, _params) do
    render conn, "index.html"
  end
end   

Notice that it will enable Drab on all the pages generated by DrabExample.PageController.

All Drab functions (callbacks and event handlers) should be placed in a module called ‘commander’. It is very similar to controller, but it does not render any pages - it works with the live page instead. Each controller with enabled Drab should have the corresponding commander.

defmodule DrabExample.PageCommander do
  use Drab.Commander

  onload :page_loaded

  # Drab Callbacks
  def page_loaded(socket) do
    socket |> update(:html, set: "Welcome to Phoenix+Drab!", on: "div.jumbotron h2")
    socket |> update(:html, 
          set: "Please visit <a href='https://tg.pl/drab'>Drab</a> page for more examples and description",
          on:  "div.jumbotron p.lead")
  end

  # Drab Events
  def button_clicked(socket, dom_sender) do
    socket |> update(:text, set: "alread clicked", on: this(dom_sender))
  end

end

Drab treats browser page as a database, allows you to read and change the data there. Please refer to Drab.Query documentation to find out how Drab.Query.select/2 or Drab.Query.update/2 works.

Debugging Drab in IEx

When started with iex (iex -S mix phoenix.server) Drab shows the helpful message on how to debug its functions:

    Started Drab for /drab/docs, handling events in DrabPoc.DocsCommander
    You may debug Drab functions in IEx by copy/paste the following:
import Drab.{Core, Query, Modal, Waiter}
socket = Drab.get_socket(pid("0.443.0"))

    Examples:
socket |> select(:htmls, from: "h4")
socket |> exec_js("alert('hello from IEx!')")
socket |> alert("Title", "Sure?", buttons: [ok: "Azaliż", cancel: "Poniechaj"])

All you need to do is to copy/paste the line with socket = ... and now you can run Drab function directly from IEx, observing the results on the running browser in the realtime.

Handling Exceptions

Drab intercepts all exceptions from event handler function and let it die, but before it presents the error message in the logs, and, for development environment, on the page. For production, it shows just an alert with the generic error.

By default it is just an alert(), but you can easly override it by creating the template in the priv/templates/drab/drab.handler_error.prod.js folder with your own javascript presenting the message.

Modules

Drab is modular. You may choose which modules to use in the specific Commander by using :module option in use Drab.Commander directive. By default, Drab.Query and Drab.Modal are loaded, but you may override it using options with use Drab.Commander directive.

Every module must have the corresponding javascript template, which is added to the client code in case the module is loaded.

Summary

Functions

detokenize(socket, token, salt \\ "drab token")

Returns data decrypted from the token.

prereqs_for(module)
tokenize(socket, what, salt \\ "drab token")

Tokenize any valid Elixir data.

Returns signed (but not ciphered) string, which can be decrypted with Drab.detokenize/2

Callbacks

js_templates()
js_templates() :: list
prerequisites()
prerequisites() :: list