drab v0.4.0 Drab.Commander
Drab Commander is a module to keep event handlers.
All the Drab functions (callbacks, event handlers) are placed in the module called Commander
. Think about
it as a controller for the live pages. Commanders should be placed in web/commanders
directory. Commander must
have a corresponding controller.
defmodule DrabExample.PageCommander do
use Drab.Commander
def click_button_handler(socket, dom_sender) do
...
end
end
Remember the difference: controller
renders the page while commander
works on the live page.
Event handler functions
Event handler is the function which process on request which comes from the browser. Most basically it is
done by running JS method Drab.run_handler()
. See Drab.Core
for this method description.
The event handler function receives two parameters:
socket
- the websocket used to communicate back to the page byDrab.Query
functionsargument
- an argument used in JS Drab.run_handler() method; when using Drab.Query module it is thedom_sender
map (seeDrab.Query
for full description)
Callbacks
Callbacks are an automatic events which are launched by the system. They are defined by the macro in the Commander module:
defmodule DrabExample.PageCommander do
use Drab.Commander
onload :page_loaded
onconnect :connected
ondisconnect :dosconnected
before_handler :check_status
after_handler :clean_up, only: [:perform_long_process]
def page_loaded(socket) do
...
end
def connected(socket) do
...
end
def connected(store, session) do
# notice that this callback receives store and session, not socket
# this is because socket is not available anymore (Channel is closed)
...
end
def check_status(socket, dom_sender) do
# return false or nil to prevent event handler to be launched
end
def clean_up(socket, dom_sender, handler_return_value) do
# this callback gets return value of the corresponding event handler
end
end
onconnect
Launched every time client browser connects to the server, including reconnects after server crash, network broken etc
onload
Launched only once after page loaded and connects to the server - exactly the same like onconnect
,
but launches only once, not after every reconnect
ondisconnect
Launched every time client browser disconnects from the server, it may be a network disconnect, closing the browser, navigate back. Disconnect callback receives Drab Store as an argument
before_handler
Runs before the event handler. If any of before callbacks return false
or nil
, corresponding event
will not be launched. If there are more callbacks for specified event handler function, all are processed
in order or appearance, then system checks if any of them returned false
Can be filtered by :only
or :except
options:
before_handler :check_status, except: [:set_status]
before_handler :check_status, only: [:update_db]
after_handler
Runs after the event handler. Gets return value of the event handler function as a third argument.
Can be filtered by :only
or :except
options, analogically to before_handler
Broadcasting options
Drab requests to update, insert or delete can be broadcasted. By default, broadcasts are sent to browsers
which view the same page (the same url), but it could be override by broadcasting/1
macro.
Modules
Drab is modular. You my choose which modules to use in the specific Commander by using :module
option
in use Drab.Commander
directive.
There is one required module, which is loaded always and can’t be disabled: Drab.Code
. By default, modules
Drab.Query
and Drab.Modal
are loaded. The following code:
use Drab.Commander, modules: [Drab.Query]
will override default modules, so only Drab.Core
and Drab.Query
will be available.
Every module has its corresponding JS template, which is loaded only when module is enabled.
Generate the Commander
There is a mix task (Mix.Tasks.Drab.Gen.Commander
) to generate skeleton of commander:
mix drab.gen.commander Name
See also Drab.Controller
Summary
Macros
Drab may allow an access to specified Plug Session values. For this, you must whitelist the keys of the
session map. Only this keys will be available to Drab.Core.get_session/2
Sets up the callback for after_handler. Receives handler function name as an atom and options
Sets up the callback for before_handler. Receives handler function name as an atom and options
Set up broadcasting options. It is used by Drab.Query bang functions, like update!
or insert!
Sets up the callback for onconnect. Receives handler function name as an atom
Sets up the callback for ondisconnect. Receives handler function name as an atom
Sets up the callback for onload. Receives handler function name as an atom
Macros
Drab may allow an access to specified Plug Session values. For this, you must whitelist the keys of the
session map. Only this keys will be available to Drab.Core.get_session/2
defmodule MyApp.MyCommander do
user Drab.Commander
access_session [:user_id, :counter]
end
Keys are whitelisted due to security reasons. Session token is stored on the client-side and it is signed, but not encrypted.
Sets up the callback for after_handler. Receives handler function name as an atom and options.
after_handler :event_handler_function
See Drab.Commander
summary for details.
Sets up the callback for before_handler. Receives handler function name as an atom and options.
before_handler :event_handler_function
See Drab.Commander
summary for details.
Set up broadcasting options. It is used by Drab.Query bang functions, like update!
or insert!
.
:same_url
(default) - broadcasts will go to the browsers rendering the same url:same_controller
- broadcasted message will be received by all browsers, which renders the page generated by the same controller"topic"
- any topic you want to set, messages will go to the clients sharing this topic
Sets up the callback for onconnect. Receives handler function name as an atom.
onconnect :event_handler_function
See Drab.Commander
summary for details.
Sets up the callback for ondisconnect. Receives handler function name as an atom.
ondisconnect :event_handler_function
See Drab.Commander
summary for details.
Sets up the callback for onload. Receives handler function name as an atom.
onload :event_handler_function
See Drab.Commander
summary for details.