drab v0.8.3 Drab
Drab allows to query and manipulate the User Interface directly from the Phoenix server backend.
Drab operates on top of the Phoenix application, to run it you must already have it configured.
In case you operate the app under an umbrella, all Drab configuration and installation should
be done in the Web application (in most cases the one ending with _web
).
All Drab functions (callbacks and event handlers) should be placed in a module called
a ‘commander’. It is very similar to controller, but it does not render any pages - it works
with the live page instead. For example, pages generated by DrabExample.PageController
are
handled by commander with the corresponding name, in this case DrabExample.PageCommander
:
defmodule DrabExample.PageCommander do
use Drab.Commander
onload :page_loaded
# Drab Callbacks
def page_loaded(socket) do
set_prop socket, "div.jumbotron h2", innerHTML: "This page has been DRABBED"
end
# Drab Events
defhandler button_clicked(socket, sender) do
set_prop socket, this(sender), innerText: "already clicked"
end
end
More on commander is in Drab.Commander
documentation.
Drab handler are launched from the client (browser) side by running javascript function
Drab.exec_elixir()
,
or defining the handler function name directly in the html:
<button drab-click="button_clicked">Clickety click</button>
More on event handlers in Drab.Core
documentation.
Debugging Drab in IEx
When started with iex (iex -S mix phx.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 an alert for a user on the page.
By default it is just an alert()
, but you can easly override it by creating the template in the
priv/templates/drab/drab.error_handler.js
folder with your own javascript presenting the
message. You may use the local variable message
there to get the exception description, like:
alert(<%= 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.Live
and Drab.Element
are loaded,
but you may override it using modules
option 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.
Drab.Core
module is always loaded.
Drab in production and behind a proxy
When using in production, an app is often behind an apache/nginx server for domain virtualization
or balancing, so the external port (80) is different from the actual app port (i.e. 4000).
The necessary mapping between the two ports is usually done by configuring a proxy,
but a particularly care have to be taken to correctly handle websocket
calls,
as they are at the core of Drab mechanism to communicate between the client browser and the backend server.
You can find more information and examples to how to configure your nxinx or apache environments on the Drab wiki page at https://github.com/grych/drab/wiki/Drab-in-production-and-behind-a-proxy
Learnig Drab
There is a tutorial/demo page.
The point to start reading docs should be Drab.Core
.
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor
Extract Drab PID from the socket
Link to this section Types
Link to this section Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
Extract Drab PID from the socket