Configuring ESP

Embedded Server Pages (ESP) is managed by a set of configuration directives in the appweb.conf configuration file. These directives permit manage:

• ESP applications
• ESP directory locations
• ESP Error handling
• Compilation and linking of ESP components
• URI parsing and routing
• Database access and binding

Use Cases

There are two primary use cases to consider when configuring ESP:

• ESP Pages
• ESP MVC applications

The basic ESP configuration takes care of ESP pages and configures Appweb to process *.esp pages via the ESP handler. If you need to support ESP MVC applications, there are extra directives to configure Appweb routes to support each MVC application.

Configuration

Before ESP can be used, the ESP web framework including the ESP handler must be loaded. ESP is packaged as as an Appweb module called "mod_esp". This is loaded into Appweb via the LoadModule directive.

LoadModule espHandler mod_esp

This loads the mod_esp module and invokes the ESP module initialization routine that registers ESP with Appweb.

Configuring the ESP Handler

For ESP to receive incoming client requests, the Appweb router must be told what requests to send to ESP. The AddHandler directive below achieves this. It tells Appweb that the espHandler will service all URIs that end with ".esp".

AddHandler espHandler esp

This is all that is needed to service any ESP web page that ends with ".esp". If you want to ESP pages with another extension, you can specify extra extensions:

AddHandler espHandler esp myesp

Error Handling

If an ESP page has a syntax error or a run-time error, messages will be sent to the Appweb log file. This defaults to the file error.log. If appweb is run manually, you can see these message on the console.

Often during development, it is useful to send errors back to the browser. To do this, add the following directive to appweb.conf.

EspShowErrors on

This will display errors to the browser in addition to sending the errors to the Appweb log.

ESP Directories

ESP has certain conventions and defaults as to where it locates controllers, pages, layouts and other components. If you follow these conventions, you will not need to manually configure ESP's directories. However, if you need to, you can modify these on a per-route basis via the EspDir directive.

The directories are:

Directory	Purpose
cache	Location to store compiled ESP pages and controllers
controllers	Location for controller source code
db	Location for database files
layouts	Location for ESP layout pages
static	Location for static web content
views	Location for ESP MVC view pages

The EspDir directive sets an ESP directory location for the current route. For example:

EspDir cache ./modules

This will cause ESP to store and retrieve the shared libraries containing compiled ESP pages and controllers to and from the modules directory.

Directory Sets

The EspDir command can also be used to set a pre-defined directory configuration. The directive EspDir mvc will set the various ESP directories to default values of the same name. i.e. the controllers directory will be set to the controllers sub-directory under the route's document root. When EspApp is used to define an ESP MVC application, the EspDir mvc command is automatically applied.

Reloading

ESP supports an "edit-and-continue" development style where you can make modifications to ESP controllers and pages and when you click reload in your browser, the controller or page will be transparently recompiled and reloaded. This can be a great boost for development productivity.

If Appweb and ESP are built in debug mode (by configuring with ./configure --debug) then ESP will automatically rebuild modified ESP pages and controllers. If Appweb and ESP are built in release mode, the default is to not reload. This default behavior can be modified via the EspUpdate directive. Setting the directive to "on" will enable the transparent recompilation and reloading of modified items.

Keep Source

Sometimes, it is helpful to preserve intermediate "C" source files so that you can debug your application at the source code level. When an ESP page is parsed, it is blended with a layout page and then an intermediate C source file is generated. This is normally removed after compilation. Setting the EspKeepSource directive to "on" will cause ESP to preserve this intermediate source file in the cache directory.

MVC Applications

ESP MVC applications typically require a little more configuration, but the ESP defaults make this fairly painless.

Separate Config

To modularize each ESP application, it is best practice to create a separate config file for each application. This per-application config file should be saved to the /etc/appweb/apps or on Windows, the Embedthis Appweb/apps directory. When Appweb is started or restarted, it will parse all the config files under the apps. Installing or removing a config file for each application under the apps directory is a simple way to add/remove an application.

One Line MVC Configuration

If your MVC application uses RESTful routes and follows the ESP defaults, the one-liner EspApp directive is typically all you need. This directive takes the following arguments:

Esp URI-Prefix Directory RouteSet Database

This defines an ESP application at the given directory that will receive all requests that begin with specified URI prefix. This will define a new Route block, inheriting the existing configuration. For example, a "blog" application stored in the "./blog" directory using RESTful routes and storing data in a SQLite database could be configured via:

EspApp /myblog ./blog restful sqlite://blog/blog.sdb

With this configuration, Appweb will send all URIs that begin with /myblog to this Blog ESP application.

Routes

So far, we've covered the basics, but Appweb provides very powerful routing and directives that can be utilized to custom configure ESP applications. The EspApp directive is really a convenience directive that is equivalent to a set of lower-level directives. For example, the previous EspApp directive:

EspApp /myblog ./blog restful sqlite://blog/blog.sdb

is equivalent to:

<Route ^/myblog >
    Prefix /myblog
    Documents ./blog
    AddHandler espHandler
    EspDir restful
    EspDb sqlite://blog.mdb
    EspRouteSet restful                                                                                
</Route>  

REST and Resources

ESP supports using a RESTful design for mapping request URIs to resources. An application will typically deal with various resources that need to be managed. For example, a WIFI router UI will need to manage the WIFI network name and password. A network switch application may need to manage a group of ethernet ports. Using REST, these resources are mapped onto HTTP methods and URIs in a simple and clear manner.

ESP provides two directives to create URI routes for resources:

• EspResource — Create routes for a singleton resource
• EspResourceGroup — Create routes for a group of resources

EspResource

The EspResource directive is used to create a RESTful set of routes to manage a singleton resource. A singleton resource is one or more related properties that are managed as a unit, like the WIFI network name and password. These routes define URI routes for create, destroy, edit, init, show and update functions. See the EspResource reference for details of the actual routes created.

EspResourceGroup

The EspResourceGroup directive is used to create a RESTful set of routes to manage a singleton resource. A group of resources is one or more instances of a resource that can be managed individually, like the "port" on a network switch. See the EspResourceGroup reference for details of the actual routes created.

Custom Routes

Sometimes you need a specific, custom mapping of a URI to an ESP controller and action. You can do this with the lowest-level Appweb directives:

• Route
• Name
• Source
• Target

However, it is easier to use the EspRoute directive that will create a route for a URI and map the URI to an ESP controller and action. For example:

EspRoute administration POST ^/wifi/admin/login admin-login admin.c

This will map /wifi/admin/login URI to the admin controller and invoke the login action.

See the EspRoute reference for details of the directive arguments.

Databases

Databases can be specified and pre-opened via the EspDb directive. Pre-opening a database connection for an ESP application or route within an application eliminates the run-time delay connecting to the database. ESP supports multiple database engines through a single Embedded Database Interface. Support is included for SQLite, MySQL and MDB. See Database Interface for more information about Database Support.

The EspDb directive takes the form: EspDb provider://database-connection. For example:

  EspDb mdb://blog.mdb
or
  EspDb sqlite://sqlite.sdb

For SQLite and MDB databases, the database-connection string is the name of the database in the ESP db directory. Databases can also be pre-opened via the EspApp directive.

Compilation

At development time, ESP need to compile ESP controllers and pages into native code. ESP supplies a pre-configured set of compilation commands for the major operating systems. These are stored in the esp.conf file which is located at /usr/lib/appweb/lib on Unix or on Windows at C:/Program Files/Embedthis Appweb/lib. The esp.conf file contains compile and link command templates using the EspCompile and optionally EspLink. For example:

EspCompile cc -shared ${DEBUG} -Wall -Wno-unused-result \
    -DPIC -fPIC -I. -I${INC} \
    -L${LIB} -Wl,--enable-new-dtags \
    -Wl,-rpath,$ORIGIN/ \
    -Wl,-rpath,$ORIGIN/../lib ${LIBS} \
    -o ${OUT}${SHOBJ} ${SRC}

The various tokens in braces "${token}", are expanded at runtime depending on the configuration of Appweb. The esp.conf configuration file has conditional sections for Cygwin, Windows, Mac OS X, VxWorks and a default section for Linux/Unix. You can customize this file to suit your system.

Some systems require a separate link phase. The EspLink command can be used to do a separate link. Other systems require that various environment variables be defined for the compiler and linker to successfully run. Use the EspEnv command for this.

Cross Compilation

When cross-compiling, invoke the esp command with the "--config" switch to specify a separate config file for compiling on the target. Copy the standard esp.conf and modify the compile and link targets as required

Directives List

The following is a list of the various ESP directives and their purpose. Click on the "purpose" text, to see the appropriate directive reference.

Directive	Purpose
EspApp	Define an ESP web application
EspCompile	Compile command for ESP controllers and pages
EspDb	Pre-open a database
EspDir	Set an ESP directory location
EspEnv	Set an environment variable
EspKeepSource	Preserve intermediate page source code
EspLink	Link command for ESP controllers and pages
EspLoad	Pre-load an ESP application that has been compiled flat
EspResource	Create a set of routes for a singleton resource
EspResourceGroup	Create a set of routes for a group of resources
EspRoute	Define and configure an ESP route
EspRouteSet	Create a pre-defined set of routes
EspShowErrors	Show ESP errors to the client
EspUpdate	Reload updated ESP controllers and pages