Web
Extends:
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')
.
Static Method Summary
Static Public Methods | ||
public static |
addBeforeAction(middleware: function) Adds a middleware that is executed before an action. |
|
public static |
addBeforeAuthAction(middleware: function) 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 |
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 |
setRequest(req: Object) Sets the request object created by the express server. |
|
public |
setResponse(res: Object) 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 |
Creates a handler based on the registered name |
|
public static |
Returns the registered handler |
|
public static |
grantAction(handlerName: string, actionName: string, args: ...args) Grants the execution of the action through the handler |
|
public static |
grantedActionNames(handlerName: string): Array<string> Returns a list granted actions for the input handler |
|
public static |
onErrorDuringOutput(listener: function) Adds a listener to an exception raised during the Handler.output process. |
|
public static |
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 |
registeredHandlerMasks(handlerName: string): Array<string> 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 |
Returns a value under the handler's metadata. |
|
public |
Results a value through the handler. |
|
public |
Executes an action through the handler. |
|
public |
Returns the session |
|
public |
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:
Name | Type | Attribute | Description |
middleware | function | expressjs middleware that should be executed before the action |
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:
Name | Type | Attribute | Description |
middleware | function | expressjs middleware that should be executed before an action that requires authentication |
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
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
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) => {
// ...
})
);
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
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#_grantingActionParams:
Name | Type | Attribute | Description |
handlerName | string | registered handler name |
|
actionName | string | registered action name |
|
options | Object | custom options |
|
options.method | string | Array<string> |
|
tells the request method about how the action should
be available, for instance: |
options.auth | boolean |
|
boolean telling if the action requires authentication
when set to |
options.restRoute | string |
|
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 Methods
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:
Name | Type | Attribute | Description |
req | Object | request object |
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:
Name | Type | Attribute | Description |
res | Object | response object |
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#_createReaderprotected _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#_createWriterParams:
Name | Type | Attribute | Description |
value | * | arbitrary value passed to the writer |
|
options | Object | plain object containing the options passed to the writer |