Embedthis Appweb 4.3.4
Home >ESP Guide> HTML Controls

# Quick Nav

# See Also

# ESP HTML Controls

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.

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.

## Sample

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:

    buttonLink("New Post", "@init", 0);
    table(data, "{ \
        columns: { \
            id: { header: 'ID' }, \
            title: { header: 'TITLE' }, \
            body: { header: 'BODY' }, \
        }");

## ESP Control Families

ESP Controls are grouped into two families:

- Form-based controls that do input
- Non form-based that do output and other tasks

Form-based controls are typically located inside a form, endform 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.

## HTML Controls

Name | Form | Description
--- | --- | ---
alert | Non-form | Display a popup alert message in the client's browser
anchor | Non-form | Render an HTML anchor link
button | Non-form | Render a form button
buttonLink | Non-form | Render a link button
chart | Non-form | Render a graphical chart
checkbox | Form | Render an input checkbox
division | Non-form | Render an HTML division
dropdown | Form | Render a dropdown selection list
endform | Form pair | Signify the end of an HTML form
flash | Non-form | Render flash messages
form | Form pair | Render an HTML form
icon | Non-form | Render an image
image | Non-form | Render an image
input | Form | Smart input control. Delegates depending on the data type.
label | Non-form | Render a text label
mail | Non-form | Render a mail link
progress | Non-form | Render a progress bar
radio | Form | Render an input radio button
refresh | Non-form | Control the refresh of web page dynamic elements
script | Non-form | Render a script tag
securityToken | Form | Generate a security token to add to a form submission
stylesheet | Non-form | Render a stylesheet tag
table | Non-form | Render a table
tabs | Non-form | Render a tab selection control
text | Form | Render an input text field
tree | Non-form | Render a tree control

## ESP Control Options

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 JSON 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:

    label("Hello World", "{ effects: 'fadein' }");

ESP supports a large suite of options, but there is a common set that are applicable to most ESP controls.

Option | Purpose
--- | ---
action | Action function to invoke
apply | Client jQuery selector identifying the element to receive the update
background | Background color
click | URI to invoke if the control is clicked
color | Foreground color
confirm | Message to prompt user before submitting a form
controller | Controller owning the action to invoke
data-* | Attributes to pass through to the generated HTML
domid | Client-side DOM ID for the control
effects | Transition effects: "fadein", "fadeout", "highlight"
escape | HTML escape text before rendering
height | Height of the HTML control
key | Key values to add to the click URI
keyFormat | Define how the keys will be added to the URI
id | Numeric database record ID
method | HTTP method to invoke
pass | Additional attributes to pass through to the client unaltered
params | Request parameters to include with a click or remote request
period | Period in milliseconds between invoking a refresh of the control data
query | URI query string to add to the URI
rel | HTML rel attribute. Use to generate "rel='nofollow' link attributes
remote | Perform the request in the background without changing the browser location
refresh | URI to invoke in the background to refresh the control data
size | Size of the element
style | CSS style to use for the element
value | Override the value to display
width | HTML width of the control

## AJAX and Client JavaScript Libraries

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. Ajax programming has risen as one of the more popular means of achieving a responsive client user interface and jQuery has emerged as one of the best client-side Ajax libraries.

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.

## Database Integration

### Dynamic Controls

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.

    <%
        table(readTable("stock"), {
            refresh: 2,
        })
    %>

© Embedthis Software LLC, 2003-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.