README.md

web-wombat

Framework for web services with NodeJS.

With web-wombat, you can easily set up a simple webserver in 1-2 minutes. You can also set up a WebSocket server in one minute.

For documentation see the GitHub pages site of project on the following link. https://kukko.github.io/web-wombat/

Create new project with web-wombat

npm install web-wombat -g
web-wombat init foo
cd foo
node index.js

Note: You have to generate keys to handle SSL connections in the <APP_FOLDER>/config/secureKey/ folder in key.pem and certificate.pem. But you can create project which do not listen for secure connections by adding --unsecure switch to the end of init command. It just adds an additional line to the <APP_FOLDER>/index.js which disables creation of HTTPS server.

And you have a running web-server. After that you can start creating routes, controllers, and collections to store data in database.

Note: You also can disable database by adding --without-database switch to the end of init command. It just adds an additional line to the <APP_FOLDER>/index.js which disables connection to database.

You can easily add web-wombat to an already existing project:

npm install web-wombat --save

You can create a controller with the following command:

web-wombat create controller foo

You can create a websocket controller with the following command:

web-wombat create websocket-controller foo

You can create a collection with the following command:

web-wombat create collection foo

Starting a web server with WebWombat

After you successfully installed WebWombat, you can easily start a web server.

let { WombatServer } = require('web-wombat');

WombatServer.init();

By default, WebWombat accepts secure connections, but it requires SSL certificate's private key and certification to be in config/secureKey folder in key.pem and certificate.pem files. If for some reasons you don't want to use secure connections, you can easily turn this off with the setUnsecure method of WombatServer class, before calling the init method.

let { WombatServer } = require('web-wombat');

WombatServer.setUnsecure().init();

Basically WebWombat tries to load the database configuration and connect to the database, but you can turn this behavior off with calling the static withoutDatabase method on the WombatServer class.

Here is an example:

let { WombatServer } = require('web-wombat');

WombatServer.withoutDatabase().setRoutes(require('./routes/routes.js')).init();

Basically WebWombat is listening on port 8888, but you can override this with the static setPort method.

Example to set port for listening:

let { WombatServer } = require('web-wombat');

WombatServer.setPort(1222).setRoutes(require('./routes/routes.js')).init();

Connect to database

You can easily connect to a MongoDB database (In the future there will be other database connectors.), but it's not mandatory.

mkdir config
cp node_modules/web-wombat/src/config/example-db.js config/db.js
mkdir collections

After this, you just need to fill in the parameters in the config/db.js file and WebWombat will automatically connect to the database. When connecting to the database, WebWombat will try to create collections which you created in the collections folder. A collection must extend the BaseCollection class and must implement the name method. The name method returns a string which will be the collection's name in the database.

Create routes

If you run all the commands listed at the Installation section, you have a file at routes/routes.js path. In that file, there is the requires required to create routes. The file contents are the following:

let { Route, MiddlewareProvider } = require('web-wombat');

module.exports=[
];

You can create routes for specific request methods, like GET, POST, PUT, UPDATE and DELETE.

Here are some examples for the different methods.

GET:

Route.get('/', require('../controllers/HomeController/HomeController.js'))

POST:

Route.post('/', require('../controllers/HomeController/HomeController.js'))

PUT:

Route.put('/', require('../controllers/HomeController/HomeController.js'))

UPDATE:

Route.update('/', require('../controllers/HomeController/HomeController.js'))

DELETE:

Route.delete('/', require('../controllers/HomeController/HomeController.js'))

In one controller, you can specify any method to serve a request and multiple routes can point to the same controller and to the same method, or to the same controller, but different methods. As the third parameter of the above methods, you can specify a method name, which will serve the requests. If this parameter isn't specified, then the controller's serve method will handle the request to the route.

Here is an example:

Route.get('/profile', require('../controllers/UserController/UserController.js'), 'showSelf')

You can add middlewares to be run specific for each route, by specifying an array as the fourth parameter, for the methods above. The specified middlewares run synchronously after each other, like they are ordered in the array.

Route with middlewares:

Route.get('/profile', require('../controllers/UserController/UserController.js'), 'showSelf', [
	MiddlewareProvider.getMiddleware('JwtAuthenticationMiddleware')
])

WebSocket

And you can create websocket servers with WebWombat. For this, you need to specify a route, with the Route class's websocket method.

Here is an example: Specify route:

Route.websocket('/', require('./controllers/WebSocketTestController/WebSocketTestController.js'))

Create controller for websocket:

let { WebSocketController } = require('../../../../index.js');

class WebSocketTestController extends WebSocketController{
	onOpen(){
		console.log('Connection opened!');
	}
	onMessage(message){
		console.log('Message received: ' + message);
	}
	onClose(){
		console.log('Server: connection closed!');
	}
	onError(error){
		console.log('Error occured!');
		console.log(error);
	}
}

module.exports = WebSocketTestController;

Available classes

These are just those classes and their methods which is accessible from outside of the class and you can do something with them, without the deeper knowledge of the classes.

WombatServer

WombatServer.init([function callback])

Initialize the WombatServer to listen on a port for requests.

callback: It's a function which will be called after the WombatServer started listening.

WombatServer.setUnsecure()

Disables the listening for secure connections. Must be called before init method. Basically WombatServer listening for secure connections too.

WombatServer.setSecure()

Enables the listening for secure connections. Must be called before init method. Basically WombatServer listening for secure connections too. Calling this method is only required if you previously called setUnsecure method.

WombatServer.withDatabase()

Configure WombatServer to load the database configuration and connect to the database on startup.

WombatServer.withoutDatabase()

Configure WombatServer to not try to load the database configuration and don't try to connect to database on startup.

WombatServer.setPort(mixed port)

Set the port where the WombatServer will listen for requests.

port: The port where the WombatServer will listen for requests.

WombatServer.setRoutes(Route[] routes)

Set the routes, which will be redirected to Controllers.

routes: An array of Route instances.

WombatServer.setSubfolder(string subfolder)

You can set a path where the WombatServer and the dependant classes find the resources relatively to the file, which have been started by node.

subfolder: A relative path where the required resources can be found relatively to the running script file.

BaseController

This is the class which must be the parent class of each controller.

BaseController.view(string filePath, object options, [boolean writeToResponse = true, boolean endResponse = true])

filePath: Route to the view, in the resources/views folder.

options: An object with the variables which will be accessible in the view file.

writeToResponse: If this parameter is true, the controller will write the builded template to the ServerResponse, else the controller will return a promise which's then branch will receive the builded output as first parameter.

endResponse: If this parameter is true, the controller will end the response after it's writed the builded template to it. If the writeToResponse parameter is false, then this parameter will be ignored.

BaseController.getMiddleware(string name)

This method will return the request middleware class, not an instance of the class. First this will find the middleware in the web-wombat module folder, after that in the projects middlewares folder.

name: The name of the required middleware class.

WebSocketController

This is the class which must be the parent class of each WebSocket controller. The following methods called automatically by this class and the classes which have been extends this parent class, just need to implement these classes. None of them are required to override, just optional.

WebSocketController.onOpen()

Called when a client have been connected.

WebSocketController.onMessage(string message)

Called when a client sent a message to the server.

message: Contains the message which the client have been sent to the server.

WebSocketController.onClose()

Called when a client have been disconnected from the server.

WebSocketController.onError(Error error)

Called when an error occured in the connection.

error: Contains the error which is occured in the WebSocket connection.

WebSocketController.send(mixed message)

Sends the specified message to the connected user.

message: The message to be sended to the client connected to this controller.

WebSocketController.sendTo(string uuid, mixed message)

Send the provided message to the client identified by the specified uuid.

uuid: The uuid of the client which is the target of the provided message.

message: The message to be sended to the client with the provided uuid.

WebSocketController.broadcast(mixed message)

Sends the provided message to all connected clients.

message: The message to be sended to all connected clients.

WebSocketController.getSocketTag()

If you have two controllers which have extends the WebSocketController class they shouldn't have the same name.

If you override it you should be cautious how two class which extends the WebSocketController shouldn't return the same value from this method and they don't have the same name.

Returns the tag of the WebSocket controller to be able to make more WebSocket controller in one application. The client's will be grouped by the tag returned by this method. By default it's return the name of the controller class. You shouldn't override this method.

ViewProvider

This is the class through which you can build views.

ViewProvider.setSubfolder(string subfolder)

You can set a path where the ViewProvider can find the resources relatively to the file, which have been started by node.

subfolder: A relative path where the required resources can be found relatively to the running script file.