View

Moduleejs.web
Namespace"ejs.web"
Definitiondynamic class View
InheritanceView inherit Object

Base class for web framework views.

This class provides the core functionality for all Ejscript view web pages. Ejscript web pages are compiled to create a new View class which extends the View base class. In addition to the properties defined by this class, user view classes will inherit at runtime all public properites of the current controller object.


Properties

QualifiersPropertyTypeDescription
ejs.web controllerControllerCurrent controller TODO - consistency. Should this be currentController.

View Methods

QualifiersMethod
aform(action: String, record: Object, options: Object): Void
 Render an asynchronous (ajax) form.
alink(text: String, action: String, options: Object): Void
 Emit an asynchronous (ajax) link to an action.
button(value: String, buttonName: String, options: Object): Void
 Render a form button.
buttonLink(text: String, action: String, options: Object): Void
 Render a link button.
chart(initialData: Array, options: Object): Void
 Render a chart.
checkbox(field: String, choice: String, options: Object): Void
 Render an input checkbox.
createSession(timeout: Number): Void
 Enable session control.
currency(fmt: String): String
 Temporary helper function to format a number as currency.
d(args: Array): Void
 Dump objects for debugging.
date(fmt: String): String
 Temporary helper function to format the date.
destroySession(): Void
 Destroy a session.
endform(): Void
 End an input form.
extlink(text: String, url: String, options: Object): Void
 Emit an application relative link.
flash(kinds, options: Object): Void
 Emit a flash message area.
form(action: String, record: Object, options: Object): Void
getOptions(options: Object): String
 Map options to a HTML attribute string.
getValue(model: Object, field: String, options: Object): String
html(args: Array): String
 HTML encode the arguments.
image(image: String, options: Object): Void
 Render an image control.
input(field: String, options: Object): Void
 Render an input field as part of a form.
label(text: String, options: Object): Void
 Render a text label field.
link(text: String, action: String, options: Object): Void
 Emit a link to an action.
list(field: String, choices: Object, options: Object): Void
mail(nameText: String, address: String, options: Object): Void
 Emit a mail link.
makeUrl(action: String, id: String, options: Object): String
 Duplicate Controller.
number(fmt: String): String
 Temporary helper function to format a number.
progress(initialData: Object, options: Object): Void
 Emit a progress bar.
radio(field: String, choices: Object, options: Object): Void
 Emit a radio autton.
redirect(action: String, id: String, options: Object): Void
 Redirect to the given action Options: id controller.
redirectUrl(url: String, code: Number): Void
 Redirect the client to a new URL.
public render(): Void
 Process and emit a view to the client.
script(url: Object, options: Object): Void
 Emit a script link.
setCookie(name: String, value: String, lifetime: Number, path: String, secure: Boolean): Void
 Define a cookie header to include in the reponse TODO - reconsider arg order.
setHeader(key: String, value: String, allowMultiple: Boolean): Void
 Of the format "keyword: value".
setHttpCode(code: Number): Void
 Set the HTTP response status code.
setMimeType(format: String): Void
 Set the response body mime type.
status(initialData: Object, options: Object): Void
 Emit a status control area.
stylesheet(url: Object, options: Object): Void
 Emit a style sheet link.
table(data: Array, options: Object): Void
 Render a table.
tabs(initialData: Array, options: Object): Void
 Render a tab control.
text(field: String, options: Object): Void
 Render a text input field as part of a form.
textarea(field: String, options: Object): Void
 Render a text area.
tree(initialData: XML, options: Object): Void
 Render a tree control.
View(controller: Controller)
 Constructor method to initialize a new View.
write(args: Array): Void
 Duplicate Controller.
writeHtml(args: Array): Void
 Write HTML escaped text to the client.
writeRaw(args: Array): Void
 Duplicate Controller.

Method Detail

aform(action: String, record: Object, options: Object): Void

Render an asynchronous (ajax) form.

Parameters
action: String Action to invoke when the form is submitted. Defaults to "create" or "update" depending on whether the field has been previously saved.
record: Object Model record to edit
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

url: String — Use a URL rather than action and controller for the target url.


alink(text: String, action: String, options: Object): Void

Emit an asynchronous (ajax) link to an action.

Description
The URL is constructed from the given action and the current controller. The controller may be overridden by setting the controller option.
Parameters
text: String Link text to display
action: String Action to invoke when the link is clicked
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

controller: String — Name of the target controller for the given action

url: String — Use a URL rather than action and controller for the target url.


button(value: String, buttonName: String, options: Object): Void

Render a form button.

Description
This creates a button suitable for use inside an input form. When the button is clicked, the input form will be submitted.
Parameters
value: String Text to display in the button.
options: Object Optional extra options. See $getOptions for a list of the standard options. Examples: button("Click Me", "OK")
buttonName: String

buttonLink(text: String, action: String, options: Object): Void

Render a link button.

Description
This creates a button suitable for use outside an input form. When the button is clicked, the associated URL will be invoked.
Parameters
text: String Text to display in the button.
options: Object Optional extra options. See $getOptions for a list of the standard options.

chart(initialData: Array, options: Object): Void

Render a chart.

Description
The chart control can display static or dynamic tabular data. The client chart control manages sorting by column, dynamic data refreshes, pagination and clicking on rows.
Parameters
initialData: Array Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data.
options: Object Object Optional extra options. See also $getOptions for a list of the standard options.

Options

columns: Object — hash of column entries. Each column entry is in-turn an object hash of options. If unset, all columns are displayed using defaults.

kind: String — Type of chart. Select from: piechart, table, linechart, annotatedtimeline, guage, map, motionchart, areachart, intensitymap, imageareachart, barchart, imagebarchart, bioheatmap, columnchart, linechart, imagelinechart, imagepiechart, scatterchart (and more)

onClick: String — Action or URL to invoke when a chart element is clicked.

Example
<% chart(null, { data: "getData", refresh: 2" }) %> <% chart(data, { onClick: "action" }) %>

checkbox(field: String, choice: String, options: Object): Void

Render an input checkbox.

Description
This creates a checkbox suitable for use within an input form.
Parameters
field: String Name of the field to display. This is used to create a HTML "name" and "id" attribute for the input element. If used inside a model form, it is the field name in the model containing the checkbox value to display. If used without a model, the value to display should be passed via options.value.
choice: String Value to submit if checked
options: Object Optional extra options. See $getOptions for a list of the standard options.

createSession(timeout: Number): Void

Enable session control.

Description
This enables session state management for this request and other requests from the browser. If a session has not already been created, this call creates a session and sets the.
Parameters
timeout: Number Optional timeout for the session in seconds. If ommitted the default timeout is used.

currency(fmt: String): String

Temporary helper function to format a number as currency.

Description
TODO.
Parameters
fmt: String Format string
Returns
A formatted string.

d(args: Array): Void

Dump objects for debugging.

Parameters
args: Array List of arguments to print.

date(fmt: String): String

Temporary helper function to format the date.

Description
TODO.
Parameters
fmt: String Format string
Returns
A formatted string.

destroySession(): Void

Destroy a session.

Description
This call destroys the session state store that is being used for the current client. If no session exists, this call has no effect.

endform(): Void

End an input form.

Description
This closes an input form initiated by calling the $form method.

extlink(text: String, url: String, options: Object): Void

Emit an application relative link.

Description
If invoking an action, it is safer to use \a action.
Parameters
text: String Link text to display
url: String Action or URL to invoke when the link is clicked
options: Object Optional extra options. See $getOptions for a list of the standard options.

flash(kinds, options: Object): Void

Emit a flash message area.

Parameters
kinds Kinds of flash messages to display. May be a single string ("error", "inform", "message", "warning"), an array of strings or null. If set to null (or omitted), then all flash messages will be displayed.
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

retain: Number. — Number of seconds to retain the message. If <= 0, the message is retained until another message is displayed. Default is 0.

Example
<% flash("status") %> <% flash() %> <% flash(["error", "warning"]) %>

form(action: String, record: Object, options: Object): Void

getOptions(options: Object): String

Map options to a HTML attribute string.

Parameters
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

background: String — Background color. This is a CSS RGB color specification. For example "FF0000" for red.

color: String — Foreground color. This is a CSS RGB color specification. For example "FF0000" for red.

data: String — String URL or action to get data for dynamic controls that support live refresh.

id: String — Browser element ID for the control

escape: Boolean — Escape the text before rendering. This converts HTML reserved tags and delimiters into an encoded form.

height: (Number|String) — Height of the table. Can be a number of pixels or a percentage string. Defaults to unlimited.

method: String — HTTP method to invoke. May be: GET, POST, PUT or DELETE.

refresh: Boolean — Defines the data refresh period for dynamic controls. Only valid if the data option is defined.

size: (Number|String) — Size of the element.

style: String — CSS Style to use for the control.

value: Default — data value to use for the control if not supplied by other means.

visible: Boolean — Make the control visible. Defaults to true.

width: (Number|String) — Width of the table or column. Can be a number of pixels or a percentage string.

Returns
A string containing the HTML attributes to emit.

getValue(model: Object, field: String, options: Object): String

html(args: Array): String

HTML encode the arguments.

Parameters
args: Array Variable arguments that will be converted to safe html
Returns
A string containing the encoded arguments catenated together.

image(image: String, options: Object): Void

Render an image control.

Parameters
options: Object Optional extra options. See $getOptions for a list of the standard options.
Example
<% image("myPic.gif") %> <% image("myPic.gif", { data: "getData", refresh: 2, style: "myStyle" }) %>

input(field: String, options: Object): Void

Render an input field as part of a form.

Description
This is a smart input control that will call the appropriate input control based on the model field data type.
Parameters
field: String Model field name containing the text data for the control.
options: Object Optional extra options. See $getOptions for a list of the standard options.
Example
<% input(modelFieldName) %> <% input(null, { options }) %>

label(text: String, options: Object): Void

Render a text label field.

Description
This renders an output-only text field. Use text() for input fields.
Parameters
text: String Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data.
options: Object Optional extra options. See $getOptions for a list of the standard options.
Example
<% label("Hello World") %> <% label(null, { data: "getData", refresh: 2, style: "myStyle" }) %>

link(text: String, action: String, options: Object): Void

Emit a link to an action.

Description
The URL is constructed from the given action and the current controller. The controller may be overridden by setting the controller option.
Parameters
text: String Link text to display
action: String Action to invoke when the link is clicked
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

controller: String — Name of the target controller for the given action

url: String — Use a URL rather than action and controller for the target url.


list(field: String, choices: Object, options: Object): Void

mail(nameText: String, address: String, options: Object): Void

Emit a mail link.

Parameters
nameText: String Recipient name to display
address: String Mail recipient address
options: Object Optional extra options. See $getOptions for a list of the standard options.

makeUrl(action: String, id: String, options: Object): String

Duplicate Controller.

Description
MakeUrl.
Parameters
id: String
options: Object

number(fmt: String): String

Temporary helper function to format a number.

Description
TODO.
Parameters
fmt: String Format string
Returns
A formatted string.

progress(initialData: Object, options: Object): Void

Emit a progress bar.

Parameters
initialData: Object Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data. Progress data is a simple Number in the range 0 to 100 and represents a percentage completion value.
options: Object Optional extra options. See $getOptions for a list of the standard options.
Example
<% progress(null, { data: "getData", refresh: 2" }) %>

radio(field: String, choices: Object, options: Object): Void

Emit a radio autton.

Description
The URL is constructed from the given action and the current controller. The controller may be overridden by setting the controller option.
Parameters
field: String Name of the field to display. This is used to create a HTML "name" and "id" attribute for the input element. If used inside a model form, it is the field name in the model containing the radio data to display. If used without a model, the value to display should be passed via options.value.
choices: Object Array or object containing the option values. If array, each element is a radio option. If an object hash, then they property name is the radio text to display and the property value is what is returned.
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

controller: String — Name of the target controller for the given action

value: String — Name of the option to select by default

Example
radio("priority", ["low", "med", "high"]) radio("priority", {low: 0, med: 1, high: 2}) radio(priority, Message.priorities)

redirect(action: String, id: String, options: Object): Void

Redirect to the given action Options: id controller.

Parameters
id: String
options: Object

redirectUrl(url: String, code: Number): Void

Redirect the client to a new URL.

Description
This call redirects the client's browser to a new location specified by the.
Parameters
url: String Url to redirect the client to
code: Number Optional HTTP redirection code

public render(): Void

Process and emit a view to the client.

Description
Overridden by the views invoked by controllers.

script(url: Object, options: Object): Void

Emit a script link.

Parameters
url: Object URL for the script to load
options: Object Optional extra options. See $getOptions for a list of the standard options.

setCookie(name: String, value: String, lifetime: Number, path: String, secure: Boolean): Void

Define a cookie header to include in the reponse TODO - reconsider arg order.

Parameters
secure: Boolean [default: false]

setHeader(key: String, value: String, allowMultiple: Boolean): Void

Of the format "keyword: value".

Description
If a header has already been defined and \a allowMultiple is false, the header will be overwritten. If \a allowMultiple is true, the new header will be appended to the response headers and the existing header will also be output. NOTE: case does not matter in the header keyword.
Parameters
allowMultiple: Boolean If false, overwrite existing headers with the same keyword. If true, all headers are output. [default: false]

setHttpCode(code: Number): Void

Set the HTTP response status code.

Parameters
code: Number HTTP response code to define

setMimeType(format: String): Void

Set the response body mime type.

Parameters
format: String Mime type for the response. For example "text/plain".

status(initialData: Object, options: Object): Void

Emit a status control area.

Parameters
initialData: Object Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data. Status data is a simple String. Status messages may be updated by calling the \a statusMessage function.
options: Object Optional extra options. See $getOptions for a list of the standard options.
Example
<% status("Initial Status Message", { data: "getData", refresh: 2" }) %>

stylesheet(url: Object, options: Object): Void

Emit a style sheet link.

Parameters
url: Object Stylesheet url or array of stylesheets
options: Object Optional extra options. See $getOptions for a list of the standard options.

table(data: Array, options: Object): Void

Render a table.

Description
The table control can display static or dynamic tabular data. The client table control manages sorting by column, dynamic data refreshes, pagination and clicking on rows.
Parameters
data: Array Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data. Table data is an Array of objects where each object represents the data for a row. The column names are the object property names and the cell text is the object property values.
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

click: String — Action or URL to invoke when the row is clicked.

columns: Object — hash of column entries. Each column entry is in-turn an object hash of options. If unset, all columns are displayed using defaults.

pageSize: Number — Number of rows to display per page. Omit or set to <= 0 for unlimited. Defaults to unlimited.

pivot: Boolean — Pivot the table by swaping rows for columns and vice-versa

showId: Boolean — If a columns option is not provided, the id column is normally hidden. To display, set showId to be true.

sortable: Boolean — Can the column be sorted on. Defaults to true.

sortColumn: String — Column to sort by. Defaults to first column. This option must be used within a column option.

sortOrder: String — Set to "ascending" or "descending". Defaults to ascending. This column must be used within a column option.

styleHead: String — CSS style to use for the table header cells

styleOddRow: String — CSS style to use for odd rows in the table

styleEvenRow: String — CSS style to use for even rows in the table

title: String — Table title Column options: header, width, sort, sortOrder

Example
<% table(null, { data: "getData", refresh: 2, pivot: true" }) %> <% table(data, { click: "edit" }) %> <% table(data, { pivot: true }) %> <% table(data, { click: "edit", columns: { product: { header: "Product", width: "20%", sort: "ascending" } date: { format: date('%m-%d-%y) } } }) %>

tabs(initialData: Array, options: Object): Void

Render a tab control.

Description
The tab control can display static or dynamic tree data.
Parameters
initialData: Array Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data. Tab data is an array of objects -- one per tab. For example: [{"Tab One Label", "action1"}, {"Tab Two Label", "action2"}]
options: Object Optional extra options. See $getOptions for a list of the standard options.

text(field: String, options: Object): Void

Render a text input field as part of a form.

Parameters
field: String Name of the field to display. This is used to create a HTML "name" and "id" attribute for the input element. If used inside a model form, it is the field name in the model containing the text data to display. If used without a model, the value to display should be passed via options.value.
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

escape: Boolean — Escape the text before rendering. This converts HTML reserved tags and delimiters into an encoded form.

style: String — CSS Style to use for the control

visible: Boolean — Make the control visible. Defaults to true.

Example
<% text("name") %>

textarea(field: String, options: Object): Void

Render a text area.

Parameters
field: String Name of the field to display. This is used to create a HTML "name" and "id" attribute for the input element. If used inside a model form, it is the field name in the model containing the text data to display. If used without a model, the value to display should be passed via options.value.
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

Boolean: escape — Escape the text before rendering. This converts HTML reserved tags and delimiters into an encoded form.

data: String — URL or action to get data

numCols: Number — number of text columns

numRows: Number — number of text rows

style: String — CSS Style to use for the control

visible: Boolean — Make the control visible. Defaults to true.

Example
<% textarea("name") %>

tree(initialData: XML, options: Object): Void

Render a tree control.

Description
The tree control can display static or dynamic tree data.
Parameters
initialData: XML Optional initial data for the control. The data option may be used with the refresh option to dynamically refresh the data. The tree data is an XML document.
options: Object Optional extra options. See $getOptions for a list of the standard options.

Options

data: URL — or action to get data

refresh: If — set, this defines the data refresh period. Only valid if the data option is defined

style: String — CSS Style to use for the control

visible: Boolean — Make the control visible. Defaults to true.


View(controller: Controller)

Constructor method to initialize a new View.

Parameters
controller: Controller Controller to manage this view

write(args: Array): Void

Duplicate Controller.

Description
Write.

writeHtml(args: Array): Void

Write HTML escaped text to the client.

Description
This call writes the arguments back to the client's browser after mapping all HTML control sequences into safe alternatives. The arguments are converted to strings before writing back to the client and then escaped. The text, written using write, will be buffered up to a configurable maximum. This allows text to be written prior to setting HTTP headers with setHeader.
Parameters
args: Array Text or objects to write to the client

writeRaw(args: Array): Void

Duplicate Controller.

Description
WriteRaw.