Forms are a common way to ask for input from users. Instances of Form() are used in the preference panels as well as several other plugins throughout Cloud9 and they are commonly combined with dialogs. The form object renders rows of label, widget combinations and optionally custom widgets.

Creating a new Form

The example below creates a new form that has 10px spacing on each side. It has no form property which would contain an array of widgets. These can be added later via the add() method.

var form = new Form({
    html: document.body,
    edge: "10 10 10 10",
    className: "my-form",
    style: "background: #EEE",
    colwidth: 300
});

The html sets the parent element of the form. You can also create a form while not setting this property and instead attach the form via the attachTo() method.

form.attachTo(document.body);

Form Properties

The following properties can be passed to the Form() constructor.

edgeSpace separated integers that specify the top, right, bottom and left edge size in pixels (i.e. "5 10 10 5").
rowheightThe height in pixels of each row.
colwidthThe width of the left column containing the label.
widthsA simple object containing the widget name as a key and the width of the widget as a value. Use this to set default widths.
skinsA simple object containing the widget name as a key and the skin name for that widget as a value. Use this to set default skins.
htmlA reference to the html element to attach the form to.
formArray of widget definitions.
classNameThe classname added to the form container.
styleStyle attribute added to the form container.

Widgets

The form elements, also known as widgets can be added to the form using a declarative description in JSON. Each widget has some custom fields and all widgets support the common fields that are listed in the table below.

title The text of the label in the first column
name This value is used when creating a json object using {@link #toJson}
width A different width for the element in the 2nd column
rowheight A different height for this row
edge The edges on the top, right, bottom, left side of the form element in pixels, space separated (e.g. "5 5 10 5").
position Integer specifying the position in the form.
type The type of form element to create. See below for a complete list

Most of these fields are optional, except title and type. The next example shows how to add a dropdown widget to a form.

form.add([{
    title: "What is your favorite color?",
    type: "dropdown",
    items: [
        { caption: "Red", value: "red" },
        { caption: "Green", value: "green" },
        { caption: "Blue", value: "blue" },
        { caption: "Orange", value: "orange" }
    ]
}]);

These are the supported widgets, each is described in detail below.

  • checkbox - A simple two-state checkbox
  • dropdown - A dropdown containing items that a user can select
  • spinner - A widget that lets a users select integers
  • checked-spinner - A combination of a checkbox and a spinner
  • textbox - A simple textbox
  • password - A textbox that doesn't show the content while the user types into it
  • colorbox - A widget that allows a user to select a color
  • button - A simple button
  • submit - A button without a label
  • label - A label that spans both columns
  • image - An image that spans both columns
  • divider - A divider that spans both columns
  • textarea - A multi line input widget
  • custom - A custom APF element. This can be anything

The screenshots below are taken from preferences. With other skins or in other contexts the widgets might look differently

checkbox

The checkbox widget creates a simple two-state checkbox.

{
    title: "Enable this feature"
    type: "checkbox"
}

Additional Properties

defaultValue The default value of the checkbox. This is the value that is set initially and after calling reset()
values Array defining values corresponding to the checked and unchecked state. (i.e. ["on", "off"])
1570

dropdown

The dropdown widget creates a dropdown containing items that a user can select.

{
    title: "What is your favorite color?",
    type: "dropdown",
    items: [
        { caption: "Red", value: "red" },
        { caption: "Green", value: "green" },
        { caption: "Blue", value: "blue" },
        { caption: "Orange", value: "orange" }
    ]
}

Additional Properties

items Array of objects with a value and caption property.
defaultValue The value of the default selected item
empty-message The message displayed when no items have been selected
1570

spinner

The spinner widget creates a widget that lets users select integers

{
    title: "How old are you?",
    type: "spinner",
    min: "1",
    max: "150"
}

Additional Properties

defaultValue The default value of the spinner. This is the value that is set initially and after calling {@link #reset}
min The smallest value that a number can have in the spinner
max The largest value that a number can have in the spinner
realtime Whether the values are updated while typing, or only when the form element has lost focus
1570

checked-spinner

The checked-spinner widget creates a row that combines a checkbox and a spinner

{
    title: "Print Margin",
    type: "checked-spinner",
    min: "1",
    max: "64"
}

Additional Properties

Property Possible Value
defaultCheckboxValue The default value of the checkbox. This is the value that is set initially and after calling {@link #reset}
defaultValue The default value of the spinner. This is the value that is set initially and after calling {@link #reset}
min The smallest value that a number can have in the spinner
max The largest value that a number can have in the spinner
realtime Whether the values are updated while typing, or only when the form element has lost focus
1570

textbox

The textbox widget creates a simple textbox.

{
    title: "What is your name?",
    type: "textbox"
}

Additional Properties

message The message displayed while the textbox has no value
defaultValue The default value of the textbox. This is the value that is set initially and after calling reset()
realtime Whether the values are updated while typing, or only when the form element has lost focus
1570

password widget

The password widget creates a textbox that doesn't show the content while the user types into it.

{
    title: "Password",
    type: "password"
}

Additional Properties

defaultValue The default value of the password element. This is the value that is set initially and after calling {@link #reset}
realtime Whether the values are updated while typing, or only when the form element has lost focus

textarea

The textarea widget creates a multi line input widget.

{
    title: "Ignore these files",
    type: "textarea",
    width: 150,
    height: 130,
    rowheight: 155
}
1570

Additional Properties

height The height of the textarea in pixels.
defaultValue The default value of the password element. This is the value that is set initially and after calling {@link #reset}
realtime Whether the values are updated while typing, or only when the form element has lost focus

colorbox

The colorbox widget allows a user to select a color.

{
    title: "What is your favorite color?",
    type: "colorbox"
}

Additional Properties

defaultValue The default value of the colorbox. This is the value that is set initially and after calling {@link #reset}
realtime Whether the values are updated while typing, or only when the form element has lost focus
1570

button

The button widget creates a simple button with a caption.

{
    type: "button",
    title: "Reset to Default Keybindings",
    caption: "Reset to Defaults",
    width: 140,
    onclick: function(){
        alert('hello!')
    }
}

Additional Properties

caption The text displayed on the button
onclick The function that is executed when a user clicks on the button
1570

submit

The submit widget creates a button that is centered across the complete width of the form and can be used to submit the form.

{
    type: "submit",
    caption: "Update Preview",
    margin: "10 10 5 10",
    onclick: function(){
        alert("hello!")
    }
},

Additional Properties

margin The edges on the top, right, bottom, left side of the submit element in pixels, space separated (e.g. "5 5 10 5").
caption The text displayed on the button
submenu A reference to a menu that is shown when the button is clicked
onclick The function that is executed when a user clicks on the button
default Whether this is the action that is executed when the user presses Enter in one of the form elements

label

The label widget creates a label that is centered across the complete width of the form and can be used for instance for status messages.

{
    type: "label",
    caption: "This is an example!"
}

Additional Properties

caption The text displayed on the button
style A css string that is applied to the label

image

The image widget creates an image that is centered across the complete width of the form and can be used for instance for displaying a banner.

{
    type: "image",
    src: "banner.png"
}

Additional Properties

src The URL to load the image from
margin The edges on the top, right, bottom, left side of the submit element in pixels, space separated (e.g. "5 5 10 5").
height The height of the image in pixels

divider

The divider widget creates a line that separates the content before from the content after the divider widget.

{
    type: "divider"
}

Updating Widgets

After creating the form you can call form.reset() to reset all the values to their defaults. You can also programmatically set and change the value of widgets like this.

form.update([
    { id: "widgetName", value: "newValue" }
]);

Make sure to set the name property of a widget in order for this to work.

Getting a reference to the Cloud9 ui element

An alternative to the above method is to fetch a reference to the widget directly.

var el = form.getElement("widgetName");

Again, the name property of a widget needs to be set. The widgets are any of the Cloud9 ui widgets.

To JSON

When you simple want to get a set of key/value pairs in a JSON blob call form.toJson(). The name property should be set and will function as the key.

var json = form.toJson();