The EspApp directive defines an ESP application at the given directory that will receive all requests that begin with specified URI prefix. This one-line directive is often all you need to do to define an ESP application. It is loosely equivalent to the following directive sequence:

<Route UriPrefix>
    Name UriPrefix
    Prefix UriPrefix
    DocumentRoot Directory
    AddHandler espHandler
    EspDir RouteSet
    EspRouteSet RouteSet
    EspDb Database
</Route>

If the URI prefix for the EspApp directive is the same as the the prefix for the outer route, EspApp will use the existing route. Otherwise, it will create a new route for the URI prefix. Sub-routes are created for the RouteSet argument.

The UriPrefix argument is mandatory, all others are optional. The Directory argument is used to define the DocumentRoot for the defined route.

The RouteSet argument specifies a set of routes to add for the applications. Permissable values for the RouteSet are:

• simple — Adds a route for the home page URI ("/").
• mvc-simple — Adds a route for the home page URI ("/") and a route for static content under the "static" directory.
• mvc — Adds a home route, a static route and a generic route mapping URIs of the form: ^/{controller}(~/{action}~). This means a URI with a controller component followed by an optional slash and action.
• restful — Adds a home route, a static route and resource group routes mapping URIs. See EspResourceGroup for details.

It is convenient to define applications using this directive in a separate configuration file for each application. If the application config file is stored under the Appweb "conf/apps" directory, then Appweb will read it automatically when it starts. This makes it very easy to install or remove applications by simply adding or removing an application configuration file to or from this directory.

The EspApp directive does the following actions:

• Creates a new Route block for the URI prefix if required.
• Adds the esp handler as the handler for the URI prefix. Note that previously defined handlers such as the fileHandler will still match by extensions such as .html.
• Defines the directories to use for the applications via espDir.
• Optionally creates a route set
• Optionally opens a database

Note: use a trailing "/" on the prefix to prevent matching URIs that have the prefix as part of the first (non-directory) portion of their URI.

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

The EspCompile directive specifies the command line to use to compile controllers and parsed ESP template pages. The command can used embedded tokens of the form ${TOKEN}. These are expanded at run-time based on the platform.

The set of supported tokens is:

• ARCH — Build architecture (x86_64)
• CC — Compiler (cc)
• DEBUG — Debug compilation options
• INC — Include directory out/inc
• LIB — Library directory (out/lib, xcode/VS: out/bin)
• LIBS — Libraries required to link with ESP
• OBJ — Name of compiled source (out/lib/view-MD5.o)
• OUT — Output module (view_MD5.dylib)
• SHLIB — Shared library (.lib, .so)
• SHOBJ — Shared Object (.dll, .so)
• SRC — Source code for view or controller (already templated)
• TMP — Temp directory
• VS — Visual Studio directory
• WINSDK — Windows SDK directory

A default EspCompile directive is supplied via the /usr/lib/appweb/lib/esp.conf configuration file. On windows this is installed by default at: /Program Files/Embedthis Appweb/lib/esp.conf. This file defines standard compilation and link commands for Windows, Linux, MacOSX and VXWORKS. To override the default EspCompile command line, ensure you place an EspCompile directive after the include for esp.conf.

EspDb mdb://test.mdb
EspDb sdb://test.sdb

The EspDb directive specifies the default database to use by an ESP application. The database is opened when Appweb starts and is made available to all ESP requests using the current Route.

The database spec argument is of the form:

provider://path

Where provider is the database provider name. ESP currently supports two providers:

• mdb — The MDB is the Memory Database and it provides a high-performance, non-SQL, in-memory data store. See ... for more details.
• sdb — This requests the SQLite database

The database path can be a relative or absolute path. If relative, it will be relative to the ESP db directory. See espDir for how to define the db directory.

EspDir mvc
EspDir static ./web

The EspDir directive configures the directories used by ESP. The standard directories are:

• cache — This is the directory where ESP puts compiled modules. Defaults to cache.
• controllers — This is the directory for MVC controller source code. Defaults to controllers.
• db — This is the directory for database files. Defaults to db.
• layouts — This is the directory for ESP template layouts. Defaults to layouts.
• static — This is the directory for static web files in an MVC application. Defaults to static.
• views — This is the directory MVC views. Defaults to views.

There are two forms for the EspDir directive. The first takes a single argument set to "mvc". This form sets each of the standard directories to their default values.

The second form defines a single ESP directory to the given path value.

EspEnv LIB "${WINSDK}\LIB;${VS}\VC\lib"

EspEnv VisualStudio

The EspEnv directive specifies an environment variable that will be defined before running the EspCompile or EspLink commands. Some platforms, such as Windows with Visual Studio, require certain environment variables to be defined for the compiler and linker to execute. Visual Studio requires that the INCLUDE, LIB, PATH and TMP environment variables be defined correctly.

The EspEnv argument can also be set to "VisualStudio" to define the required Visual Studio environment. This will define the INCLUDE, LIB and PATH variables if the current user's environment does not contain the Visual Studio settings. User's can run the Visual Studio vsvarsall.bat script (supplied with Visual Studio) to define the environment.

EspKeepSource on

The EspKeepSource directive controls whether the parsed, intermediate "C" source code for ESP templates and views should be preserved in the cache directory. This is useful when debugging the view in an IDE or debugger.

Set the argument to "on" to preserve intermediate source and set to "off" to remove intermediate source.

EspLink cc -dynamiclib ${DEBUG} -arch ${ARCH} -L${LIB} \
  -Wl,-rpath,@executable_path/../lib \
  -Wl,-rpath,@executable_path/ -Wl,-rpath,@loader_path/ \
  ${LIBS} -o ${OUT}${SHOBJ} ${OBJ} 

The EspLink directive specifies the command line to use to link controllers and parsed ESP template pages. The command can used embedded tokens of the form ${TOKEN}. These are expanded at run-time based on the platform.

The set of supported tokens is:

• ARCH — Build architecture (x86_64)
• CC — Compiler (cc)
• DEBUG — Debug compilation options
• INC — Include directory out/inc
• LIB — Library directory (out/lib, xcode/VS: out/bin)
• LIBS — Libraries required to link with ESP
• OBJ — Name of compiled source (out/lib/view-MD5.o)
• OUT — Output module (view_MD5.dylib)
• SHLIB — Shared library (.lib, .so)
• SHOBJ — Shared Object (.dll, .so)
• SRC — Source code for view or controller
• TMP — Temp directory
• VS — Visual Studio directory
• WINSDK — Windows SDK directory

A default EspLink directive is supplied via the /usr/lib/appweb/lib/esp.conf configuration file. On windows this is installed by default at: /Program Files/Embedthis Appweb/lib/esp.conf. This file defines standard compilation and link commands for Windows, Linux, MacOSX and VXWORKS. To override the default EspLink command line, ensure you place an EspLink directive after the include for esp.conf.

Some platforms can do the compile and link phases in one command. Others require a separate link.

If appweb is built with static linking or if the esp command is invoked with the --static switch, the EspLink command should perform static linking. The default esp.conf configuration file has separate commands for dynamic and static linking.

EspLoad blog cache/app
EspLoad blog cache/app.dylib

The EspLoad directive will pre-load an ESP application that has been compiled flat via the esp compile flat command. A flat application is one where all controllers, views and ESP template pages have been compiled into a single module. Pre-loading a flat application provides the ultimate in performance and eliminates any per-request overhead in checking for changed modules or source code.

The Name argument to the directive should be a unique, descriptive name for the application. By default, when esp compiles an application, this name is the folder name of the application, though this can be overridden by the esp --name switch.

The second argument is a path to the compiled, flat application. This by default is called cache/app.so where .so may vary depending on the O/S platform. The path may be specified with or without an extension. Omitting the extension will allow a common configuration file to be used across multiple platforms.

See the ESP Generator documentation for more details.

EspResource system profile status

The EspResource directive creates a set of routes suitable for a singleton resource. The routes created are RESTful routes that are designed to mesh well with ESP MVC applications. They provide clean URIs that allow the basic Create/Read/Update/Destroy (CRUD) operations on a resource.

EspResource system
LogRoutes
# Prints ...

Name             Method  Pattern             Target
/system/init     GET     ^/system/init$      system-init   
/system/create   POST    ^/system(/)*$       system-create 
/system/edit     GET     ^/system/edit$      system-edit   
/system/show     GET     ^/system$           system-show   
/system/update   PUT     ^/system$           system-update 
/system/destroy  DELETE  ^/system$           system-destroy
/system/default  *       ^/system/{action}$  system-cmd-$1 

EspResourceGroup customer prospect

The EspResourceGroup directive creates a set of routes suitable for a group of resources. The routes created are RESTful routes that are designed to mesh well with ESP MVC applications. They provide clean URIs that allow the basic Create/Read/Update/Destroy (CRUD) operations on a group of resources. Use this directive if there are more than one instance of a resource. Use the EspResource directive if there is only once instance of the resource.

By convention, the resource group name should be singular and not plural. To avoid confusion as to whether controller and/or view names should be singular or plural — ESP always uses singular names for controllers, views, template pages and database tables.

For example, this command will generate the following routes:

EspResourceGroup user
LogRoutes
# Prints ...

Name            Method  Pattern                      Target
/user/list      GET     ^/user(/)*$                  user-list     
/user/init      GET     ^/user/init$                 user-init     
/user/create    POST    ^/user(/)*$                  user-create   
/user/edit      GET     ^/user/{id=[0-9]+}/edit$     user-edit     
/user/show      GET     ^/user/{id=[0-9]+}$          user-show     
/user/update    PUT     ^/user/{id=[0-9]+}$          user-update   
/user/destroy   DELETE  ^/user/{id=[0-9]+}$          user-destroy  
/user/custom    POST    ^/user/{action}/{id=[0-9]+}$ user-$1       
/user/default   *       ^/user/{action}$             user-cmd-$1 

EspRoute /app/user POST ^/app/user/{action} user-${action} user.c

The EspRoute directive creates a single route and configures it according to the given parameters. This is a one-line convenience directive that is equivalent to the following directive sequence:

For ESP MVC applications, the target must be of the form: CONTROLLER-ACTION. The target string can contain token replacement references of the form "${token}". This will typically use "${action}" and/or "${controller}".

<Route ^/app/user/{action}>
  Name /app/user
  Methods POST
  Source user.c
  Target run
</Route>

EspRouteSet mvc

The EspRouteSet directive defines a pre-prepared set of routes according to the route set argument. Valid sets are:

• simple — This defines a route to the application home URI at "/" that serves an "index.esp page.
• mvc — This defines a route to the application home URI at "/" that serves an "index.esp page. It also defines a route for URIs beginning with "/static" that serves content from the static directory. Lastly, it defines a non-RESTful route for URIs that match "/{controller}(~/{action}~)". This matches URIs with a controller and optional action.
• restful — This defines a route to the application home URI at "/" that serves an "index.esp page. It also defines a route for URIs beginning with "/static" that serves content from the static directory. Lastly, it defines a Resource Group of routes for any controller name.

EspShowErrors on

The EspShowErrors directive controls whether ESP errors are sent to the client and displayed in the browser. If EspShowErrors is off, then ESP errors will be sent to the Appweb log file. If EspShowErrors is on, then the errors will also be sent back to the client. This is useful in development mode to quickly diagnose errors.

EspUpdate on

The EspUpdate directive controls whether to reload updated content. If EspUpdate is on, then ESP will reload any updated module. It will also recompile updated controller source files, web pages and views.

If EspUpdate is off, ESP will load content from cache once but will not reload or compile ESP source.

When reloading, ESP first waits for all active ESP requests to complete before unloading old versions of the module being updated. When all is quiet, it reloads the new module — recompiling if required.