361 lines
23 KiB
HTML
361 lines
23 KiB
HTML
<!-- BeginDsi "dsi/head.html" -->
|
|
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<title>Embedthis Appweb 4.3.4 Documentation</title>
|
|
<meta name="keywords" content="embedded web server, web server software, embedded HTTP, application web server,
|
|
embedded server, small web server, HTTP server, library web server, library HTTP, HTTP library" />
|
|
<meta name="description" content="Embedthis Sofware provides commercial and open source embedded web servers for
|
|
devices and applications." />
|
|
<meta name="robots" content="index,follow" />
|
|
<link href="../../../doc.css" rel="stylesheet" type="text/css" />
|
|
<link href="../../../print.css" rel="stylesheet" type="text/css" media="print"/>
|
|
<!--[if IE]>
|
|
<link href="../../../iehacks.css" rel="stylesheet" type="text/css" />
|
|
<![endif]-->
|
|
<link href="http://www.google.com/cse/style/look/default.css" type="text/css" rel="stylesheet" />
|
|
</head>
|
|
|
|
<body>
|
|
<div class="top">
|
|
<a class="logo" href="http://appwebserver.org/"> </a>
|
|
<div class="topRight">
|
|
<div class="search">
|
|
<div id="cse-search-form"></div>
|
|
<div class="version">Embedthis Appweb 4.3.4</div>
|
|
</div>
|
|
</div>
|
|
<div class="crumbs">
|
|
<a href="../../../index.html">Home</a>
|
|
<!-- EndDsi -->
|
|
><a href="index.html">ESP Guide</a> >
|
|
<b>Embedded Server Pages</b>
|
|
</div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="contentRight">
|
|
<h1>Quick Nav</h1>
|
|
<ul class="nav">
|
|
<li><a href="#configuration">Configuration</a></li>
|
|
<li><a href="#errors">Error Handling</a></li>
|
|
<li><a href="#dir">Directories</a></li>
|
|
<li><a href="#reload">Reloading</a></li>
|
|
<li><a href="#keep">Keep Source</a></li>
|
|
<li><a href="#mvc">MVC Applications</a></li>
|
|
<li><a href="#routes">Routes</a></li>
|
|
<li><a href="#database">Databases</a></li>
|
|
<li><a href="#compilation">Compilation</a></li>
|
|
<li><a href="#directives">Directives</a></li>
|
|
</ul>
|
|
<!-- BeginDsi "dsi/webFrameSeeAlso.html" -->
|
|
<h1>See Also</h1>
|
|
<ul class="nav">
|
|
<li><a href="../../../guide/appweb/users/frameworks.html">Web Frameworks</a></li>
|
|
<li><a href="../../../guide/appweb/users/action.html">Action Handler</a></li>
|
|
<li><a href="../../../guide/appweb/users/cgi.html">CGI</a></li>
|
|
<li><a href="../../../guide/esp/users/index.html">ESP</a></li>
|
|
<li><a href="../../../guide/appweb/users/ejs.html">Ejscript</a></li>
|
|
<li><a href="../../../guide/appweb/users/php.html">PHP</a></li>
|
|
<li><a href="../../../guide/appweb/users/index.html">User Guide Overview</a></li>
|
|
<li><a href="../../../guide/appweb/users/configuration.html">Configuring Appweb</a></li>
|
|
<li><a href="../../../guide/appweb/users/ports.html">Ports and Binding</a></li>
|
|
<li><a href="../../../guide/appweb/users/authentication.html">User Authorization</a></li>
|
|
<li><a href="../../../guide/appweb/users/logFiles.html">Log Files</a></li>
|
|
<li><a href="../../../guide/appweb/users/vhosts.html">Virtual Hosts</a></li>
|
|
<li><a href="../../../guide/appweb/users/security.html">Security Considerations</a></li>
|
|
<li><a href="../../../guide/appweb/users/ssl.html">SSL</a></li>
|
|
<li><a href="../../../guide/appweb/users/modules.html">Appweb Modules</a></li>
|
|
<li><a href="../../../guide/appweb/users/stages.html">Pipeline Stages</a></li>
|
|
<li><a href="../../../guide/appweb/users/client.html">HTTP Client</a></li>
|
|
<li><a href="../../../ref/appweb/architecture.html">Appweb Architecture</a></li>
|
|
</ul>
|
|
<!-- EndDsi -->
|
|
</div>
|
|
<div class="contentLeft">
|
|
<h1>Configuring ESP</h1>
|
|
<p>Embedded Server Pages (ESP) is managed by a set of configuration directives in the <em>appweb.conf</em>
|
|
configuration file. These directives permit manage:</p>
|
|
<ul>
|
|
<li>ESP applications</li>
|
|
<li>ESP directory locations</li>
|
|
<li>ESP Error handling</li>
|
|
<li>Compilation and linking of ESP components</li>
|
|
<li>URI parsing and routing</li>
|
|
<li>Database access and binding</li>
|
|
</ul>
|
|
<h2 class="section">Use Cases</h2>
|
|
<p>There are two primary use cases to consider when configuring ESP:</p>
|
|
<ul>
|
|
<li>ESP Pages</li>
|
|
<li>ESP MVC applications</li>
|
|
</ul>
|
|
<p>The basic ESP configuration takes care of ESP pages and configures Appweb to process <em>*.esp</em> 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.</p>
|
|
<a id="configuration"></a>
|
|
<h2 class="section">Configuration</h2>
|
|
<p>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 "<em>mod_esp</em>". This is loaded into Appweb via the <em>LoadModule</em>
|
|
directive.</p>
|
|
<pre>LoadModule espHandler mod_esp</pre>
|
|
<p>This loads the <em>mod_esp</em> module and invokes the ESP module initialization routine that registers
|
|
ESP with Appweb.</p>
|
|
<h2>Configuring the ESP Handler</h2>
|
|
<p>For ESP to receive incoming client requests, the Appweb router must be told what requests to send to ESP.
|
|
The <em>AddHandler</em> directive below achieves this. It tells Appweb that the <em>espHandler</em> will service
|
|
all URIs that end with "<em>.esp</em>".</p>
|
|
<pre>AddHandler espHandler esp</pre>
|
|
<p>This is all that is needed to service any ESP web page that ends with "<em>.esp</em>". If you want to
|
|
ESP pages with another extension, you can specify extra extensions:</p>
|
|
<pre>AddHandler espHandler esp myesp</pre>
|
|
<a id="errors"></a>
|
|
<h2 class="section">Error Handling</h2>
|
|
<p>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 <em>error.log</em>. If appweb is run manually, you can see these message on
|
|
the console.</p>
|
|
<p>Often during development, it is useful to send errors back to the browser. To do this, add the following
|
|
directive to appweb.conf.</p>
|
|
<pre>EspShowErrors on</pre>
|
|
<p>This will display errors to the browser in addition to sending the errors to the Appweb log.</p>
|
|
<a id="dir"></a>
|
|
<h2>ESP Directories</h2>
|
|
<p>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 <em>EspDir</em> directive.</p>
|
|
<p>The directories are:</p>
|
|
<table title="dirs">
|
|
<thead>
|
|
<tr><th>Directory</th><th>Purpose</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td>cache</td><td>Location to store compiled ESP pages and controllers</td>
|
|
<tr><td>controllers</td><td>Location for controller source code</td>
|
|
<tr><td>db</td><td>Location for database files</td>
|
|
<tr><td>layouts</td><td>Location for ESP layout pages</td>
|
|
<tr><td>static</td><td>Location for static web content</td>
|
|
<tr><td>views</td><td>Location for ESP MVC view pages</td>
|
|
</tbody>
|
|
</table>
|
|
<p>The <em>EspDir</em> directive sets an ESP directory location for the current route. For example:</p>
|
|
<pre>EspDir cache ./modules</pre>
|
|
<p>This will cause ESP to store and retrieve the shared libraries containing compiled ESP pages and controllers
|
|
to and from the modules directory.</p>
|
|
<h2>Directory Sets</h2>
|
|
<p>The EspDir command can also be used to set a pre-defined directory configuration. The directive
|
|
<em>EspDir mvc</em> will set the various ESP directories to default values of the same name. i.e.
|
|
the controllers directory will be set to the <em>controllers</em> sub-directory under the route's
|
|
document root. When EspApp is used to define an ESP MVC application, the <em>EspDir mvc</em> command is
|
|
automatically applied.</p>
|
|
<a id="reload"></a>
|
|
<h2 class="section">Reloading</h2>
|
|
<p>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.</p>
|
|
<p>If Appweb and ESP are built in debug mode (by configuring with <em>./configure --debug</em>) 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
|
|
<em>EspUpdate</em> directive. Setting the directive to "<em>on</em>" will enable the transparent
|
|
recompilation and reloading of modified items.</p>
|
|
<a id="keep"></a>
|
|
<h2 class="section">Keep Source</h2>
|
|
<p>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
|
|
<em>EspKeepSource</em> directive to "<em>on</em>" will cause ESP to preserve this intermediate source file
|
|
in the <em>cache</em> directory.</p>
|
|
<a id="mvc"></a>
|
|
<h2 class="section">MVC Applications</h2>
|
|
<p>ESP MVC applications typically require a little more configuration, but the ESP defaults make this fairly
|
|
painless.</p>
|
|
<h2>Separate Config</h2>
|
|
<p>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 <em>/etc/appweb/apps</em> or
|
|
on Windows, the <em>Embedthis Appweb/apps</em> directory. When Appweb is started or restarted, it will
|
|
parse all the config files under the <em>apps</em>. Installing or removing a config file for each
|
|
application under the <em>apps</em> directory is a simple way to add/remove an application.</p>
|
|
<h2>One Line MVC Configuration</h2>
|
|
<p>If your MVC application uses RESTful routes and follows the ESP defaults, the one-liner
|
|
<a href="../../appweb/users/dir/esp.html#espApp">EspApp</a>
|
|
directive is typically all you need. This directive takes the following arguments:</p>
|
|
<pre>Esp URI-Prefix Directory RouteSet Database</pre>
|
|
<p>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:</p>
|
|
<pre>EspApp /myblog ./blog restful sqlite://blog/blog.sdb</pre>
|
|
<p>With this configuration, Appweb will send all URIs that begin with <em>/myblog</em> to this Blog ESP
|
|
application.</p>
|
|
<a id="routes"></a>
|
|
<h2 class="section">Routes</h2>
|
|
<p>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:</p>
|
|
<pre class="light">EspApp /myblog ./blog restful sqlite://blog/blog.sdb</pre>
|
|
<p>is equivalent to:</p>
|
|
<pre>
|
|
<Route ^/myblog >
|
|
Prefix /myblog
|
|
Documents ./blog
|
|
AddHandler espHandler
|
|
EspDir restful
|
|
EspDb sqlite://blog.mdb
|
|
EspRouteSet restful
|
|
</Route>
|
|
</pre>
|
|
<h2>REST and Resources</h2>
|
|
<p>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.</p>
|
|
<p>ESP provides two directives to create URI routes for resources: </p>
|
|
<ul>
|
|
<li>EspResource — Create routes for a singleton resource</li>
|
|
<li>EspResourceGroup — Create routes for a group of resources</li>
|
|
</ul>
|
|
<h2>EspResource</h2>
|
|
<p>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 <a href="../../appweb/users/dir/esp.html#espResource">EspResource</a> reference
|
|
for details of the actual routes created.</p>
|
|
<h2>EspResourceGroup</h2>
|
|
<p>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 <a href="../../appweb/users/dir/esp.html#espResourceGroup">EspResourceGroup</a> reference
|
|
for details of the actual routes created.</p>
|
|
<h2>Custom Routes</h2>
|
|
<p>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:</p>
|
|
<ul>
|
|
<li><a href="../../appweb/users/dir/route.html#route">Route</a></li>
|
|
<li><a href="../../appweb/users/dir/route.html#name">Name</a></li>
|
|
<li><a href="../../appweb/users/dir/route.html#source">Source</a></li>
|
|
<li><a href="../../appweb/users/dir/route.html#target">Target</a></li>
|
|
</ul>
|
|
<p>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: </p>
|
|
<pre>EspRoute administration POST ^/wifi/admin/login admin-login admin.c</pre>
|
|
<p>This will map <em>/wifi/admin/login</em> URI to the <em>admin</em> controller and invoke
|
|
the <em>login</em> action.</p>
|
|
<p>See the <a href="../../appweb/users/dir/esp.html#espRoute">EspRoute</a> reference
|
|
for details of the directive arguments.</p>
|
|
<a id="database"></a>
|
|
<h2 class="section">Databases</h2>
|
|
<p>Databases can be specified and pre-opened via the <em>EspDb</em> 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 <a href="database.html">Database Interface</a> for more information about
|
|
Database Support.</p>
|
|
<p>The EspDb directive takes the form: <em>EspDb provider://database-connection</em>. For example:
|
|
<pre class="light">
|
|
EspDb mdb://blog.mdb
|
|
or
|
|
EspDb sqlite://sqlite.sdb
|
|
</pre>
|
|
<p>For SQLite and MDB databases, the database-connection string is the name of the database in the ESP
|
|
<em>db</em> directory. Databases can also be pre-opened via the
|
|
<a href="../../appweb/users/dir/esp.html#espApp">EspApp</a> directive.</p>
|
|
<a id="compilation"></a>
|
|
<h2 class="section">Compilation</h2>
|
|
<p>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 <em>esp.conf</em> file which is located at <em>/usr/lib/appweb/lib</em> on Unix or on
|
|
Windows at <em>C:/Program Files/Embedthis Appweb/lib</em>. The esp.conf file contains compile and link command
|
|
templates using the <a href="../../appweb/users/dir/esp.html#espCompile">EspCompile</a> and optionally
|
|
<a href="../../appweb/users/dir/esp.html#espLink">EspLink</a>. For example:
|
|
<pre>
|
|
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}
|
|
</pre>
|
|
<p>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. </p>
|
|
<p>Some systems require a separate link phase. The <a
|
|
href="../../appweb/users/dir/esp.html#espLink">EspLink</a> 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 <a href="../../appweb/users/dir/esp.html#espEnv">EspEnv</a> command for this.
|
|
<h2>Cross Compilation</h2>
|
|
<p>When cross-compiling, invoke the <em>esp</em> command with the "<em>--config</em>" switch to specify a
|
|
separate config file for compiling on the target. Copy the standard <em>esp.conf</em> and modify the compile
|
|
and link targets as required</p>
|
|
<a id="directives"></a>
|
|
<h2 class="section">Directives List</h2>
|
|
<p>The following is a list of the various ESP directives and their purpose. Click on the "purpose" text, to
|
|
see the appropriate directive reference.</p>
|
|
<table title="directives">
|
|
<thead>
|
|
<tr><th>Directive</th><th>Purpose</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espApp">EspApp</a></td>
|
|
<td>Define an ESP web application</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espCompile">EspCompile</a></td>
|
|
<td>Compile command for ESP controllers and pages</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espDb">EspDb</a></td>
|
|
<td>Pre-open a database</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espDir">EspDir</a></td>
|
|
<td>Set an ESP directory location</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espEnv">EspEnv</a></td>
|
|
<td>Set an environment variable</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espKeepSource">EspKeepSource</a></td>
|
|
<td>Preserve intermediate page source code</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espLink">EspLink</a></td>
|
|
<td>Link command for ESP controllers and pages</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espLoad">EspLoad</a></td>
|
|
<td>Pre-load an ESP application that has been compiled flat</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espResource">EspResource</a></td>
|
|
<td>Create a set of routes for a singleton resource</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espResourceGroup">EspResourceGroup</a></td>
|
|
<td>Create a set of routes for a group of resources</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espRoute">EspRoute</a></td>
|
|
<td>Define and configure an ESP route</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espRouteSet">EspRouteSet</a></td>
|
|
<td>Create a pre-defined set of routes</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espShowErrors">EspShowErrors</a></td>
|
|
<td>Show ESP errors to the client</td></tr>
|
|
<tr><td><a href="../../appweb/users/dir/esp.html#espUpdate">EspUpdate</a></td>
|
|
<td>Reload updated ESP controllers and pages</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<!-- BeginDsi "dsi/bottom.html" -->
|
|
<div class="bottom">
|
|
<p class="footnote">
|
|
<a href="../../../product/copyright.html" >© Embedthis Software LLC, 2003-2013.
|
|
All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.</a>
|
|
</p>
|
|
</div>
|
|
<script src="http://www.google.com/jsapi" type="text/javascript"></script>
|
|
<script type="text/javascript">
|
|
google.load('search', '1', {language : 'en'});
|
|
google.setOnLoadCallback(function() {
|
|
var customSearchControl = new google.search.CustomSearchControl(
|
|
'000262706376373952077:1hs0lhenihk');
|
|
customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
|
|
var options = new google.search.DrawOptions();
|
|
options.enableSearchboxOnly("http://appwebserver.org/search.html");
|
|
customSearchControl.draw('cse-search-form', options);
|
|
}, true);
|
|
</script>
|
|
<script type="text/javascript">
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-179169-2']);
|
|
_gaq.push(['_trackPageview']);
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
</script>
|
|
</body>
|
|
</html>
|