Application Generator — mvc

Ejscript provides an application generator and manager, called mvc. This tool makes it easier and quicker to create and manage your web applications. The mvc command generates Ejscript web applications, database migrations, database models, scaffolds and views.

Mvc will create directories and generate configuration and source code files which can then be manually edited as required. Mvc is intelligent and will not overwrite existing files, so you can safely edit and regenerate without losing your changes. You can overwrite your changes if you wish to by using the --overwrite switch.

Mvc can also be used to run your application by invoking a configured web server.

Generating Applications

To start a new web application, run mvc to create the application directory and generate the essential application configuration and script files. For example:

mvc generate app myApp

Created Directories

This will create the following directories. Most of these directories are initially empty, but may be used over time. Ejscript follows conventions where specific files are stored. This greatly simplifies configuring a web application.

Directory	Purpose
cache	Compiled views and web pages
controllers	Controller source
db	Databases and scripts
db/migrations	Database migration scripts
layouts	View layout files
models	Database model code
src	Extra application source code
static	Static web page directory
static/images	Static images
static/js	Client side JavaScripts
Application/themes	Application HTML themes
views	View source files

Mvc will also create some files which have the following meaning:

Files	Purpose
controllers/Base.es	Application base controller class
ejsrc	Application configuration file
layouts/default.ejs	Default layout web page
static/themes/default.css	Default theme CSS file
static/layout.css	Default layout CSS file

Generating Controllers

Controllers are the primary mechanism for responding to client requests. To generate a controller:

mvc generate controller NAME [actions...]

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

If no actions are requested, mvc will create a default index action method. If other actions are requested, mvc 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:

mvc generate controller Admin edit login logout command.

The following controller code will be generated.

public class AdminController extends BaseController {
    function AdminController() { 
    }
    action function edit() {
    }
    action function login() {
    }
    action function logout() {
    }
}

Generating Models

Database models are Ejscript classes that encapsulate database data and provide access methods. They provide a conduit to interact with the database. To generate a model:

mvc generate model MODEL [field:type ...]

This will create a database model and will generate a model class under the models directory. It will also create a database migration to create a database table of the same name as the model.

If field:type values are supplied, the database migration will include code to create a column 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 Scaffolds

A scaffold is a generated database migration, database model, controller and a set of views that provide add, edit and list functionality for a database model. Scaffolds are useful to quickly generate prototype web pages and actions for managing a database table. To generate a scaffold:

mvc generate scaffold MODEL [field:type ...]

This will create a scaffold for the database model and will generate a controller of the same name. If field:type values are supplied, the database migration will include code to create a database column 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. The scaffold will include an edit action and view page that provides add and edit capability. The list action and view, provides the ability to list the database table rows and select an entry to edit.

You can use the --apply switch to apply the generated database migration and upgrade the database.

Generating Migrations

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

mvc generate migration description MODEL [field:type ...]

This will create a migration script under the db/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).

For each specified field:type pair, mvc 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 "mvc migrate" command. Without other parameters, the command will run all migrations that have not yet been applied to the database. You can also use "mvc migrate forward" to apply the next unapplied migration. Similarly, "mvc migrate backward" will reverse the last applied migration. You can also use "mvc 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.

Compiling

Ejscript compiles models, views and controllers into Ejscript byte code modules. These are then loaded and run by Ejscript in response to incoming client requests. Code is compiled only once but can be run many times to service incoming requests.

In development mode, Ejscript will automatically compile the relevant portions of the application if the source code is modified. It can intelligently recompile views, actions, controllers and database models as required. However, you can also explicitly recompile portions or the complete application.

Compile Everything

Mvc can recompile everything via:

mvc compile ...

This will compile each controller and view and also recompile the application and module source code. Module files for each component will be generated.

Compile Views and Controllers

Mvc also provides options for you to individually compile controllers and views. To recompile named views or controllers:

mvc compile view NAMES...
mvc compile controller NAMES...

When compiling views, you can use the --keep switch to preserve the intermediate generated Ejscript source file. This can sometimes be helpful for debugging.

Compile Models and Application Code

Models are compiled with application code into a single module file. To recompile the models and application source code:

mvc compile app

Compile Application as One Module

To compile the entire application and produce a single module file:

mvc compile all

Compile Stand-Alone Web Pages

To compile stand-alone Ejscript web pages:

mvc compile path/name.ejs...

Running

To run your application:

mvc run

This requires that your config/config.ecf file be modified to define command to run your web server.

Cleaning

To clean all generated module files:

mvc clean

Command Options

Mvc has the following command usage patterns:

mvc clean
mvc compile [all | app | controller names... | model names... | view names...]
mvc compile path/name.ejs...
mvc generate app name
mvc generate controller name [actions...]
mvc generate migration description model [field:type...]
mvc generate model name
mvc generate scaffold model [field:type ...]
mvc migrate [forward|backward|NNN]
mvc run

Switch	Description
--apply	Apply the database migration when generating a scaffold. This is the same as running mvc migrate.
--database connector	Select a database connector to use. Currently, this switch is not implemented and sqlite is the only connector supported.
--keep	Preserve generated intermediate Ejscript source files. These files are generated when blending views with layout pages.
--layout layoutPage	Change the name of the default layout page if a view does not explicitly specify a layout page.
--overwrite	Overwrite existing files. Mvc normally will not overwrite existing files. This is to preserve user changes to previously generated files.
--reverse	Reverse the operation when generating a migration. Instead of adding tables or columns, this switch will modify the migration to remove them.
--quiet or -q	Run quietly and don't trace actions to the console.
--verbose or -v	Run in verbose mode and trace actions to the console (default).