MOST Web Framework 2.0 Codename Blueshift Web Module
The new version of MOST Web Framework comes with a set of new features for building modern data-driven web applications and services.
Install @themost/web
npm i @themost/web
This repo is a submodule of MOST Web Framework
git clone http://github.com/themost-framework/themost.git
Install MOST Web Framework CLI globally:
npm install @themost/cli -g
and generate a new project by executing:
themost generate new project <project name>
where [project name] is the name of the project which is going to be generated e.g.
themost generate new project test-app
MOST Web Framework approaches a web application structure with a wind set of naming conventions. So, a classic application structure seems like:
+ app
+ assets
...
+ vendor
...
+ server
+ controllers
root-controller.js
+ config
+ models
Thing.json
User.json
Group.json
...
app.json
routes.json
+ views
+ root
index.html.ejs
+ shared
master.html.ejs
Navigate to new project directory and start application by executing:
npm run serve
Controllers are classes which handle requests and are stored in server/controllers directory.
//# server/controllers/hello-controller.js
import HttpBaseController from '@themost/web/controllers/base';
import {httpController,httpGet, httpAction} from '@themost/web/decorators';
@httpController()
export default class RootController extends HttpBaseController {
constructor(context) {
super(context);
}
/**
* GET /hello.html
* @returns {Promise<any>}
*/
@httpGet()
@httpAction('hello')
hello() {
return Promise.resolve({
"message": "Hello World!"
});
}
}
Generate a new controller by executing the following command:
themost generate controller <controller name>
e.g.
themost generate controller Test
This command will generate a new controller in server/controllers/test-controller.js. The new module exports a default class named TestController. TestController class extends HttpBaseController class which is one of the available controller classes of @themost. The framework uses the above naming convention (test-controller) to identify an HTTP controller available to handle requests.
@themost uses EcmaScript decorators for defining HTTP controllers actions and methods. An HTTP controller class has @httpController() decorator to let framework identify it as a valid HTTP controller.
@httpController()
export default class RootController extends HttpBaseController
...
An instance method of an HTTP controller may be marked as an HTTP action by defining one or more of the available decorators for HTTP actions.
@httpGet()
@httpAction('hello')
hello() {
return Promise.resolve({
"message": "Hello World!"
});
}
These decorators are:
- @httpGet() to handle GET requests
- @httpPost() to handle POST requests
- @httpPut() to handle PUT requests
- @httpDelete() to handle DELETE requests
- @httpPatch() to handle PATCH requests
- @httpHead() to handle HEAD requests
@httpAction() decorator is used to define an HTTP action name
@httpGet()
@httpAction('hello')
hello() {
...
}
The result of an HTTP action may be an instance of HttpResult class or any other class which derives from HttpResult class.
Returns a application/json result
@httpGet()
@httpAction('hello')
hello() {
return this.json({
"message": "Hello World!"
});
}
Returns an application/xml result
@httpGet()
@httpAction('hello')
hello() {
return this.xml({
"message": "Hello World!"
});
}
Returns a text/html content result
@httpGet()
@httpAction('hello')
hello() {
return this.view(`
<h2>Hello World!</h2>
`);
}
Returns a text/html result
@httpGet()
@httpAction('hello')
hello() {
return this.view({
"message": "Hello World!"
});
}
Returns a content result based on the mime type of the physical file
@httpGet()
@httpAction('hello')
hello() {
return this.file(path.resolve(process.cwd(),'./app/assets/hello.pdf'));
}
Redirects the current HTTP request
@httpGet()
@httpAction('hello')
hello() {
return this.redirect('/login.html');
}
@themost uses a set of view engines for rendering content:
EJS View Engine
based on Embedded JavaScript templates
<div class="container">
<div class="row">
<div class="col-lg-12 text-center">
<h2 class="mt-5"><%=model.message%></h2>
</div>
</div>
</div>
Vash View Engine
based on Vash, Razor syntax, for JavaScript templates
<html lang="en">
<head><title>MOST Web Framework</title></head>
<body>
<h2>@model.message</h2>
</body>
</html>
Jade View Engine
based on Pug – robust, elegant, feature rich template engine for Node.js
doctype html
html(lang="en")
head
title MOST Web Framework
body
h2= model.message
AngularJS for Server
@themost presents an new template engine based on the popular AngularJS 1.x framework This template is running in paraller with other templates engines and allows the use of AngularJS in server-side rendering.
The following example contains an AngularJS server module and a simple directive which includes a hello message in an element:
//# server/modules/server-app.js
/**
* Initializes angular server application
* @param angular
*/
export function bootstrap(angular) {
let serverExtensions = angular.module('server-extensions',[]);
serverExtensions
.directive('serverHello', function() {
return {
restrict: 'A',
scope: {
serverHello: '='
},
link: function (scope, element) {
element.html(scope.serverHello);
}
};
});
return angular.module('server',['server-extensions']);
}
Include the following html markup:
<p server-hello="'This is a hello message from server application'"></p>
e.g.
<div class="container">
<div class="row">
<div class="col-lg-12 text-center">
<h2 class="mt-5"><%=model.message%></h2>
<p server-hello="'This is a hello message from server application'"></p>
</div>
</div>
</div>
and start using AngularJS directives in any server-side view.
The result of an HTTP action may be also a Promise of any object (including an instance of HttpResult class).
@httpGet()
@httpAction('hello')
hello() {
return Promise.resolve({
"message": "Hello World!"
});
}
or
@httpGet()
@httpAction('hello')
hello() {
return new Promise((resolve, reject) => {
//...
return resolve({
"message": "Hello World!"
});
});
}
MOST Web Framework holds application routings in server/config/routes.json file.
[
{
"url": "/?",
"controller": "root",
"action": "index"
},
{
"url": "/:action.html",
"controller": "root",
"format": "html"
},
{
"url": "/:action.json",
"controller": "root",
"format": "json"
},
{
"url": "/:action.xml",
"controller": "root",
"format": "xml"
},
{
"url": "/{controller:plural}/?",
"action": "index"
},
{
"url": "/{controller:plural}/:action.html",
"format": "html"
},
{
"url": "/{controller:plural}/:action.json",
"format": "json"
},
{
"url": "/{controller:plural}/:action.xml",
"format": "xml"
}
]
An application route may have a set of parameters that are defined with a colon followed by parameter name e.g. /test/:id/edit.html
{
"url": "/:action.html",
"controller": "root",
"format": "html"
}
The example above defines an application route for each action of RootController. The static parameter [controller] defines the controller which is going to serve the action. The [action] parameter defines the target action. The [format] parameter defines the content-type of the action result.
Any application route may have typed route parameters.
/users/{id:int}/edit.json
This route defines a parameter named [id] which it must be an integer. Any other value will be ignored. Typed route parameters are:
| Format | Type |
|---|---|
| {param:int} | Defines an integer parameter (e.g. /users/12450/edit.json ) |
| {param:boolean} | Defines a boolean parameter |
| {param:float} | Defines a float parameter |
| {param:guid} | Defines a GUID parameter e.g. /users/2812EAEE-29C5-4810-AD9C-E6A50E97DE40/edit.json is served based on the following route: /users/{id:guid}/edit.json |
| {param:plural} | Defines a string parameter that is used with its plural. This typed parameter is used for controller names e.g. /users/100/edit.html is served based on /{controller:plural}/{id:int}/edit.html where finally controller parameter is "user". |
| {param:date} | Defines a DateTime parameter wrapped in single quotes e.g. /orders/calculate('2018-02-01') is served based on the following route: /orders/calculate\({targetDate:date}\) |
| {param:string} | Defines a string parameter wrapped in single quotes e.g. /users('admin@example.com')/edit.json is served based on the following route: /users\({email:date}\)/edit.json |
Route parameters may be passed as action arguments.
import HttpBaseController from '@themost/web/controllers/base';
import {httpController,httpGet, httpAction} from '@themost/web/decorators';
@httpController()
export default class TestController extends HttpBaseController {
constructor(context) {
super(context);
}
...
@httpGet()
@httpAction('multiply')
multiply(a, b) {
return Promise.resolve({
result: a * b
});
}
...
}
The TestController.multiply(a,b) has two float arguments. A route for this action may be:
{
"url": "/test/multiply\\({a:float},{b:float}\\)",
"controller": "test",
"action": "multiply",
"format": "json"
}
An HTTP request on /test/multiply(4.5,5.5) will produce the following response:
{
"result": 24.75
}
Any other request (like /test/multiply(x,5.5)) will fail with 404 Not Found HTTP result
An HTTP controller action may validate any parameter with @httpParam decorator. This powerfull decorator allows a final parameter validation before the execution of an HTTP action.
import HttpBaseController from '@themost/web/controllers/base';
import {httpController,httpGet, httpAction} from '@themost/web/decorators';
@httpController()
export default class TestController extends HttpBaseController {
constructor(context) {
super(context);
}
...
@httpGet()
@httpParam({ name: "b", type:"NonNegativeNumber" })
@httpParam({ name: "a", type:"NonNegativeNumber" })
@httpAction('multiply')
multiply(a, b) {
return Promise.resolve({
result: a * b
});
}
...
}
In this case any HTTP request where a or b parameter is a negative number (e.g. /test/multiply(-2.5,5.5)) will fail with 400 Bad Request HTTP error.
Note: @httpParam() decorators must be placed in reverse order.
An @httpParam decorator may have the following attributes
| Attribute | Description |
|---|---|
| name | Defines the argument name |
| type | Defines the argument type based on application defined types (e.g. Integer, NonNegativeInteger, PositiveInteger, Email, Date, DateTime, Number etc.) |
| required | Indicates whether this parameter is required or not even if this is not described in application route |
| minLength | Defines the minimum length of a parameter |
| maxLength | Defines the maximum length of a parameter |
| minValue | Defines the minimum value for the given parameter |
| maxValue | Defines the maximum value for the given parameter |
| message | Defines a validation message for this parameter |
| pattern | Defines a regular expression for the given parameter |
A @themost web application may serve static files. HttpApplication#useStaticContent(contentPath) enables the serving of static files of the specified directory.
//# server/server.js
import {HttpApplication} from '@themost/web/app';
import path from 'path';
import {TraceUtils} from '@themost/common/utils';
import {AngularServerModule} from "@themost/web/angular/module";
import {LocalizationStrategy, I18nLocalizationStrategy} from "@themost/web/localization";
//initialize app
let app = new HttpApplication(path.resolve(__dirname));
...
//use static content
app.useStaticContent(path.resolve('./app'));
...