Entry forms

Location

Forms are displayed by the views

  • app/views/entities/add
  • app/views/entities/list
  • app/views/entities/public_form
  • app/views/entities/edit

Displaying the form

The forms are managed by YUI3 gallery-form
A YUI3 javascript block is generated by a helper called yui3_block, in which all necessary modules are made available.
Here is a snippet of code from app/views/entities.add.rhtml

<% yui_block( :modules => [ "gallery-form", "madb" ], :use => [ 'gallery-form', 'anim', 'madb','event-custom']) do %>

A javascript array called fields is created, and all form field definitions are put in that array, which is then passed to the form when it is instanciated.

The items pushed in the fields array are generated by the detail values throught their method to_yui_form_row. A loop iterates over all of them to generate the needed javascript to have the fields array populated. The iteration is done in the entity_yui_form_fields partial.

Most detail values will generate 2 fields:

  • One hidden field to pass the id of the detail_value to update in case of an update operation
  • One visible form field

The id these fields are generated by the method app/model/detail_value.rb#form_field_id with an _id and name suffix respectively
The id these fields are generated by the method app/model/detail_value.rb#form_fieldname with a [id] and [name] suffix, respectively. With this approach, when the server is submitted, all elements of a detail value or placed in an hash, the id being available under the “id” key, and the value under de “value” key.

The id and name generated for a detail value are based on the name of the detail they are linked to, except when a non-ASCII character is present in the name, then we take the SHA1 of the name as a base.

Once all the javascript variables have been initialized, we call the helped default_entity_form
This helper takes a Hash as argument, which holds options about the form to be created:

  • :form_content_box : the id of the div in which to render the form
  • :success_callback : javascript code defining the function to call as acallback when the form has been submitted successfully
  • :upload : true if this form h is used to upload files. Usually set to the value returned by @entity.has_file_attachment_detail?

Fields of the form are no validated with the gallery-form’s validation procedure, but the validation request to the server is sent when the blur event is fired for a field (seel below).

Validation

Each data type can have its own validation. All validations happen on the server in app/controller/entities_controller.rb#check_detail_value_validity which returns 1 if the value was valid, 0 if not.

Submission

The form is submitted to app/controllers/entities_controller.rb/apply_edit
The response will tell if the submission was successful or not. Possible results:

  • Successful: if it is a public form, nothing is rendered. If it is not a publich form, a json representation of the created instance is returned
  • Invalid values: the ids of the invalid (visible) form fields are returned, separated by the sting “######”.
  • Error: The error message is returned, prefixed by ERROR

This needs to be updated so that the server returns a json string.

Events

The YUI3 event madb:entity_created should be fired when the form has been submitted successfully and a new entity instance has been created.