drab v0.3.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 by Drab.Query functions
  • argument - an argument used in JS Drab.run_handler() method; when using Drab.Query module it is the dom_sender map (see Drab.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

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

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

access_session(session_keys)

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.

after_handler(event_handler, filter \\ [])

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.

before_handler(event_handler, filter \\ [])

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.

onconnect(event_handler)

Sets up the callback for onconnect. Receives handler function name as an atom.

onconnect :event_handler_function

See Drab.Commander summary for details.

ondisconnect(event_handler)

Sets up the callback for ondisconnect. Receives handler function name as an atom.

ondisconnect :event_handler_function

See Drab.Commander summary for details.

onload(event_handler)

Sets up the callback for onload. Receives handler function name as an atom.

onload :event_handler_function

See Drab.Commander summary for details.