• If you are citizen of an European Union member nation, you may not use this service unless you are at least 16 years old.

  • You already know Dokkio is an AI-powered assistant to organize & manage your digital files & messages. Very soon, Dokkio will support Outlook as well as One Drive. Check it out today!


Quilmes-FormView Notes

Page history last edited by Alex Iskander 14 years, 7 months ago

The FormView should take a configuration and automatically generate forms to edit various properties on the form view.  It uses a set of configuration methods, just like SC.Record.attr() so you can setup the form view.  Here is an example of how the API would work :


from a main_page.js:


myForm:  SC.FormView.design({

  layout: { top: 0, left: 0, right: 0, bottom: 40 },

  fields: 'name gender'.w(),  // Fields. RowView is really just a sub

                              // form as it works identically in most ways.

  contentBinding: "MyApp.fooController",


  // if row gets a class as a first argument, it conveniently sets it up

  // like the following, but with only one field.

  name: SC.FormView.row({

    fields: "firstName lastName".w(),

    fieldLabel: "Name:",

    firstName: SC.FormView.field(SC.TextFieldView, { fieldKey: "first_name" }),

    lastName: SC.FormView.field(SC.TextFieldView, { fieldKey: "last_name"})



  // with that optional first argument:

  gender: SC.FormView.row(SC.RadioView, {

    layout: { width: 100 },

    items:  'male female'.w(),

    fieldKey: 'contactGender',

    fieldLabel: "Gender:",





This would create a form with three fields: firstName, lastName, and gender.  By default these will generate fields preceded by a label using the key name (i.e. firstName, lastName) as the key on the content object and a humanized form of the key name (i.e. First Name:, Last Name:) as the label.  


You can override these defaults using the 'fieldKey' and 'fieldTitle' properties in the second hash.  Any other properties named in the hash will be applied to the generated view.


The 'fields' property—by the way—is not required.  It just allows you to control the order in which the fields will be displayed.  Otherwise it will display the fields in the order they are defined here.


Fields would usually be created using the "row" function. The API for a row is identical to the API for a form, except that rows have an additional property: fieldLabel. In fact, rows are actually subclasses of FormView (groups and other form features may also be implemented as form subclasses).


Note: the following discusses many settings, but it should be noted that the defaults should make a very nice form to begin with; tweaks should not be necessary except for customization to a theme.


Special Form Controls/Fields?

A few extra features may be wanted from controls or fields in a form. These can be implemented in a set of Form controls or fields, which are, of course, not rewrites of the existing controls, but encapsulate them.

  • Edit Begin/End

    Many forms have an editable and non editable state. The non-editable state might show only the fields that hold information, or may show textual values instead of the normal UI controls. The FormView needs to be able to call beginEdit and endEdit and have fields automatically hide or show themselves and switch from being controls to labels or whatever as necessary.

  • autoResize

    If you look in Address Book.app on Mac, the first and last name fields change width as you type. This would be a nice feature to have in the Form's specialized text field view. It may also be a nice feature to have in other views (checkboxes, etc.). However, it would impact performance more significantly than other features, so should be opt-in.

  • liveUpdate

    Would be interesting (though perhaps a very bad idea) if the text fields could update the values they were bound to, live (but without necessarily committing the underlying data to the server—just intra-app).



Animation should be possible through a FormView animation mixin. This mixin will automatically propagate itself through all child forms it knows how to connect to.


Example usage:

myFormView: SC.FormView.design(SC.AnimatableForm, { /* My form stuff */ })


This allows automatic animation of anything animatable, without inserting any animation logic directly into FormView itself.


Row & Field Positioning

Parts of this stink a bit, but is there a workaround? The FormView and FormRowViews handle the positioning of the rows, labels, and fields; but how do they do this positioning? Unfortunately, they have to take parameters to make it somewhat flexible, and they remind one a bit too much of HTML tables. It would be really nice to have a better idea on how to do this:

  • rowSpacing: The real stinky one: the space added below each row to keep them away from each other some minimum amount. If not provided on a per-row basis, it will be taken from the row's parent form (and, while this is not really intended final behavior, for the moment it will cascade to any child forms, etc.)
  • rowPadding: the space to add around all contents of the row. This is so things like TextFieldView's outline on Mac will not be clipped. Perhaps this can be gotten rid of when FormView has its own controls? This could then just be made part of FormView's special controls and no longer stink so badly. Currently, if not provided on a per-row basis, it will be taken from the row's parent form view.
  • labelVerticalAlign:
    • 'smart-center': the default. The label will be centered (with centerY = 0—unlike 'center' mode) if the row it is in is less than twice its height. Otherwise, it will be top aligned with top=labelVerticalOffset.
    • 'center': Sets centerY to labelVerticalOffset.
    • 'top': Sets top to labelVerticalOffset.
  • labelVerticalOffset: the offset from either centerY (if not in "smart-center") or top to display the label.
  • rowOrientation:
    • If "left", the row's label will appear on the left, and the fields will flow from left to right, up to down.
    • If "right", the row's label will appear on the right, and the fields will flow from right to left, up to down.
  • labelSpacing: the spacing between the edge of the label and the fields in the row (which show next to the label).


Performance Concerns

Currently, the size of the label is calculated so that all labels can be sized to one size (the maximum label width). However, this involves creating and destroying a DOM node—for each calculation. Perhaps performance could be improved by:

  • Caching measurement DOM node—probably would improve performance a lot.
  • Allowing opt-out of label size calculation.


The measurement occurs every time the label's layout or contents change—somewhat (but not terribly) often; primarily focused around initial creation of the form.


Auto-Configured FormViews


FormViews could also have a isAutoconfigured: YES option.  If turned on, then instead of looking for fields defined on the view itself, the form view would look at the fields defined on the content object.  Based on the fields found, it would generate defaults fields for the UI.


In this case, any fields defined on the FormView (i.e. firstName, lastName, etc above) would be used only if the content object itself had a field with the same property name.



Comments (2)

Charles Jolley said

at 11:49 pm on Oct 28, 2009

Re: label performance. One way to solve this would be to allow the developer to manually specify their desired label width - to bypass the DOM calculation.

Another option would be to have the label views just go as wide as they want. THen you just check their display widths in didUpdateLayer and fit to size as needed.

jrogelstad said

at 9:20 am on Mar 3, 2011

Is this available for use in the general release of 1.4.5? I'm getting this error:
TypeError: Result of expression 'SC.FormView' [undefined] is not an object.

I tried adding 'sproutcore/forms' to my build file, but sc-server gives me warnings:
Could not find target sproutcore/forms that is required by...

You don't have permission to comment on this page.