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.
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.
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.
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.
Read more about skeletons in Application Skeletons.
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.
The esp init and pak commands will make directories when creating an application or installing packages and generating components.
|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|