Embedded Server Pages™

Embedded Server Pages (ESP) are a collection of technologies developed by Mbedthis to provide embeddable, standards-based dynamic web page generation. Similar in its ultimate goal to Active Server Pages (ASP) and Java Server Pages (JSP), Embedded Server Pages enables the creation of web pages using page layout tools such as Dreamweaver yet still allow the inclusion of dynamic data within the page.

Embedded Server Pages was designed exclusively to be suitable for embedding in applications and devices. It provides a close binding between your application and the web page to be displayed making it very easy to generate dynamic data.

The AppWeb ESP architecture allows multiple scripting engines to be used at the same time. AppWeb is provided with server Embedded JavaScript, but other scripting engines such as TCL, Perl or Python may easily leverage this open scripting architecture in the future.

Example ESP Web Page

So what does an ESP HTML web page look like? ESP pages are standard HTML pages with ESP tags containing scripting logic. ESP tags use the delimiters <% and %> to bracket the scripting code.

<% Script Code Here %>

This script code is executed and replaced with the script output on the server side. The client never sees the script logic. The following example demonstrates just a few of the constructs available using ESP.

<HTML><HEAD><TITLE>Simple ESP Test Page</TITLE></HEAD>

<BODY>

<P>The HTML query string for this page is @@QUERY_STRING</P>

<!-- This quickly generates a very large table -->
<TABLE>
<% for (i = 0; i < 3; i++) { %>
<TR><TD>Line</TD><TD>@@i</TD>
<% } %>
</TABLE>

<!-- Sample ESP procedure calls -->
<% displayCurrentSecurityStats("myDb", 1); %>

<%
// Inside JavaScript blocks, we can put any server-side
// JavaScript we like

i = 2;
write("i is " + i); 
%>
 
</BODY>
</HTML>

As you can see, the page is standard HTML with ESP tag delimited JavaScript. What makes this especially interesting, is that you can easily create new Embedded JavaScript procedures in your application to suite your needs. These can then be called from the ESP web pages. This close nexus between the HTML page and your application logic is what makes AppWeb such an easy platform to use to create dynamic web pages.

How to Use ESP in HTML Pages

ESP pages typically have a ".esp" extension and are processed by the ESP AppWeb handler. ESP pages look like typical HTML pages with the exception that scripts may be specified within the page.

The ESP handler compiles ESP pages into pure JavaScript procedures that are executed when the client requests the page. When executed, the JavaScript procedures run and can display the relevant dynamic data.

Don't confuse ESP with client side JavaScript. A single page may have both. ESP JavaScript is between <% and %> tags and is replaced by the AppWeb server before it is ever sent to the client. Once the page reaches the clients browser, it will execute any client side JavaScript which is typically between <SCRIPT> and </SCRIPT> tags.

Embedded JavaScript Procedures

JavaScript procedures look like C functions with the exception that the arguments are typeless. The procedures can return a result which can be assigned to a JavaScript variable.

Generally it is best to create general ESP procedures that can be used to access a range of dynamic data depending on  the parameters provided to the script procedure. For example, it is better to create a dbRead procedure that reads specified database tables, columns and rows, rather than a dbReadFirstRowInCustomerTable.

Page Creation Tools

You may use your favorite HTML editor to create Embedded Server Pages. Dreamweaver is perhaps one of the best, but there are other fine choices. If your HTML editor supports ASP script editing, you may be able to use this feature as ASP uses the same <% %> delimiters as ESP. Otherwise, create your page using the page layout tool and then switch to the HTML code view to insert the ESP scripting at the relevant locations.

Standard ESP Procedures

AppWeb supplies some useful Embedded JavaScript procedures with the product. These may be called from within an ESP page without any C or C++ coding required.

Script Name
Syntax
Examples
Description
include
include(filename);
include("myLib.js");
Server side inclusion of a JavaScript library. The nominated file is read and parsed inline when the page is compiled by AppWeb.
write
write(args, ...);
write("Hello World");
write("<h1>Today is ", date);
Write the given arguments back to the client (browser) in the place of the ESP script. Multiple calls to write and its derivatives may be used.

Server Side Includes

The AppWeb ESP implementation also supports server side includes. To include another document use the directive:

<% include fileName %>

This will replace the ESP script with the content of the nominated filename The included file is assumed to be an ESP page that will be parsed at the point of the include directive. It may contain further ESP tags and include directives.

You can also include pure Embedded JavaScript code using the include JavaScript procedure:

<% include("myLib.js"); %>

In this case, the included file must contain pure JavaScript and NO ESP.

Accessing Variables

There are three methods to access JavaScript variables within ESP scripts. You can use the ESP write procedure to output the value of a variable back to the client. For example, assuming you have the current temperature in a JavaScript variable called temp.

<P>Today's temperature is <% write(temp) %></P>

As this kind of variable access is a very common occurrence, a shorter form may be more convenient. Because the JavaScript assignment operators sets the result, it can be used to return a value to the client. For example:

<P>Today's temperature is <% =temp; %></P>

Even easier is to use the @@ directive which does not require any <% %> enclosing tags. You use this by prepending the required variable with @@. For example:

<P>Today's temperatore is @@temperature</P>

How to Create ESP Procedures

You can easily create Embedded Server Page procedures in both C and C++ languages.

ESP Procedures in C++

To create an ESP procedure you subclass the MaEspProc class and override the run method. The run method is called whenever the procedure is run by the ESP handler. For example, the following code fragment creates an ESP procedure that will be invoked when an ESP page specifies <% myEsp(); %>.

#include "appWeb/appWeb.h"

class MyEsp : public MaEspProc {
public:
MyEsp() : MaEspProc("myEsp") {};
~MyEsp() {};
int run(MaRequest *rq, int argc, char **argv);
};

int MyEsp::run(MaRequest *rq, int argc, char **argv)
{
rq->write("Hello World");
return 0;
}

// Somewhere in the main program
new MyEsp();

You can also provide constructors and destructors for your class if you have persistent data structures that you need create.

NOTE: the run method is essentially stateless. Per session data storage is not explicitly supported by ESP though you can easily construct this yourself.

ESP Procedures in C

To create an ESP procedure in C, you create a function to execute when the ESP procedure is invoked and bind that function to the ESP script name. For example, the following code fragment creates an ESP procedure that will be invoked when an ESP page specifies <% myEsp(); %>.

#include "appWeb/appWeb.h"

static int myEspProc(MaRequest *rq, int argc, char **argv)
{
maWriteStr("Hello World");
}

// Somewhere in the main program
maDefineEsp("myEsp", myEspProc);

NOTE: the run method is essentially stateless. Per session data storage is not explicitly supported by ESP though you can easily construct this yourself.

Tips for ESP Procedures

Returning a Result

ESP Procedures may return a result that can then be assigned to JavaScript variables within the ESP page. To return a result, use the maSetResult call in C and the scriptEngine->setResult call in C++. See the simpleEsp sample for details. For example, the ESP page fragment uses the result of a database read call and tests the returned value before conditionally displaying a message.

<% 
temperature = dbRead("myDb", "system", "temperature");

if (temperature > 100) {
write("Wow it is hot");
}
%>

Don't use Write Too Much

You can use write within an ESP script. However it is often more conventient to invert the script. For example:

<% 
temperature = dbRead("myDb", "system", "temperature");
write("Today's temperature is <b>", temperature, "</b> degrees);
%>

is better written as:

<% temperature = dbRead("myDb", "system", "temperature"); %>
Today's temperature is <b>@@temperature</b>



© Mbedthis Software LLC, 2003-2204. All rights reserved. Mbedthis is a trademark of Mbedthis Software LLC.