Home Intro Source Mebo GitHub
import Web from 'mebo/src/Handlers/Web.js'
public class | source

Web

Extends:

Handler → Web

Handles the web integration through expressjs and passportjs.

It enables the execution of actions triggered by web requests. The request information is read by WebRequest, this information is passed to the action during the execution of the web handler (Web.run). The output of this handler (Web.output) is done through the WebResponse writer.

In order to tell which actions are visible by this handler, they are required to be registered beforehand via a webfication process that describes their request method, rest route and if it requires authentication.

Through decorator support:

@Mebo.grant('web', {restRoute: '/myApi/action', auth: true})
@Mebo.register('myAction')
class MyAction extends Mebo.Action{
  // ...
}

Through registration api:

Mebo.Handler.grantAction('web', 'myRegisteredAction', {restRoute: '/myApi/action', auth: true});

In case of actions that require authentication (auth: true) Mebo checks if the authentication has been executed before executing the action. Therefore, a passport authentication is required to be defined beforehand which can be done through addBeforeAuthAction:

Mebo.Handler.get('web').addBeforeAuthAction(passport);

Also, custom middlewares can be added before the execution of any action through addBeforeAction:

Mebo.Handler.get('web').addBeforeAction((req, res, next) => {...});

After the webfication process, actions can be triggered in two ways:

  • Rest support (Web.restful): Executes an action through a rest route, it happens when an action is webfied with restRoute where it becomes automatically visible as part of the restful support. In order to activated the restful support you need to tel Mebo what is the expressjs app you want to register the rest routes:

    const app = express();
    // this process registers the rest route for the webfied actions
    Mebo.Handler.get('web').restful(app);
    

    The result of webfied actions is done through the restful support is automatically by using google's json style guide. The only exceptions are readable stream and buffer that are piped to the response (Web._successOutput, Web._errorOutput).

  • Middleware support (Web.middleware): Executes an action through an arbitrary route. Actions can be executed as expressjs middlewares. It's done by using Mebo.Handler.get('web').middleware where you tell what is the action's registration name that should be executed for the express route (make sure the action has been webfied before hand). By using this feature you control the response of the request, since the result of the action is passed to the middleware:

    const app = express();
    app.get(
     '/foo',
     Mebo.Handler.get('web').middleware('myRegisteredAction', (err, result, req, res) => {
       // some sauce...
     })
    );
    

You can access a basic help page by passing help as part of the querystring. This feature generates a help page automatically for the action, for instance: http://.../?help

Express req and res

The request and the response used by this handler are available under the Session as: session.get('req') and session.get('res').

See:

Static Method Summary

Static Public Methods
public static

addBeforeAction(middleware: function)

Adds a middleware that is executed before an action.

public static

Adds a middleware that is executed before an action that requires authentication.

public static

Returns a list of middlewares which are executed before an action.

public static

Returns a list of middlewares which are executed before an action that requires auth

public static

Clears all middlewares assigned to run before actions (beforeAction)

public static

Clears all middlewares assigned to run before auth actions (beforeAuthAction)

public static

middleware(actionName: string, responseCallback: function): function

Returns a middleware designed to execute a webfied Web.webfyAction based on an arbitrary express route.

public static

restful(expressApp: Object, prefix: string)

Adds the restful support to the express app.

Static Protected Methods
protected static

_grantingAction(handlerName: string, actionName: string, options: Object)

Makes an action available for requests.

Constructor Summary

Public Constructor
public

constructor(req: Object, res: Object)

Creates a web handler

Method Summary

Public Methods
public

Returns the request object created by the express server

public

Returns the response object created by the express server

public

Sets the request object created by the express server.

public

Sets the response object created by the express server

Protected Methods
protected

_createReader(action: Action, options: Object): Reader

Creates an instance of a reader for the current handler

protected

_createWriter(value: *, options: Object): Writer

Creates an instance of a writer for the current handler.

Inherited Summary

From class Handler
public static

Removes all listeners connected to the signal emitted through Handler.onErrorDuringOutput.

public static

create(handlerName: string, mask: string, args: ...args): Handler

Creates a handler based on the registered name

public static

get(handlerName: string, handlerMask: string): Handler

Returns the registered handler

public static

grantAction(handlerName: string, actionName: string, args: ...args)

Grants the execution of the action through the handler

public static

Returns a list granted actions for the input handler

public static

Adds a listener to an exception raised during the Handler.output process.

public static

register(handlerClass: Handler, handlerName: string, handlerMask: string)

Register an Handler type to the available handlers

public static

registerReader(readerClass: Reader, handlerName: string, handlerMask: string)

Register a Reader for the handler

public static

registerWriter(writerClass: Writer, handlerName: string, handlerMask: string)

Register a Writer for the handler

public static

registeredHandler(handlerName: string, handlerMask: string): Handler

Returns the registered handler

public static

Returns a list of registered handler makers for the input handler name

public static

Returns a list containing the names of the registered handler types

public static

registeredReader(handlerName: string, handlerMask: string): Reader

Returns the reader registered for the handler

public static

registeredWriter(handlerName: string, handlerMask: string): Writer

Returns the writer registered for the handler

protected static

_grantingAction(handlerName: string, actionName: string, args: ...args)

This method can be re-implemented by derived classes to hook when an Action is granted for a handler (Handler.grantAction)

public

meta(path: string, defaultValue: *): *

Returns a value under the handler's metadata.

public

output(value: *, options: Object, finalizeSession: boolean)

Results a value through the handler.

public

async runAction(actionName: string, options: Object): *

Executes an action through the handler.

public

Returns the session

public

setMeta(path: string, value: *, merge: boolean)

Sets a value to the handler's metadata.

Detailed information about the metadata support can be found at Metadata.

public

setSession(session: Session)

Associates a Session with the handler.

protected

_createReader(action: Action, options: Object, additionalArgs: ...additionalArgs): Reader

Creates an instance of a reader for the current handler

protected

_createWriter(value: *, options: Object, additionalArgs: ...additionalArgs): Writer

Creates an instance of a writer for the current handler

Static Public Methods

public static addBeforeAction(middleware: function) source

Adds a middleware that is executed before an action.

Use this feature when you want to execute a custom middleware before the execution of an action. If you want to add a middleware for a specific web handler implementation then take a look at Web.beforeAction. All middlewares registered by this method are executed after addBeforeAuthAction.

Alternatively this method can be called directly from Mebo as Mebo.Handler.get('web').addBeforeAction(...)

In order to pass a values computed by a "before middleware" to the action you need to add the values to the handler session, so the action can read them later. The web handler is available under res.locals.web, for instance:

const web = res.locals.web;
web.session().setAutofill('customValue', 'myValue');

Where any input assigned with the autofill property 'someCustom' is going to be assigned with the 'something' value:

class MyAction extends Mebo.action{
  constructor(){
     super();
     // gets assigned with `something` value
     this.createInput('a: text', {autofill: 'customValue'});
  }
}

Params:

NameTypeAttributeDescription
middleware function

expressjs middleware that should be executed before the action

See:

public static addBeforeAuthAction(middleware: function) source

Adds a middleware that is executed before an action that requires authentication.

Use this feature when you want to execute a custom middleware before the execution of an action that requires authentication. If you want to add a middleware for a specific web handler implementation then take a look at Web.beforeAuthAction. All middlewares registered by this method are executed before addBeforeAction.

Use this feature to define the passportjs authentication middleware.

In order to pass a values computed by a "before middleware" to the action you need to add the values to the handler session, so the action can read them later. The web handler is available under res.locals.web, for instance:

const web = res.locals.web;
web.session().setAutofill('customValue', 'value');

Where any input assigned with the autofill property 'customValue' is going to be assigned with 'value':

class MyAction extends Mebo.action{
  constructor(){
     super();
     // gets assigned with `something`
     this.createInput('a: text', {autofill: 'customValue'});
  }
}

Params:

NameTypeAttributeDescription
middleware function

expressjs middleware that should be executed before an action that requires authentication

See:

public static beforeAction(): Array<function> source

Returns a list of middlewares which are executed before an action.

This method can be re-implemented by subclasses to include custom middlewares that are tied with a specific web handler implementation. By default it returns the middlewares added through Web.addBeforeAction

Return:

Array<function>

public static beforeAuthAction(): Array<function> source

Returns a list of middlewares which are executed before an action that requires auth

This method can be re-implemented by subclasses to include custom middlewares that are tied with a specific web handler implementation. By default it returns the middlewares added through Web.addBeforeAuthAction

Return:

Array<function>

public static clearBeforeAction() source

Clears all middlewares assigned to run before actions (beforeAction)

public static clearBeforeAuthAction() source

Clears all middlewares assigned to run before auth actions (beforeAuthAction)

public static middleware(actionName: string, responseCallback: function): function source

Returns a middleware designed to execute a webfied Web.webfyAction based on an arbitrary express route. Differently from Web.restful this method does not response the request, instead it's done through the responseCallback which passes the action error, result and the default middleware express arguments, for instance:

const app = express();
app.get(
   '/foo',
   Mebo.Handler.get('web').middleware('myRegisteredAction', (err, result, req, res) => {
     // ...
   })
);

Params:

NameTypeAttributeDescription
actionName string

registered action name

responseCallback function
  • optional

optional response callback that overrides the default json response. The callback carries the express: function(err, result, req, res, next){...}

Return:

function

public static restful(expressApp: Object, prefix: string) source

Adds the restful support to the express app.

It works by registering the rest routes for the webfied visible actions (Web.webfyAction) to the express app. The response of actions executed through the rest support is done via the output method.

const app = express();
Mebo.Handler.get('web').restful(app);

or

const app = express();
Mebo.Handler.get('web').restful(app, '/api'); // adding a prefix for the rest routes

Params:

NameTypeAttributeDescription
expressApp Object

expressjs application instance

prefix string
  • optional

optional prefix that gets included in the registration of the rest routes

Static Protected Methods

protected static _grantingAction(handlerName: string, actionName: string, options: Object) source

Makes an action available for requests.

By doing that the action gets visible for the restful and middleware support.

This method is called during Mebo.Handler.grantAction('web', ...)

Override:

Handler#_grantingAction

Params:

NameTypeAttributeDescription
handlerName string

registered handler name

actionName string

registered action name

options Object

custom options

options.method string | Array<string>
  • optional
  • default: 'get'

tells the request method about how the action should be available, for instance: get, post, put, delete (...). Multiples methods can be defined through an array of method names

options.auth boolean
  • optional
  • default: null

boolean telling if the action requires authentication when set to null (default) this information is driven by the setting ⚠ handler/web/requireAuthByDefault (default: false).

options.restRoute string
  • optional

the rest route from which the action should be executed from the restful support. You can use route parameters as well that later are translated to input values to further information take a look at (WebRequest).

Public Constructors

public constructor(req: Object, res: Object) source

Creates a web handler

Override:

Handler#constructor

Params:

NameTypeAttributeDescription
req Object

request object

res Object

response object

Public Methods

public request(): Object source

Returns the request object created by the express server

Return:

Object

See:

public response(): Object source

Returns the response object created by the express server

Return:

Object

See:

public setRequest(req: Object) source

Sets the request object created by the express server.

It also includes the request as part of the session: session.get('request')

Params:

NameTypeAttributeDescription
req Object

request object

See:

public setResponse(res: Object) source

Sets the response object created by the express server

It also includes the response as part of the session: session.get('response')

Params:

NameTypeAttributeDescription
res Object

response object

See:

Protected Methods

protected _createReader(action: Action, options: Object): Reader source

Creates an instance of a reader for the current handler

This passes the Web.request to the reader.

Override:

Handler#_createReader

Params:

NameTypeAttributeDescription
action Action

action instance used by the reader to parse the values

options Object

plain object containing the options passed to the reader

Return:

Reader

protected _createWriter(value: *, options: Object): Writer source

Creates an instance of a writer for the current handler.

This passes the Web.response to the reader and the request.query.context as an option to the writer.

Override:

Handler#_createWriter

Params:

NameTypeAttributeDescription
value *

arbitrary value passed to the writer

options Object

plain object containing the options passed to the writer

Return:

Writer