Class: Brut::FrontEnd::Handler

Inherits:

Object

• Object
• Brut::FrontEnd::Handler

Includes:

Brut::Framework::Errors, HandlingResults

Defined in:

lib/brut/front_end/handler.rb

Overview

A handler responds to all HTTP requests other than those that render a page. Like a page, the handler is initialized with any of the data it needs. The #handle method will be called to perform whatever action is needed, and its return value will determine what ther esponse will be.

To create a handler, after defining a route or form, subclass this class (or, more likely, your app's AppHandler) and provide an initializer that accepts keyword arguments. The names of these arguments will be used to locate the values that Brut will pass in when creating your page object. If your handler is for a form, be sure to include the form: keyword argument.

Consult Brut's documentation on keyword injection to know what values you may use and how values are located.

Then, implement #handle to perform whatever logic is needed to handle the request.

You may also define before_handle which will be called before #handle to potentially abort the request. This is mostly useful if you have a base class for some of your handlers and want to share cross-cutting logic.

Note that the public API for handlers is #handle!, which is what you should call in a test.

Direct Known Subclasses

Brut::FrontEnd::Handlers::CspReportingHandler, Brut::FrontEnd::Handlers::InstrumentationHandler, Brut::FrontEnd::Handlers::LocaleDetectionHandler, Brut::FrontEnd::Handlers::MissingHandler

Instance Method Summary

• #before_handle ⇒ URI|Brut::FrontEnd::Component, ...

  Override this to performa any checks before #handle is called.

• #handle ⇒ URI|Brut::FrontEnd::Component, ...

  You must implement this to accept whatever parameters you need.

• #handle!(**args) ⇒ Object

  Called by Brut to handle the request.

Methods included from Brut::Framework::Errors

#abstract_method!, #bug!

Methods included from HandlingResults

#http_status, #redirect_to

Instance Method Details

#before_handle ⇒ URI|Brut::FrontEnd::Component, ...

Override this to performa any checks before #handle is called. This should return nil if #handle should proceed to be called. Generally, you don't need to override this as #handle can include the logic. Where this is useful is to share cross-cutting logic across other handlers.

Returns:

• (URI|Brut::FrontEnd::Component, Array, Brut::FrontEnd::HttpStatus, Brut::FrontEnd::Download) —

  See #handle for what each return value means.

# File 'lib/brut/front_end/handler.rb', line 49

def before_handle = nil

#handle ⇒ URI|Brut::FrontEnd::Component, ...

You must implement this to accept whatever parameters you need. See RequestContext for how that works. The type of the return value determines what will happen:

• Instance of URI - browser will redirect to this URI. Typically, you would do this by calling Brut::FrontEnd::HandlingResults#redirect_to.
• Instance of Component (which notably includes Page) - renders that component or page
• Array of two items, with the first being an Instance of Component and the second being an Brut::FrontEnd::HttpStatus - renders that component or page, but responds with the given HTTP status. Useful for Ajax requests that don't return 200, but do return useful content.
• Instance of Brut::FrontEnd::HttpStatus - returns just that status code. Typically you would do this by calling Brut::FrontEnd::HandlingResults#http_status
• Instance of Download - sends a file download to the browser.
• Instance of GenericResponse - sends itself as the rack response. Use this only if you cannot use one of the other options

Returns:

• (URI|Brut::FrontEnd::Component, Array, Brut::FrontEnd::HttpStatus, Brut::FrontEnd::Download)

# File 'lib/brut/front_end/handler.rb', line 38

def handle(**)
  abstract_method!
end

#handle!(**args) ⇒ Object

Called by Brut to handle the request. Do not override this. If your handler responds to before_handle that is called with the same args as you have defined for #handle. If before_handle returns anything other than nil, that value is returned and should be one of the values documented in #handle. If before_handle returns nil, #handle is called and whatever it returns is returned here.

# File 'lib/brut/front_end/handler.rb', line 55

def handle!(**args)
  result = nil
  result = self.before_handle
  if result.nil?
    result = self.handle(**args)
  end
  result
end