ESP Tour

This quick tour of the ESP Web Framework provides an overview of ESP and how to use it to create ESP pages and ESP applications.

There are two other tours:

The ESP MVC Application Tour — for server-side MVC applications
The ESP SPA Application Tour — for client-side Single Page Applications (SPA)

Before you start, make sure you have read the Quick Start and that you have ESP installed on your system so you can try the commands as you go.

Download ESP

Running ESP

The ESP web framework includes a utility program called esp that is used to initialize and then run your application.

To start the tour, create a directory to contain your ESP application and then from that directory, run esp. In this example, we create a directory called "test". The directory name is used as the default name for your application, so choose a name that can be a valid C identifier.

$ mkdir test
$ cd test
$ esp
esp: 2: Started HTTP service on "127.0.0.1:4000"
esp: 1: Started at Mon Apr 14 15:00:42 2014 PDT

ESP is now running and ready to serve documents from the "test" directory.

Hello World

The first step in any tour is to create a simple "Hello World" web page. ESP web pages have an .esp extension. Create a file called hello.esp using your favorite text editor in the test directory with the following content:

<html>
<body>
<h1>Hello World</h1>
</body>

To view the "Hello" web page, type the following URL: http://localhost:4000/hello.esp into your browser.

Dynamic Content

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:

<%= expression %>

To add the current date and time, modify the hello.esp web page and add the highlighted line:

<h1>Hello Bright World</h1>
<h2>Generated on <%= mprGetDate(0); %></h2>

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.

No Restart Required

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. The loaded module is cached in-memory and on-disk for fast execution by subsequent requests.

In the output from the esp command, you may have noticed:

esp: 2: GET /hello.esp HTTP/1.1
esp: 2: esp: compile hello.esp
esp: 2: Loading native module view_d2f3bdb8df0a0f0b440ea83c81b618c5.dylib
esp: 2:   HTTP/1.1 200 OK

This output traces each request and response, but also notifies you that the page was recompiled. Any request or page syntax errors will be show in the esp log output.

You can also embed arbitrary C code in your ESP page, like:

<h3><% render("Request method is %s", getMethod()); %></h3>
<%
    int i;
    for (int i = 0; i < 10; i++) {
        render(" Line: %d</br>\r\n", i);
    }
%>

By using the ESP statement directive <% code %>, you can embed arbitrary C language statements in your web page. The render function allows you to write arbitrary data which is patched back where the directive was defined in the page. See the ESP Pages document for full details about all the ESP web page directives.

For help on the esp utility, use man esp or invoke esp with the esp -help switch.

$ man esp
$ esp -help

Learn More ...

That concludes a quick tour through some of the capabilities of the ESP web framework. To learn more, please read: