Quick Nav
See Also
Application Generator — esp
The ESP web framework provides an application generator and building tool named in the esp program. This tool makes it easy and quick to create and manage your web applications. The esp command generates MVC web applications, database schema, scaffolds and views. The esp command can be used to run your application by invoking the Appweb web server and it can be used to pre-compile controllers, views and web pages.
The esp program is not just for MVC applications. It can be used to pre-compile stand-alone ESP web pages too.
Generating Applications
To start a new web application, run esp to create the application directory and generate the essential application configuration and script files. For example:
esp generate app blog
The esp command will create directories and generate configuration and source code files which can then be manually edited as required. The esp command 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.
Created Directories
The esp command will create some standard directories when generating an application. Some of these directories are initially empty, but may be used over time. ESP follows conventions where specific files are stored. This greatly simplifies configuring and managing web applications.
Directory | Purpose |
---|---|
cache | Cached modules and views |
controllers | Controller source |
db | Databases and scripts |
layouts | Layout template pages |
views | View source files |
static | Static web content |
static/images | Client side JavaScripts |
static/js | Client side JavaScripts |
static/themes | Application HTML themes |
The esp command will also create some files which have the following meaning:
Files | Purpose |
---|---|
appweb.conf | Appweb startup configuration file |
static/themes/default.css | Default theme CSS file |
static/layout.css | Default layout CSS file |
layouts/default.esp | Default layout template page |
Generating Controllers
Controllers are the primary mechanism for responding to client requests. To generate a controller:
esp 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 ESP to respond to client requests and generate responses.
If no actions are requested, esp will create a default index action method. If other actions are requested, 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 espDefineAction is added to register the controller. The esp_controller_admin initialization function is invoked once when the controller is first loaded.
/* admin controller */ #include "esp.h" static void edit() {} static void login() {} static void logout() {} static void command() {} ESP_EXPORT int esp_controller_admin(EspRoute *eroute, MprModule *module) { espDefineAction(eroute, "admin-edit", edit); espDefineAction(eroute, "admin-login", login); espDefineAction(eroute, "admin-logout", logout); espDefineAction(eroute, "admin-command", 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 Scaffolds
Scaffolds enable you to quickly create sections of your application. A scaffold provides CRUD (create, read, update and delete) functionality for a database table. Generating a scaffold will create a database table, controller and a set of views that provide add, edit and list functionality for a database table. Scaffolds are useful to quickly generate prototype web pages and actions for managing a database table. 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 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.
Compiling
ESP compiles views and controllers into native machine code libraries. These are automatically compiled in response to client requests and are then loaded and run by ESP to serve the relevant response. Code is compiled only once but can be run many times to service incoming requests.
ESP will automatically recompile controllers, views and web pages, however you can also source code is modified. It can intelligently recompile views and controllers as required. However, you can also explicitly pre-compile portions or the complete application via the esp command.
Compile Everything
The esp command can recompile the entire application via:
esp compile
This will compile and link all controllers and views and place the generated shared libraries (DLLs) in the cache directory.
If you are using static linking, use the --static switch to generate archive libraries instead of shared libraries. If you are doing this, you must manually call the ESP initializers. See the --genlink option for how to generate the code to call the ESP initializers.
Routes
When esp is invoked it, loads the appweb.conf configuration file from the current directory. If not found, esp will search up the parent directories for an appweb.conf file to use. The --config option may also contain a full path to an appweb.conf file.
An appweb.conf file may contain directives for one more more applications. It will usually contain many routes for various URIs. When esp compile is invoked, esp will compile the resources managed by each of the ESP routes specified in the Appweb configuration file.
Filtering
If esp compile is invoked with one or more paths on the command line, these paths will act as filters such that only the designated paths will be compiled. For example:
esp compile web/test.esp esp compile myapp esp compile views esp compile /path/to/my/app esp compile /directory/of/apps
These paths are interpreted as filenames relative to the current directory. If a controller, view or web page filename is provided, only that resource will be compiled. If a directory that is part of an MVC application is provided, then all resources under that directory will be compiled. If a directory that is a parent directory of ESP applications or web pages, then all those resources contained by that directory will be compiled.
You may also use the --routeName or --routePrefix switches to select a specific route in the appweb.conf configuration file. Then only the resources managed by that route will be compiled.
Keep Source
When compiling views or web pages, the EspKeepSource configuration file directive will control if the intermediate C source code generated from the ESP will be preserved. This can sometimes be helpful for debugging.
Compile Application as One Module
For deployment in a production environment, it can be useful to compile the entire application including all controllers, views and web pages into a single module file. Use the --flat esp option to achieve this:
esp --flat compile
If you compile flat, you will need to add an EspLoad directive to the appweb.conf. This tells ESP to pre-load the application and where to locate the module file.
EspLoad NAME PATH
When using dynamic linking, appweb automatically invokes the necessary ESP initializers when running ESP pages or invoking ESP controllers. However, if you are using static linking, you need to manually call these ESP initializers. You can generate the necessary initialization calls via the esp --genlink slink.c switch. The generated code should be linked with your appweb main program replacing the default slink.c file.
esp --flat --static --genlink slink.c
Cross Compiling
When esp compile is invoked, it selects its compile and link rules from the esp.conf configuration file. This file, which may be customized, contains the rules for various operating systems and CPU architectures. The esp.conf file is included automatically when the ESP handler is added.
By default, the current system configuration is selected if not cross compiling. If cross-compiling, the configuration for the target host specified via the Appweb configure program is utilized.
The esp command can select alternate compile and link configurations via the --platform switch. For example:
esp --platform vxworks-arm-debug
This will compile the application for VxWorks on arm. Of course, the resulting module cannot be run on the development system if cross-compiling.
The --platform option will search current directory and parent directories for an Appweb platform directory of the same name. You can provide a full path name as an argument to the --platform switch if your application is outside the Appweb source tree.
Note: You may need to modify the esp.conf configuration file to add rules for your operating system and CPU architecture or to customize for your application.
Running
To run your application:
esp run
Cleaning
To clean all generated files under the cache directory:
esp clean
Command Options
To see the esp command options, run esp with no options. This produces:
ESP Usage: esp [options] [commands] Options: --chdir dir # Change to the named directory first --config configFile # Use named config file instead appweb.conf --database name # Database provider 'mdb|sqlite' --flat # Compile into a single module --genlink # Generate a static link module for flat compilations --host OS # Target O/S --keep # Keep intermediate source --listen [ip:]port # Listen on specified address --log logFile:level # Log to file file at verbosity level --overwrite # Overwrite existing files --quiet # Don't emit trace --platform os-arch-profile # Target platform. May be a full path. --rebuild # Force a rebuild --reverse # Reverse migrations --routeName name # Route name in appweb.conf to use --routePrefix prefix # Route prefix in appweb.conf to use --show # Show compile commands --static # Use static linking --verbose # Emit verbose trace --why # Why compile or skip Commands: esp clean esp compile esp compile [pathFilters ...] esp migrate [forward|backward|NNN] esp generate app name esp generate controller name [action [, action] ... esp generate migration description model [field:type [, field:type] ...] esp generate scaffold model [field:type [, field:type] ...] esp generate table name [field:type [, field:type] ...] esp run
Switch | Description |
---|---|
--chdir dir | Change to the specified directory. |
--config configFile | Use the named config file instead of appweb.conf. |
--database connector | Select a database connector to use. Currently, this switch is not implemented and sqlite is the only connector supported. |
--flat | Compile entire application into a single module. Same as "esp compile flat". |
--genlink slink.c | Generate a file of ESP initializers when using --static and --flat". |
--keep | Preserve intermediate files. Useful for debugging. |
--listen [ip:]port | Listen on the specified address. Overrides the Listen directive in appweb.conf. |
--log logFile:level | Log errors and trace to the log file at the given verbosity level. Levels are 0-9 with nine being the most verbose. |
--name | Name for the application when compiling flat. |
--overwrite | Overwrite existing files. The esp command normally will not overwrite existing files. This is to preserve user changes to previously generated files. |
--quiet or -q | Run quietly and don't trace actions to the console. |
--platform os-arch-profile | Target platform. This may be a full path to an Appweb platform directory in an Appweb source tree. |
--rebuild | Force a rebuild of all components. |
--reverse | Reverse migrations. |
--routeName name | Route name in appweb.conf to use for ESP configuration. |
--routePrefix prefix | Route prefix in appweb.conf to use for ESP configuration. |
--show | Show all commands invoked by esp. |
--static | Use static linking when compiling ESP components. |
--verbose or -v | Run in verbose mode and trace actions to the console (default). |
--why | Show why a compile was performed or omitted. |