Form
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.
edge | Space separated integers that specify the top, right, bottom and left edge size in pixels (i.e. "5 10 10 5"). |
---|---|
rowheight | The height in pixels of each row. |
colwidth | The width of the left column containing the label. |
widths | A simple object containing the widget name as a key and the width of the widget as a value. Use this to set default widths. |
skins | A 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. |
html | A reference to the html element to attach the form to. |
form | Array of widget definitions. |
className | The classname added to the form container. |
style | Style 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"] ) |
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 |
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 |
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 |
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 |
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
}
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 |
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 |
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();
Updated less than a minute ago