Creating ESP Applications

To start a new ESP web application or web site, first create a new directory named for the application, then run esp init.

$ mkdir demo $ cd demo $ esp init

This will prepare your application to run ESP by generating two configuration files and creating a dist directory to hold your rendered application.

The pak.json file to describe the name and version of your application with any installed packages.
The esp.json file to configure ESP and HTTP.
The dist directory is the final distribution directory for web content after rendering.

You can now create web pages to be served by ESP. Create a test ESP page under the dist directory called dist/index.esp with the contents:

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

If a directory named dist is not present, esp will serve web content from the current directory. It is more secure to have only the public web documents being visible in a dist directory.

Running

To run your application, run esp serve to serve browser requests.

$ esp serve

You can also just run a plain esp command without arguments. It is the same as esp serve.

$ esp

You can now browse to http://localhost:4000/index.esp to see the new page. The first time, there will be a brief pause as the page is compiled and saved in the cache directory. Next time, the page will be served from memory. If you modify the page, it will be transparently re-compiled. If you restart esp the cached module will be loaded and the page will not be re-compiled.

Skeletons

There is another way to create ESP applications and that is by installing ESP skeletons. Skeletons are integrated starter packages for ESP applications. Skeletons typically include default web pages, layouts, partial pages, stylesheets, scripts and required dependent packages for an easy, one-step launch of your web application.

Installing skeletons is easy via the Pak utility. For example, to install esp-html-skeleton.

$ pak install embedthis/esp-html-skeleton [Install] exp-js 0.3.2 [Install]
  exp-less 0.3.0 [Install] exp-css 0.3.1 [Install] exp-esp 0.3.1 [Install]
  exp-html 0.2.0 [Install] exp-canon 0.3.0 [Install] esp-mvc 5.5.2 [Install]
  esp-html-skeleton 5.5.1

This installs the esp-html-skeleton and all dependent packages. The skeleton includes:

A default layout page layouts/default.html.exp
Partial pages for page headers, footers and navigation: partials/header.html.exp, partials/footer.html.exp and partials/nav.html.exp
Less stylesheet contents/css/app.less
Expansive plugin packages to manage scripts, Less and CSS stylesheets.
The exp-esp plugin package to compile ESP pages and run ESP applications.

Files with a .html.exp extension are files that may contain server-side Javascript that Expansive will run at development render-time. To render and server pages, run expansive.

$ expansive

Read more about skeletons in Application Skeletons.

Configuration Files

The three configuration files esp.json, pak.json and expansive.json play a central role in configuring and managing the evolution of your application. Read more about these files in Configuring ESP.

Directories

The esp init and pak commands will make directories when creating an application or installing packages and generating components.

Directory	Purpose
cache	Cached shared libraries for compiled controllers and pages
contents	Input web content source directory used by Expansive when rendering into the dist directory.
dist	Directory of web content to serve to browser clients. Files outside the dist directory are not visible to the client. If a dist directory does not exist, files in the current directory will be served.
dist/images	Client side assets: images and media
dist/css	Client side CSS
dist/lib	Rendered library content originally sourced from installed packages.
controllers	ESP controller C source code
db	Databases and database migrations
layouts	Layout template pages used by Expansive. Layouts provide the master page look and feel. Layout pages provide the outer HTML that wraps individual content pages.
lib	Library content for installed packages. These files are copied from the paks directory for scripts, stylesheets, fonts and resources that should be rendered to the dist directory.
migrations	Database migration scripts
paks	Installed packages. This is the location of the package's raw content. Required files are exported into the lib directory and ultimately into the dist directory when the site is rendered by Expansive.
partials	Partial ESP pages used by Expansive. These pages may be included by content or layout pages.
src	Other application C source code