368 lines
17 KiB
HTML
368 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>HTML Controls</b>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="content">
|
||
|
|
<div class="contentRight">
|
||
|
|
<h1>Quick Nav</h1>
|
||
|
|
<ul class="nav">
|
||
|
|
<li><a href="#families">Control Families</a></li>
|
||
|
|
<li><a href="#ajax">Ajax Libraries</a></li>
|
||
|
|
<li><a href="#database">Database Integration</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">
|
||
|
|
<!--
|
||
|
|
<pre>
|
||
|
|
- Overview
|
||
|
|
- Why controls
|
||
|
|
- Eliminate the page refresh
|
||
|
|
- Dynamic updating
|
||
|
|
- Role of client-side JavaScript and libraries
|
||
|
|
- List of controls
|
||
|
|
- Links to per-control discussions
|
||
|
|
- How options are handled
|
||
|
|
- Standard options
|
||
|
|
- jQuery / Ajax support
|
||
|
|
- minified libraries
|
||
|
|
- More on attribute behavior
|
||
|
|
key/keyFormat
|
||
|
|
- More links to API doc
|
||
|
|
- URIs
|
||
|
|
How to use uri()
|
||
|
|
@controller/action
|
||
|
|
- redirecting to "@"
|
||
|
|
- Dynamic refresh
|
||
|
|
- Using database integration
|
||
|
|
- current record
|
||
|
|
- Open databases in appweb.conf
|
||
|
|
- Using controls without a database
|
||
|
|
- Per controls
|
||
|
|
- form errors
|
||
|
|
- Style sheets and theming
|
||
|
|
- text and escaping data - escape option, renderSafe()
|
||
|
|
</pre>
|
||
|
|
-->
|
||
|
|
<h1>ESP HTML Controls</h1>
|
||
|
|
<p>Generating HTML directly to create a dynamic web user interface can be tedious, slow and prone to
|
||
|
|
inconsistencies and errors. Client-side JavaScript libraries can help, but increasingly, the task of
|
||
|
|
extensive integration with such libraries can also become burdensome. What is needed is a higher level of
|
||
|
|
abstraction that can automatically generate most HTML including integration with client-side libraries.</p>
|
||
|
|
<p>ESP provides such a higher level via its rich library of HTML control functions. ESP Controls are
|
||
|
|
provided to generate tables and tabbed property sheets, and manage input forms and fields. Furthermore,
|
||
|
|
these controls are pre-integrated with the jQuery client-side JavaScript library and may optionally bind
|
||
|
|
with server-side databases. ESP controls make it easy to create dynamically updating tables, perform background
|
||
|
|
page updates and do automatic user feedback and form validation.</p>
|
||
|
|
<h2>Sample</h2>
|
||
|
|
<p>In essence, ESP HTML controls are functions that can be called anywhere in an ESP page or ESP
|
||
|
|
controller. Based on their arguments, they emit HTML and jQuery calls into the client response.
|
||
|
|
Here is a quick sample of some of the ESP controls in action:</p>
|
||
|
|
<pre>
|
||
|
|
buttonLink("New Post", "@init", 0);
|
||
|
|
table(data, "{ \
|
||
|
|
columns: { \
|
||
|
|
id: { header: 'ID' }, \
|
||
|
|
title: { header: 'TITLE' }, \
|
||
|
|
body: { header: 'BODY' }, \
|
||
|
|
}");
|
||
|
|
</pre>
|
||
|
|
<a id="families"></a>
|
||
|
|
<h2 class="section">ESP Control Families</h2>
|
||
|
|
<p>ESP Controls are grouped into two families:
|
||
|
|
<ul>
|
||
|
|
<li>Form-based controls that do input
|
||
|
|
<li>Non form-based that do output and other tasks
|
||
|
|
</ul>
|
||
|
|
<p>Form-based controls are typically located inside a <em>form</em>, <em>endform</em> control
|
||
|
|
pair that defines a current database record from which data will be utilized. Non form-based controls
|
||
|
|
can be used anywhere on a page outside a form/endform pair.</p>
|
||
|
|
<h2>HTML Controls</h2>
|
||
|
|
<table title="controls">
|
||
|
|
<thead>
|
||
|
|
<tr>
|
||
|
|
<th>Name</th>
|
||
|
|
<th>Form</th>
|
||
|
|
<th>Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<td>alert</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Display a popup alert message in the client's browser</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>anchor</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render an HTML anchor link</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>button</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a form button</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>buttonLink</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a link button</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>chart</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a graphical chart</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>checkbox</td>
|
||
|
|
<td>Form</td>
|
||
|
|
<td>Render an input checkbox</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>division</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render an HTML division</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>dropdown</td>
|
||
|
|
<td>Form</td>
|
||
|
|
<td>Render a dropdown selection list</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>endform</td>
|
||
|
|
<td>Form pair</td>
|
||
|
|
<td>Signify the end of an HTML form</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>flash</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render flash messages</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>form</td>
|
||
|
|
<td>Form pair</td>
|
||
|
|
<td>Render an HTML form</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>icon</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render an image</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>image</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render an image</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>input</td>
|
||
|
|
<td>Form</td>
|
||
|
|
<td>Smart input control. Delegates depending on the data type.</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>label</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a text label</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>mail</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a mail link</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>progress</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a progress bar</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>radio</td>
|
||
|
|
<td>Form</td>
|
||
|
|
<td>Render an input radio button</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>refresh</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Control the refresh of web page dynamic elements</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>script</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a script tag</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>securityToken</td>
|
||
|
|
<td>Form</td>
|
||
|
|
<td>Generate a security token to add to a form submission </td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>stylesheet</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a stylesheet tag</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>table</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a table</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>tabs</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a tab selection control</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>text</td>
|
||
|
|
<td>Form</td>
|
||
|
|
<td>Render an input text field</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td>tree</td>
|
||
|
|
<td>Non-form</td>
|
||
|
|
<td>Render a tree control</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
<h2>ESP Control Options</h2>
|
||
|
|
<p>ESP controls are generally of the form: function(args ..., options). The options argument is an optional
|
||
|
|
set of properties that can be used to modify the behavior of the control. It is expressed as a
|
||
|
|
<a href="http://en.wikipedia.org/wiki/JSON">JSON</a> string where a set of properties are enclosed in
|
||
|
|
braces. Each keyword is followed by a colon. It helps to use single quotes around property values
|
||
|
|
and to use double quotes around the entire option string. For example: </p>
|
||
|
|
<pre>
|
||
|
|
label("Hello World", "{ effects: 'fadein' }");
|
||
|
|
</pre>
|
||
|
|
<p>ESP supports a large suite of options, but there is a common set that are applicable to most ESP controls.</p>
|
||
|
|
<table title="options">
|
||
|
|
<thead>
|
||
|
|
<tr><th>Option</th><th>Purpose</th></tr>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<tr><td>action</td><td>Action function to invoke</td></tr>
|
||
|
|
<tr><td>apply</td><td>Client jQuery selector identifying the element to receive the update</td></tr>
|
||
|
|
<tr><td>background</td><td>Background color</td></tr>
|
||
|
|
<tr><td>click</td><td>URI to invoke if the control is clicked</td></tr>
|
||
|
|
<tr><td>color</td><td>Foreground color</td></tr>
|
||
|
|
<tr><td>confirm</td><td>Message to prompt user before submitting a form</td></tr>
|
||
|
|
<tr><td>controller</td><td>Controller owning the action to invoke</td></tr>
|
||
|
|
<tr><td>data-*</td><td>Attributes to pass through to the generated HTML</td></tr>
|
||
|
|
<tr><td>domid</td><td>Client-side DOM ID for the control</td></tr>
|
||
|
|
<tr><td>effects</td><td>Transition effects: "fadein", "fadeout", "highlight"</td></tr>
|
||
|
|
<tr><td>escape</td><td>HTML escape text before rendering</td></tr>
|
||
|
|
<tr><td>height</td><td>Height of the HTML control</td></tr>
|
||
|
|
<tr><td>key</td><td>Key values to add to the click URI</td></tr>
|
||
|
|
<tr><td>keyFormat</td><td>Define how the keys will be added to the URI</td></tr>
|
||
|
|
<tr><td>id</td><td>Numeric database record ID</td></tr>
|
||
|
|
<tr><td>method</td><td>HTTP method to invoke</td></tr>
|
||
|
|
<tr><td>pass</td><td>Additional attributes to pass through to the client unaltered</td></tr>
|
||
|
|
<tr><td>params</td><td>Request parameters to include with a click or remote request</td></tr>
|
||
|
|
<tr><td>period</td><td>Period in milliseconds between invoking a refresh of the control data</td></tr>
|
||
|
|
<tr><td>query</td><td>URI query string to add to the URI</td></tr>
|
||
|
|
<tr><td>rel</td><td>HTML rel attribute. Use to generate "rel='nofollow' link attributes</td></tr>
|
||
|
|
<tr><td>remote</td><td>Perform the request in the background without changing the browser location</td></tr>
|
||
|
|
<tr><td>refresh</td><td>URI to invoke in the background to refresh the control data</td></tr>
|
||
|
|
<tr><td>size</td><td>Size of the element</td></tr>
|
||
|
|
<tr><td>style</td><td>CSS style to use for the element</td></tr>
|
||
|
|
<tr><td>value</td><td>Override the value to display</td></tr>
|
||
|
|
<tr><td>width</td><td>HTML width of the control</td></tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
<a id="ajax"></a>
|
||
|
|
<h2 class="section">AJAX and Client JavaScript Libraries</h2>
|
||
|
|
<p>Web applications split their processing between the server and the client. Increasingly, more processing
|
||
|
|
is being done at the client to give a better overall user experience. <a href=
|
||
|
|
"http://en.wikipedia.org/wiki/Ajax_(programming)">Ajax</a> programming has risen as one of the more popular
|
||
|
|
means of achieving a responsive client user interface and <a href="http://jquery.com/">jQuery</a> has emerged as
|
||
|
|
one of the best client-side Ajax libraries.</p>
|
||
|
|
|
||
|
|
<p>Consequently, it is very important that the server-side
|
||
|
|
web framework integrate well with the client-side JavaScript library. ESP is thoroughly integrated
|
||
|
|
with jQuery and provides a jQuery client-side adapter and automatically generates the necessary HTML and
|
||
|
|
jQuery calls for dynamic and background requests.</p>
|
||
|
|
<a id="database"></a>
|
||
|
|
<h2 class="section">Database Integration</h2>
|
||
|
|
<a id="dynamic"></a>
|
||
|
|
<h3>Dynamic Controls</h3>
|
||
|
|
<p>ESP controls can dynamically retrieve data from databases and refresh their contents automatically.
|
||
|
|
Here is an example of a table configured to display stock market data in a grid with the current price
|
||
|
|
for each stock. The grid will refresh its data every 2 seconds without updating the entire web page.</p>
|
||
|
|
<pre>
|
||
|
|
<%
|
||
|
|
table(readTable("stock"), {
|
||
|
|
refresh: 2,
|
||
|
|
})
|
||
|
|
%>
|
||
|
|
</pre>
|
||
|
|
</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>
|