302 lines
17 KiB
HTML
302 lines
17 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>Web Framework Tour</b>
|
|
</div>
|
|
</div>
|
|
<div class="content">
|
|
<div class="contentRight">
|
|
<h1>Quick Nav</h1>
|
|
<ul class="nav">
|
|
<li><a href="#starting">Starting Appweb</a></li>
|
|
<li><a href="#testing">Testing Appweb</a></li>
|
|
<li><a href="#hello">Hello World</a></li>
|
|
<li><a href="#dynamic">Dynamic Content</a></li>
|
|
<li><a href="#declarations">Declarations</a></li>
|
|
<li><a href="#params">Forms and Parameters</a></li>
|
|
<li><a href="#controls">Web Controls</a></li>
|
|
<li><a href="#sessions">Sessions and Flash</a></li>
|
|
<li><a href="#layouts">Layouts</a></li>
|
|
<li><a href="#learn">Learn More</a></li>
|
|
</ul>
|
|
<!-- BeginDsi "dsi/espSeeAlso.html" -->
|
|
<h1>See Also</h1>
|
|
<ul class="nav">
|
|
<li><a href="../../../guide/esp/users/using.html">ESP Overview</a></li>
|
|
<li><a href="../../../guide/esp/users/tour.html">ESP Tour</a></li>
|
|
<li><a href="../../../guide/esp/users/template.html">Templates and Layouts</a></li>
|
|
<li><a href="../../../guide/esp/users/controls.html">HTML Controls</a></li>
|
|
<li><a href="../../../guide/esp/users/config.html">ESP Configuration Directives</a></li>
|
|
<li><a href="../../../guide/esp/users/mvc.html">Model-View-Controller</a></li>
|
|
<li><a href="../../../guide/esp/users/generator.html">Application Generator</a></li>
|
|
<li><a href="../../../guide/esp/users/controllers.html">Controllers and Actions</a></li>
|
|
<li><a href="../../../guide/esp/users/database.html">Database Interface</a></li>
|
|
<li><a href="../../../guide/appweb/users/caching.html">Caching Responses</a></li>
|
|
</ul>
|
|
<!-- EndDsi -->
|
|
</div>
|
|
<div class="contentLeft">
|
|
<h1>ESP Web Framework Tour</h1>
|
|
<p>This quick tour of the ESP Web Framework provides an overview of ESP and how to use it in web pages.
|
|
First make sure you have read the <a href="../../appweb/users/quickStart.html">Quick Start</a> and
|
|
that you have ESP installed on your system so you can type along as you go.</p>
|
|
|
|
<a id="starting"></a>
|
|
<h2 class="section">Starting Appweb</h2>
|
|
<p>When Appweb is installed, it will start automatically and run in the background. You can start and stop
|
|
Appweb via the "<em>appman</em>" command.</p>
|
|
<pre>
|
|
appman start
|
|
appman stop
|
|
</pre>
|
|
<p>Type <em>appman</em> -? to see a list of options. See <a href="../../../guide/appweb/users/service.html">
|
|
Running Appweb as a System Service</a> for platform specific details about starting and stopping Appweb.</p>
|
|
|
|
<h3>Manually Running Appweb</h3>
|
|
|
|
<p>When developing, it can be most convenient to run Appweb manually. To run Appweb directly, use this
|
|
command:</p>
|
|
<pre>
|
|
sudo appweb -v
|
|
</pre>
|
|
<p>You must be in the Appweb server root directory containing an <em>appweb.conf</em> configuration file.</p>
|
|
|
|
|
|
<a id="testing"></a>
|
|
<h2 class="section">Testing Appweb</h2>
|
|
<p>To test Appweb, enter
|
|
<em>localhost/test.esp</em> in your browser. You should see the following page:</p>
|
|
|
|
<img src="../../../images/esp/tour/home.png" class="screen" alt="home" />
|
|
<a id="hello"></a>
|
|
<h2 class="section">Hello World</h2>
|
|
<p>The first step in any tour is to create a simple "Hello World" web page. ESP web pages have an
|
|
<em>.esp</em>
|
|
extension. Create a file called <em>hello.esp</em> under the directory nominated as your <em>Documents</em>
|
|
directory in the <em>appweb.conf</em> configuration file. Create a file using your favorite text editor with
|
|
the following content:</p>
|
|
<pre>
|
|
<html>
|
|
<body>
|
|
<h1>Hello World</h1>
|
|
</body>
|
|
</pre>
|
|
<p>Don't worry about the layout directive for now, that tells ESP not to use a layout page.</p>
|
|
<p>To view the "Hello" web page, type the following url: <em>http://localhost/hello.esp</em> into your browser.</p>
|
|
<img src="../../../images/esp/tour/hello.png" alt="hello" class= "bare-screen" />
|
|
<a id="dynamic"></a>
|
|
<h2 class="section">Dynamic Content</h2>
|
|
<p>While that was fun, the output is static and boring, so let's add some dynamic content. You can embed
|
|
"C" language code and ESP function calls by including them inside a special ESP web page directive that
|
|
will be executed and converted to HTML before being sent to the client. There are a variety of server-side
|
|
ESP web page directives, the one you'll use first, is: </p>
|
|
<p><em><%= expression %></em>.</p>
|
|
<p>To add the current date and time, modify the hello.esp web page and add the highlighted line:</p>
|
|
<pre>
|
|
<h1>Hello Bright World</h1>
|
|
<h2><b>Generated on <%= mprGetDate(0); %></b></h2>
|
|
</pre>
|
|
<p>Now when you re-run the page, it will display the current date and time. If you refresh the page by
|
|
pressing reload, the new date and time will be displayed.</p>
|
|
|
|
|
|
<img src="../../../images/esp/tour/hello-dynamic.png" alt="hello" class="bare-screen" />
|
|
<h4>No Restart Required</h4>
|
|
<p>Notice that you did not have to restart the web server, nor did you have to manually recompile the
|
|
ESP code. Rather, ESP transparently recompiled the web page in the background. ESP noticed that the hello.esp
|
|
web page had been modified and it re-parsed and compiled it into a loadable module ready for
|
|
execution. This web module is then cached in-memory and on-disk for fast execution.</p>
|
|
<p>You can also embed more complex ESP into our page, like:</p>
|
|
<pre>
|
|
<b><h3><% render("Request method is %s", getMethod()); %></h3></b>
|
|
<b><%
|
|
int i;
|
|
for (int i = 0; i < 10; i++) {
|
|
render(" Line: %d</br>\r\n", i);
|
|
}
|
|
%></b>
|
|
</pre>
|
|
<p>By using the ESP statement directive <b><% code %></b>, you can embed arbitrary "C" language
|
|
statements in your web page. The <em>render</em> function allows you to write arbitrary data which is patched
|
|
back where the directive was defined in the page. See the <a href="template.html">Web Pages and Templates</a>
|
|
document for full details about all the ESP web page directives.</p>
|
|
|
|
<a id="declarations"></a>
|
|
<h2 class="section">Declarations</h2>
|
|
<p>Some compilers (Microsoft CL) do not permit "C" declarations except at the start of a block. When ESP
|
|
compiles an ESP web page, it converts it to "C" code and wraps it inside a function that will be invoked
|
|
at run-time in response to client requests. ESP supports MSCL by controlling where ESP code will be
|
|
placed in the web page function. To ensure that declarations are emitted at the start of the function block
|
|
use the <em>^start</em> directive.</p>
|
|
<pre><%^start
|
|
char *msg = "hello world";
|
|
int x = 42;
|
|
%>
|
|
<% render("%s, the answer is %d", msg, x); %>
|
|
</pre>
|
|
<a id="params"></a>
|
|
<h2 class="section">Forms and Request Params</h2>
|
|
<p>When an HTML form is submitted, ESP converts form data and query parameters into ESP request parameters.
|
|
These can be accessed via the <em>param()</em> function or more conveniently via the literal <em>@@variable</em>
|
|
directive. By prefixing a variable with <em>@@</em> ESP will automatically look up the request parameters,
|
|
and if not found, the session data store for the variable, and then substitute its value.</p>
|
|
<p>If an HTTP request has the URI: <em>http://example.com/submit.esp?name=julie</em>, then the following
|
|
ESP code could access the user name directly.</p>
|
|
<pre><p>User Name: <b>@@name</b></p></pre>
|
|
<h3>XSS Security</h3>
|
|
<p>Normally, echoing user input back to the client in a web page is bad practice and can invite XSS security
|
|
attacks. Fortunately, ESP HTML escapes the variable value to prevent such attacks. </p>
|
|
<p>General ESP output can also be escaped by using a "safe" "%S" format specifier. The renderSafe function
|
|
can also be used.</p>
|
|
<pre><p>User Name: <b><%=%S param("name"); %></b></p>
|
|
<p>User Name: <b><%= renderSafe(param("name")); %></b></p>
|
|
</pre>
|
|
<a id="controls"></a>
|
|
<h2 class="section">Web Controls</h2>
|
|
<p>ESP includes a rich library of web control functions that easily generate HTML. These web controls
|
|
are integrated with the <a href="http://jquery.com/">jQuery</a> client-side JavaScript library.
|
|
<p>Controls are provided to create forms, buttons, input lists, checkboxes, selectable tabs, and tables.
|
|
<p>To the following control will emit a text label that will dynamically update using background AJAX requests.
|
|
This control will create the appropriate HTML to invoke the <em>data.esp</em> page every 1 second to
|
|
get the current time. The web page will transparently update with the data returned by <em>data.esp</em>.</p>
|
|
<pre><% Time: label("", "{ data-refresh: "data.esp", data-period: 1000 }"); %></pre>
|
|
<a id="binding"></a>
|
|
<h3>Database Binding</h3>
|
|
<p>To make it easy to display and update database data, ESP supports "data binding" where a database
|
|
record can be bound to a request form. Thereafter, the ESP web controls will take data from the record.
|
|
<pre>
|
|
<%
|
|
form(userRecord, 0);
|
|
input("name", 0);
|
|
input("address", 0);
|
|
button("commit", "OK", 0);
|
|
buttonLink("Cancel", "../index.esp", 0);
|
|
buttonLink("Delete", "destroy.esp");
|
|
endform();
|
|
%>
|
|
</pre>
|
|
<p>In this example, the <em>form</em> control <i>binds</i> the <em>userRecord</em>. The input controls
|
|
then retrieve the "name", and "address" fields from the database record and emit the appropriate HTML
|
|
input elements.</p>
|
|
<a id="sessions"></a>
|
|
<h2>Sessions and Flash</h2>
|
|
<p>ESP provides an integrated session store so that state can be shared across requests. Session variables
|
|
can be accessed using the <em>@@variable</em> directive in ESP pages or via the
|
|
<em>renderVar()</em> and <em>getSessionVar()</em> APIs.</p>
|
|
<p>Flash storage is a portion of the session storage used to pass messages and state to the next request
|
|
only. This is useful after a form, to add feedback messages to the next web page. Messages can be added
|
|
to flash storage via the <em>error</em>, <em>inform</em>, or <em>warn</em> APIs. </p>
|
|
<pre><% <b>inform</b>("Record updated"); %></pre>
|
|
|
|
<p>The <em>flash</em> web
|
|
control is used in the next web page to extract flash messages for display.</p>
|
|
<pre><% <b>flash</b>("all", NULL); %></pre>
|
|
<a id="layouts"></a>
|
|
<h2>Layouts</h2>
|
|
<p>ESP Layouts provide a powerful and flexible solution for implementing a consistent UI.
|
|
ESP pages use layout pages that define the look and feel of an application. Content pages are
|
|
then rendered by merging with one or more layout pages that define the look and feel of the
|
|
application to create a composite page that the user will actually see. In this way, a web
|
|
application can easily maintain a consistent look and feel without repeating boilerplate code
|
|
from page to page. </p>
|
|
|
|
<p>A layout page provides template for the page and defines the location for the content via a
|
|
<em><%@ content %></em> directive.</p>
|
|
<pre>
|
|
<html>
|
|
<body>
|
|
<div class="top">
|
|
<img src="banner.jpg" />
|
|
</div>
|
|
<div class="content">
|
|
<b><%@ content %></b>
|
|
</div>
|
|
</body>
|
|
</html>
|
|
</pre>
|
|
<p>A content page defines only the HTML and code that is unique for a specific page.
|
|
It is merged with a layout page by inserting the content and replacing the <em><%@ content %></em> tag
|
|
in the layout page.</p>
|
|
<p>To use a layout page, a layout directory must be defined in the <em>appweb.conf</em> configuration file
|
|
using the EspDir directive. With this directive, pages will use the
|
|
"<em>./layouts/default.esp</em>" layout page by default.
|
|
<pre>EspDir layout "./layouts"</pre>
|
|
<p>The ESP <em><%@ layout</em> directive may be used in web pages to control what layout page (if any)
|
|
is used for the page. </p>
|
|
<pre>
|
|
<%@ layout "custom-layout.esp" %>
|
|
<h1>Hello Bright World</h1>
|
|
</pre>
|
|
<a id="learn"></a>
|
|
<h2 class="section">Learn More ...</h2>
|
|
<p>That concludes a quick tour through some of the capabilities of the ESP web framework.</p>
|
|
<p>To learn more, please read:</p>
|
|
<ul>
|
|
<li><a href="../../../index.html">ESP Documentation</a></li>
|
|
<li><a href="../../../ref/esp/espArchitecture.html">ESP Architecture</a></li>
|
|
<li><a href="mvc.html">ESP MVC Framework</a></li>
|
|
<li><a href="mvcTour.html">ESP MVC Tour</a>
|
|
</ul>
|
|
<p>You may also like to ask questions at the
|
|
<a href="http://appwebserver.org/forum/">Appweb Support Forum</a>.</p>
|
|
</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>
|