Generating Components

Generating Controllers

Controllers are the primary mechanism for responding to client requests. Controllers may be generated directly or as part of a scaffold that includes database schema and web pages. Before generating a controller, you must have installed an ESP skeleton that includes support for generating controllers such as: esp-skeleton, esp-html-skeleton or esp-vue-skeleton.

To generate a controller, use esp generate controller.

$ esp generate controller NAME [actions...]

This will create the named controller in the controllers directory. A controller manages requests to the web application. The controller action methods are invoked by ESP to respond to client requests and generate responses.

If no actions are requested when generating, esp will create a controller with an initialization function but without any actions. If actions are specified, esp will create an empty action method for each requested action. You can edit the controller source to meet your needs.

If you use the command:

$ esp generate controller admin edit login logout command

The following controller code will be generated. There is one function generated for each action and a call to espAction is added to register the controller. The esp_controller_admin initialization function is invoked once when the controller is first loaded.

#include "esp.h"

static void edit() {}
static void login() {}
static void logout() {}
static void command() {}

ESP_EXPORT int esp_module_admin(HttpRoute *route)
{
    cchar   *role = "user";
    espAction(route, "admin-cmd-edit", role, edit);
    espAction(route, "admin-cmd-login", role, login);
    espAction(route, "admin-cmd-logout", role, logout);
    espAction(route, "admin-cmd-command", role, command);
    return 0;
}

Generating Database Tables

Database schema can be created and modified via the esp command. This will create a database table with fields of the required types.

$ esp generate table NAME [field:type ...]

If field:type values are supplied, the database will be updated for each specified field of the requested type. The valid database types are: binary, boolean, date, datetime, decimal, float, integer, number, string, text, time, timestamp.

Generating Migrations

Database migrations are mini programs which modify the database schema or content. You can create database migrations by the "esp generate migration" command. This command generates a migration for a specific model by creating or removing tables and columns. To generate a migration:

$ esp generate migration description MODEL [field:type ...]

This will create a migration script under the migrations directory. Migration scripts filenames are time stamped and use the description as part of the filename for the migration script (so keep it short and sweet and don't use spaces!).

For each specified field:type pair, esp will generate add column code in the migration script. If the --reverse switch is specified, then remove column code will be generated. To change the type or name of a column, remove then re-add the column.

Running Migrations

Migration scripts can be run via the "esp migrate" command. Without other parameters, the command will run all migrations that have not yet been applied to the database. You can also use "esp migrate forward" to apply the next unapplied migration. Similarly, "esp migrate backward" will reverse the last applied migration. You can also use "esp migrate NNN" to migrate forward or backward to a specific migration. NNN is the migration sequence number which is the number at the start of the migration script file name.

Migrations are often under used. They are much more important than most people realize. Being able to effectively create and manage database test data greatly simplifies this aspect of development and testing.

Generating Scaffolds

Scaffolds enable you to quickly create sections of your application. A scaffold provides CRUD functionality (create, read, update and delete) for a database table. Generating a scaffold will create a database table, controller and actions to add-edit-delete. Depending on the skeleton, a set of views may also be generated that provide add, edit and list functionality for a database table. The esp-skeleton does not provide scaffold view. The esp-html-skeleton provides basic HTML view pages, and the esp-vue-skeleton provide client-side VueJS views.

To generate a scaffold:

$ esp generate scaffold NAME [field:type ...]

This will create a scaffold for the named database table and will generate a controller of the same name. If field:type values are supplied, the database will be updated with columns for each specified field of the requested type. The valid database types are: binary, bool, date, float, int, string, text. The scaffold controller will include a create, get, index, remove and update actions.