Form

$.fn.jsform_submit_button()

Make a form submit button an ajax submit button. This makes sure that when clicking submit, all fields are saved via ajax.

$('#form input[type=submit]').jsform_submit_button()
class Form(id[, options])
Extends:

TemplateHandler()
Arguments:
  • id (string) – The id of the DOM node where the form should be rendered.
  • options (Object) – An object containing options for the form.
  • options.save_url (string) – The url where data changes are propagated to. Should return a dict with either {"status": "success"} or {"status": "error", "msg": "Not an eMail address."}.
  • options.action (string) – The url the form will submit to (if intended). Will become the action attribute in form.
  • options.language (string) – 2-char language code. Default is en.
  • options.disabled (boolean) – Only render disabled fields in the whole form if true.
Returns:

The form instance.
Return type:

Object

 
$(body).append('<div id="form"></div>');
var form = new gocept.jsform.Form('form');
alert(msg)

Show a message to the user. (Alert box)

Arguments:
  • msg (string) – The message to display.
Return type:

void
clear_field_error(name)

Clear announcement of an field error during save.

Arguments:
  • name (string) – The name of the field.
clear_saving(name, msg_node)

Clear announcement of save progress for a given field.

Arguments:
  • name (string) – The name of the field.
  • msg_node (string) – The node where a saving progess message is displayed.
clear_server_error()

Clear any announcement of an HTTP fault during an ajax call.

clear_status_message(msg_node)

Clear given status message.

Arguments:
  • msg_node (Object) – DOM Node as returned by status.message.
collect_sources()

Collect sources from options and make them ovservable.

Return type:void
create_form()

Wires the form DOM node and object.

Return type:void
create_model()

Create a knockout model from self.data.

Note

Needed for bindings and oberservation.

expand_form()

Expands the form_template into the DOM.

Return type:void
field(name)

Get the DOM node for a field.

Arguments:
  • name (string) – The name of the field.
Returns:

The DOM node of the field as a jQuery object.
Return type:

Object
finish_load(tokenized)

After load handler. Save data retrieved from server on model.

Arguments:
  • tokenized (Object) – The data returned from the ajax server request.
get_widget(name)

Retrieve the widget for a field.

Arguments:
  • name (string) – The name of the field.
highlight_field(name, status)

Highlight field with status.

Arguments:
  • name (string) – The name of the field.
  • status (string) – The status to display. Should be one of ‘success’, ‘info’, ‘warning’ or ‘danger’.
init_fields()

Initialize fields from self.data.

Note

Guess the type of data for each field and render the correct field template into the DOM. Invoke the knockout databinding via auto-mapping data into a model (thanks to ko.mapping plugin) and invoke observing the model for changes to propagate these to the server. Appends fields into the form if no DOM element with id name like field is found.

is_object_field(name)

Check whether field is an object field.

Note

Object fields are either select boxes or radio lists.

Arguments:
  • name (string) – The name of the field to check.
Return type:

boolean
label(name)

Return the label for a field.

Arguments:
  • name (string) – The name of the field.
Returns:

The label of the field.
Return type:

string
load(data_or_url[, options[, mapping]])

Invokes data retrieval and form field initialization.

Arguments:
  • data_or_url (string) – The url to a JSON View returning the data for the form or the data itself.
  • options (Options) – Options for each data field.
  • options.<field_name> (string) – Options for the field.
  • options.<field_name>.label (string) – The label of the field.
  • options.<field_name>.template (string) – The id of a custom template for this field.
  • options.<field_name>.required (boolean) – Whether this is a required field or not.
  • options.<field_name>.source (Array) – The source for a select field. Contains objects with ‘token’ and ‘title’.
  • options.<field_name>.multiple (boolean) – For object selection, whether to do multi-select.
  • options.<field_name>.placeholder (string) – Placeholder to the empty dropdown option.
  • options.<field_name>.disabled (boolean) – true if field should be disabled.
  • mapping (Object) – An optional mapping for the <ko.mapping> plugin.
Return type:

void

 
form.load({'firstname': 'Robert', 'is_baby': true});
form.load('/data.json', {is_baby: {label: 'Is it a baby?'}});
notify_field_error(name, msg)

Announce error during save of field.

Arguments:
  • name (string) – The name of the field.
  • msg (string) – The message to announce.
notify_saving(name)

Announce that save of a field is in progress.

Arguments:
  • name (string) – The name of the field.
notify_server_error()

Announce HTTP faults during ajax calls.

observe_model_changes()

Observe changes on all fields on model.

reload()

Invokes data retrieval from server and reloads the form.

render_widget(id)

Render one form widget (e.g. an input field).

Arguments:
  • id (string) – The name of the field.
resolve_object_field(name, value)

Save tokens from value in object fields.

Arguments:
  • name (string) – The name of the field.
  • value (Array|string) – Tokens from object field if multiple of one token.
Returns:

Returns either an array of source objects if field is multiple or exactly one source object.
Return type:

Array|Object
retry()

Retry saving the form.

save(name, newValue[, silent])

Schedule saving one field’s value to the server via ajax.

Arguments:
  • name (string) – The name of the field.
  • newValue (string) – The new value of the field.
  • silent (boolean) – Do not notify the user about saving field.
save_and_validate(name, newValue)

Validation of the field and newValue

Arguments:
  • name (string) – The name of the field.
  • newValue (string) – The new value of the field.
Returns:

A jQuery promise.
Return type:

Object
save_remaining()

Save all fields that were not saved before.

Note

Fields are saved silently.

start_load()

Invokes data retrieval if needed.

Note

After retrieval (which may be asynchronous), self.data is initialized.

start_save(name, newValue[, silent])

Actual work of preparing and making the ajax call.

Note

May be deferred in order to serialise saving subsequent values of each field.

Arguments:
  • name (string) – The name of the field.
  • newValue (string) – The new value of the field.
  • silent (boolean) – Do not notify the user about saving field.
Returns:

A jQuery promise.
Return type:

Object
status_message(message, status, duration)

Create a status message for the given duration.

Arguments:
  • message (string) – The message to display.
  • status (string) – The status to display. Should be one of ‘success’, ‘info’, ‘warning’ or ‘danger’.
  • duration (number) – How long should the message be displayed (in milliseconds)
Returns:

The created message as jQuery DOM node.
Return type:

Object
subscribe(name)

Subscribe to changes on one field of the model and propagate them to the server.

Arguments:
  • name (string) – The name of the field.
t(msgid)

Translate a message into the language selected upon form initialization.

Arguments:
  • msgid (string) – The message id from the localization dict.
Returns:

The translated message.
Return type:

string
tokenize_object_fields(name, value)

Get tokens from value in object fields.

Arguments:
  • name (string) – The name of the field.
  • value (Array|string) – The selected values if field is multiple else the selected value.
Returns:

The selected tokens if field is multiple else the selected token.
Return type:

Array|string
update_bindings()

Add or update knockout bindings to the data.

Note

This is where all the magic starts. Adding bindings to our model and observing model changes allows us to trigger automatic updates to the server when form fields are submitted.

update_sources(data)

Update sources from data. Called on form reload.

Arguments:
  • data (Object) – The data returned from the ajax server request.
when_saved(retry)

Handle save retries if connection to server is flaky or broken.

Arguments:
  • retry (boolean) – Chain retries? (default: true)
Returns:

A jQuery promise.
Return type:

Object