This documentation is for a pre-release version of SimpleMVC.js. Any of the function signatures can change from one commit to the next, and may fall out of sync with this documentation.
-
Install the
simplemvcjspackage from npm (or download it manually).npm install simplemvcjs -
Create the reference to SimpleMVC by requiring the package
const SimpleMVC = require('simplemvcjs');
The App class is the foundation of SimpleMVC.js.
It encapsulates the http server, controller routing, sessions, static files, and database initialization.
Initializes the various components for the base application to function.
var app = new SimpleMVC.App();Adds the individual controller routes to the http server.
app.addControllers(homeController, newsController, authController, accountController);NOTE: If the same route is defined in multiple actions only the first one is executed.
Creates an http server that listens on http://{host}:{port}.
app.listen('example.com', 8080);NOTE: If
hostorportparameters are falsey, theHOSTorPORTenvironment variables will be used.
Initializes the MongoDB database connection, and mongoose data context using the MONGO_* environment variables.
app.initDbConnection();Intializes the Session middleware.
app.initSessions();NOTE: If the database connection has been previously intialised, session state will be stored in the collection
simple_sessions, otherwise it will be stored only in memory.
NOTE: due to a known/purposeful memory leak in the default memory store used by
express-sessionit is recommended that you initialize the database first in a production environment. This also gives you an added bonus of being able to scale your application horizontally as well.
Adds a file route for http://{host}:{port}/* to be run after no other routes are found. This route will then look for files to be delivered stored at the path provided by the path parameter (absolute or relative to application root).
app.initStaticFiles('static');NOTE: Prior to version 0.9.7 This should be called only AFTER all controllers have been added.
The Controller class contains the logic for creating containered routes.
Initializes the routes for a controller.
The optional routes parameter takes a dictionary where the key is a path relative to the basePath parameter, and the value is either a function, or another dictionary with an HTTP VERB for the key and a function for the value.
const homeController = new SimpleMVC.Controller('/', {
"": function(req) {
return this.text("hello, world!");
},
"name": {
post: function(req) {
return this.text(`hello, {req.fields.name}!`);
}
}
});The beforeRoute property is a function that can be overwritten to provide logic that will be called prior to every route in the controller executing.
adminController.beforeRoute = function(req) {
if(!req.session.user || !req.session.user.profile.isAdmin)
return this.redirect('/auth/login');
}Just like the constructor, the routes parameter takes a dictionary where the key is a path relative to the basePath parameter, and the value is either a function, or another dictionary with an HTTP VERB for the key and a function for the value.
This function could be useful if you want to optionally add routes based on a configuration.
if(process.env.ADMIN_DIAGNOSTICS) {
adminController.addRoutes({
"diagnostics": function(req) {
const report = adminService.getDiagnosticsReport();
return this.view('diagnostics', report);
}
})
}Returns an application/json response with the json object provided in the data parameter.
The optional status parameter defaults to 200 OK.
return this.json({
someProperty: 'some value'
});Returns an HTTP 302 Redirect to the url/path provided in the url paremeter.
The redirect url can be:
-
A fully qualified
URIreturn this.redirect('https://google.com');
-
An absolue path
return this.redirect('/auth/login');
-
A relative path
return this.redirect('../new');
Returns a text/plain response with text parameter as the body of the response.
The optional status parameter defaults to 200 OK.
return this.text('hello world')Returns a mustache rendered view bound to the object in the model parameter.
return this.view('index', {name: request.fields.name});The Membership service contains various helper methods for enabling authentication on an application.
NOTE: The Membership service requires the database to be initialized, and stores users in the
simple_userscollection.
Most functions return a User object, which is defined as:
{
id: ObjectId,
email: String,
profile: { String: String }
}Initializes the Membership service and underlying database model.
Creates a user. Returns the new user if creation was successful.
Delete a user from the collection.
Retrieve a user from the collection by their id.
Retrieve a user from the collection by their email.
Updates the user's email.
Updates the user's password.
Updates the user's profile.
NOTE: Only updates the properties that are passed in. Currently there is no way to delete a profile property.
Returns the user if the email and password match what is in the database.
User activation is optional. It creates 2 user profile properties called activationCode and activatedOn. If you wish to use the built in activation, do not override these values.
Sends an activation email to the email address in the collection for the user. The email is sent through the SMTP Service. The email is rendered from the mustache markup passed in through the template parameter.
const user = membership.addUser(req.fields.email, req.fields.password, { name: req.fields.name });
if(user)
membership.sendActivation(user.id, 'John Q. Public <jqp@example.com>', 'Activate your account', 'Here is your activation code: {{activationCode}}');NOTE: Uses the SMTP Service, so it requires the
SMTP_*environment variable to have been set.
Attempts to activate the user's account by matching the activationCode parameter to the user.profile.activationCode property. Returns true if successful.
...
"activate": {
get: function(req) {
if(membership.activateUser(req.query.email, req.query.activationCode)) {
return this.view('activation/success');
}
return this.view('activation/error');
}
}
...