drab v0.10.5 Drab.Client View Source

Enable Drab on the browser side. Must be included in HTML template, for example in web/templates/layout/app.html.eex:

<%= Drab.Client.run(@conn) %>

after the line which loads app.js:

<script src="<%= static_path(@conn, "/js/app.js") %>"></script>

at the very end of the layout (after template rendering functions).

Own channels inside the Drab’s socket

On the browser side, there is a global object Drab, which you may use to create your own channels inside Drab Socket:

ch = Drab.socket.channel("mychannel:whatever")
ch.join()

Custom socket constructor (Webpack “require is not defined” fix)

If you are using JS bundler other than default brunch, the require method may not be availabe as global. In this case, you might see the error:

require is not defined

in the Drab’s javascript, in line:

this.Socket = require("phoenix").Socket;

In this case, you must provide it. In the app.js add a global variable, which will be passed to Drab later:

window.__socket = require("phoenix").Socket;

Then, tell Drab to use this instead of default require("phoenix").Socket. Add to config.exs:

config :drab, MyAppWeb.Endpoint,
  js_socket_constructor: "window.__socket"

This will change the problematic line in Drab’s javascript to:

this.Socket = window.__socket;

Drab JS client API

Drab.connect(token_object)

Connects to the Drab’s websocket. Must be called after injecting JS code with Drab.Client.generate/2:

<%= Drab.Client.generate(@conn) %>
<script>
  if (window.Drab) Drab.connect({auth_token: window.my_token});
</script>

Drab.exec_elixir(elixir_function_name, argument, callback)

Run elixir function (which must be a handler in the commander) from the browser side.

Arguments:

  • elixir_function_name(string) - function name
  • argument(object) - the object will be passed to the handler function; if it is not an object, it is converted to {payload: argumen}
  • callback - callback function runs after event handler finish

Function name may be given with the commander name, like “MyApp.MyCommander.handler_function”, or the function name only: “handler_function”. In this case the corresponding commander module will be used. This function must be marked as public with Drab.Commander.public/1 or defhandler macro.

Returns:

  • no return

Example:

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

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

Drab.enable_drab_on(selector_or_node)

Evaluates DOM to set up Drab events.

Called automatically on page load for the whole document. You need to call it after adding/changing html fragments from the client side. No need to call it when updating html with Drab commands (poke, insert_html, etc).

Arguments:

  • selector_or_node - DOM object or its selector under which Drab re-evaluate the html; uses document if not given

Return:

  • no return

Link to this section Summary

Functions

Like run/2, but does not connect to the Drab socket

Generates JS code and runs Drab

Link to this section Functions

Link to this function generate(conn, assigns \\ []) View Source
generate(Plug.Conn.t(), Keyword.t()) :: String.t()

Like run/2, but does not connect to the Drab socket.

It is intended to use when you need to pass the additional tokens, eg. for authorization. To connect, use Drab.connect(object) JS function.

<script>
  window.my_token = ...
</script>
<%= Drab.Client.generate(@conn) %>
<script>
  if (window.Drab) Drab.connect({auth_token: window.my_token});
</script>

Like in run/2, you may use optional arguments, which will become socket’s assigns.

Please check Drab.Socket for more information about how to handle the auth tokens with Drab.

Generates JS code and runs Drab.

Passes controller and action name, tokenized for safety. Works only when the controller, which renders the current action, has a corresponding commander, or has been compiled with use Drab.Controller.

Optional argument may be a list of parameters which will be added to assigns to the socket. Example of layout/app.html.eex:

<%= Drab.Client.run(@conn) %>
<%= Drab.Client.run(@conn, user_id: 4, any_other: "test") %>

Please remember that your parameters are passed to the browser as Phoenix Token. Token is signed, but not ciphered. Do not put any secret data in it.