Basic functions

This set of functions provides a basic operations on widgets.

(form-bind name event callback)

Binds event handler to appropriate event of some widget. Supported events are click, change, and enter.

Example: (form-bind "button" "click" ui-button)

(form-value name . default)

Returns current value of widget. If widget's value is not set, then this function returns a false boolean value or other default value if it was specified.

Please note, that unchecked checkboxes in HTML interface have no values.

Example: (form-value "foo")

(form-update-value name value)

Changes current value of widget.

Example: (form-value "foo" "some-text")

(form-update-visibility name value)

Shows or hides widget. First argument is a name of the widget or list of names, second - boolean value.

Example: (form-update-visibility "foo" #t)

(form-update-activity name value)

Enables or disables some widget. First argument is a name of the widget or list of names, second - boolean value.

Example: (form-update-activity "foo" #f)

Communication between backend and interface

Very often we have to organize a data flow between backend and form fields. These functions helps us to do it. All these functions suggest that the name of the parameter in backend is equal to the name of appropriate field.

(form-value-list . name-list)

Fetch values of the fields and return a list that ready to apply to woo-write or other ``woo'' function. You can specify names of the parameters that you want to have in list. By default, this function will process all widgets in the form.

Example:
(apply woo-write "/foo"
(form-value-list '("foo" "bar")))

In this example form-value-list returns a list like '(foo "value-of-foo" bar "value-of-bar")

(form-update-value-list name-list woo-data)

Get values from backend and fill an appropriate fields in the form. Second parameter is a one component from typical backend's answer, e.g.,
result of the woo-read-first function.

Example:
(form-update-value-list
'("foo" "bar")
(woo-read-first "/foo"))

(form-update-enum name woo-data)

This function fills listbox, combobox, checklistbox or table with data from backend. To change current value of these widgets use form-update-value or form-update-value-list functions.

Example: (form-update-enum "foo" (woo-list "/foo"))

File upload support

Sometimes we need to send a binary data to backend. Please note, that some shell implementations too slow process large strings, therefore, you should preffer to use call-with-form-file function instead of form-blob for them.

(form-bind-upload name event file-field-name callback)

Binds button (or other widget) with a special file upload widget. To get uploaded binary data use form-callback or call-with-form-file functions.

Example: (form-bind "button" "click" "file" ui-upload)

(form-blob name . default)

Returns base64 encoded string with uploaded binary data. First parameter specifies name of file upload widget.

Example: (form-blob "file")

(call-with-form-file name proc)

Creates a temporary file with uploaded data and call `(proc tempfile)' with name of this file. All temporary data will be removed at the end of work of this function.

Example:
(call-with-form-file
"file"
(lambda(tempfile)
(woo-write "/foo" 'tempfile tempfile)))

Messages

Sometimes you need to catch errors and notify user about it.

(form-error fmt . args)

Shows "Critical error" popup.

Example: (form-error "some error")

(form-warning fmt . args)

Shows "Warning" popup.

Example: (form-warning "some error")

(form-confirm msg . args)

Shows confirm dialog to user and returns result as a boolean value. In additional arguments you can define: a custom title text (default value is "Question"), text on "ok" button (default value is "OK"), text on "cancel" button (default value is "Cancel").

Example:
(form-confirm
"Are you really want do delete user?"
"Yes"
"No")

(catch/message proc)

Catch woo-error or type-error exception and call form-error with appropriate message to notify users about it.

Example:
(catch/message
(lambda()
(woo-write "/foo")))

Localization

You can made localized messages and text labels using _ function.

(_ string . domain)

Returns translated string. Default dictionary name is calculated from document's url, e.g., for url /foo/bar dictionary name is alterator-foo. You can also explicitly specify dictionary instead of default.

Example: (_ "string" "alterator-foo")

Form session data

Every time you are starting to work with interface engine you explicitly (via login page) or implicitly open a session to communicate with it. Each form can store it's data to per-session storage.

It looks like html cookies, but this data storage lives at server side in RAM, therefore, you can save any scheme object in it. Because this storage lives in memory you should avoid to use functions from this section for large and complicated data objects.

If you really want to manipulate cookies in html interface you can use form-cookie and form-update-cookie functions.

(form-session-ref name)

get form's data from session's storage.

Example: (form-session-ref "data")

(form-session-set! name value)

put form's data to session's storage.

Example: (form-session-set! "data" "value")