{"_id":"54e23b349d045721004cbc26","parentDoc":null,"project":"54d53c7b23010a0d001aca0c","version":{"_id":"54d5635532d98b0d00384afb","project":"54d53c7b23010a0d001aca0c","__v":10,"forked_from":"54d53c7c23010a0d001aca0f","createdAt":"2015-02-07T00:59:01.934Z","releaseDate":"2015-02-07T00:59:01.934Z","categories":["54d5635632d98b0d00384afc","54d5635632d98b0d00384afd","54d5635632d98b0d00384afe","54d5635632d98b0d00384aff","54d5635632d98b0d00384b00","54d5635632d98b0d00384b01","54d5635632d98b0d00384b02","54d652097e05890d006f153e","54dd1315ca1e5219007e9daa","54e21e2b22de1c230094b147","54e68e62a43fe13500db3879","54fa1d3fe7a0ba2f00306309","551c453a23a1ee190034d19a","551df586e52a0b23000c62b6","551f39be6886f8230055f02a","55a6720751457325000e4d97"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.1.0","version":"0.1"},"__v":66,"category":{"_id":"54dd1315ca1e5219007e9daa","pages":["54dd1324ca1e5219007e9dac","54e26fe6dd4c990d00479bef","5516e2d97f5d0919007d0701"],"version":"54d5635532d98b0d00384afb","project":"54d53c7b23010a0d001aca0c","__v":3,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-12T20:54:45.914Z","from_sync":false,"order":8,"slug":"user-interface","title":"User Interface"},"user":"54cfa8e1a8a4fd0d00b7fd1d","updates":["57599be65577ba2b00cc42ec"],"next":{"pages":[],"description":""},"createdAt":"2015-02-16T18:47:16.527Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Forms are a common way to ask for input from users. Instances of `Form()` are used in the [preference panels](doc:preference-panel) as well as several other plugins throughout Cloud9 and they are commonly combined with [dialogs](doc:dialog). The form object renders rows of label, widget combinations and optionally custom widgets.\n\n# Creating a new Form\n\nThe 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.\n\n```\nvar form = new Form({\n    html: document.body,\n    edge: \"10 10 10 10\",\n    className: \"my-form\",\n    style: \"background: #EEE\",\n    colwidth: 300\n});\n```\n\nThe `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.\n\n```\nform.attachTo(document.body);\n```\n\n# Form Properties\n\nThe following properties can be passed to the `Form()` constructor.\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>edge</th><td>Space separated integers that specify the top, right, bottom and left edge size in pixels (i.e. \\\"5 10 10 5\\\").</td></tr>\\n<tr><th>rowheight</th><td>The height in pixels of each row.</td></tr>\\n<tr><th>colwidth</th><td>The width of the left column containing the label.</td></tr>\\n<tr><th>widths</th><td>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.</td></tr>\\n<tr><th>skins</th><td>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.</td></tr>\\n<tr><th>html</th><td>A reference to the html element to attach the form to.</td></tr>\\n<tr><th>form</th><td>Array of widget definitions.</td></tr>\\n<tr><th>className</th><td>The classname added to the form container.</td></tr>\\n<tr><th>style</th><td>Style attribute added to the form container.</td></tr>\\n</table>\"\n}\n[/block]\n# Widgets\n\nThe 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.\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>title</th><td>             The text of the label in the first column</td></tr>\\n<tr><th>name</th><td>              This value is used when creating a json object using {:::at:::link #toJson}</td></tr>\\n<tr><th>width</th><td>             A different width for the element in the 2nd column</td></tr>\\n<tr><th>rowheight</th><td>         A different height for this row</td></tr>\\n<tr><th>edge</th><td>              The edges on the top, right, bottom, left side of the form element in pixels, space separated (e.g. \\\"5 5 10 5\\\").</td></tr>\\n<tr><th>position</th><td>          Integer specifying the position in the form.</td></tr>\\n<tr><th valign=\\\"top\\\">type</th><td> The type of form element to create. See below for a complete list</td></tr>\\n</table>\"\n}\n[/block]\nMost of these fields are optional, except `title` and `type`. The next example shows how to add a dropdown widget to a form.\n\n```\nform.add([{\n    title: \"What is your favorite color?\",\n    type: \"dropdown\",\n    items: [\n        { caption: \"Red\", value: \"red\" },\n        { caption: \"Green\", value: \"green\" },\n        { caption: \"Blue\", value: \"blue\" },\n        { caption: \"Orange\", value: \"orange\" }\n    ]\n}]);\n```\n\nThese are the supported widgets, each is described in detail below.\n\n* [checkbox](#section-checkbox) - A simple two-state checkbox\n* [dropdown](#section-dropdown) - A dropdown containing items that a user can select\n* [spinner](#section-spinner) - A widget that lets a users select integers\n* [checked-spinner](#section-checked-spinner) - A combination of a checkbox and a spinner\n* [textbox](#section-textbox) - A simple textbox\n* [password](#section-password-widget) - A textbox that doesn't show the content while the user types into it\n* [colorbox](#section-colorbox) - A widget that allows a user to select a color\n* [button](#section-button) - A simple button\n* [submit](#section-submit) - A button without a label\n* [label](#section-label) - A label that spans both columns\n* [image](#section-image) - An image that spans both columns\n* [divider](#section-divider) - A divider that spans both columns\n* [textarea](#section-textarea) - A multi line input widget\n* [custom](#section-custom) - A custom APF element. This can be anything\n\n*The screenshots below are taken from preferences. With other skins or in other contexts the widgets might look differently*\n\n## checkbox\n\nThe `checkbox` widget creates a simple two-state checkbox.\n\n```\n{\n    title: \"Enable this feature\"\n    type: \"checkbox\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>defaultValue</th><td>    The default value of the checkbox. This is the value that is set initially and after calling <code>reset()</code></td></tr>\\n<tr><th>values</th><td>          Array defining values  corresponding to the checked and unchecked state. (i.e. <code>[\\\"on\\\", \\\"off\\\"]</code>)</td></tr>\\n</table>\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/AOacP29BRxydqkHu6IKW_2015-03-26_1648.png\",\n        \"2015-03-26_1648.png\",\n        \"1570\",\n        \"182\",\n        \"#81ab68\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## dropdown\n\nThe `dropdown` widget creates a dropdown containing items that a user can select.\n\n```\n{\n    title: \"What is your favorite color?\",\n    type: \"dropdown\",\n    items: [\n        { caption: \"Red\", value: \"red\" },\n        { caption: \"Green\", value: \"green\" },\n        { caption: \"Blue\", value: \"blue\" },\n        { caption: \"Orange\", value: \"orange\" }\n    ]\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>items</th><td>           Array of objects with a value and caption property.</td></tr>\\n<tr><th>defaultValue</th><td>    The value of the default selected item</td></tr>\\n<tr><th>empty-message</td><td>   The message displayed when no items have been selected</td></tr>\\n</table>\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/cznvV0TSSPiPsVML6DZs_dropdown.png\",\n        \"dropdown.png\",\n        \"1570\",\n        \"222\",\n        \"#66adfc\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## spinner\n\nThe `spinner` widget creates a widget that lets users select integers\n\n```\n{\n    title: \"How old are you?\",\n    type: \"spinner\",\n    min: \"1\",\n    max: \"150\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>defaultValue</th><td>    The default value of the spinner. This is the value that is set initially and after calling {@link #reset}</td></tr>\\n<tr><th>min</th><td>             The smallest value that a number can have in the spinner</td></tr>\\n<tr><th>max</th><td>             The largest value that a number can have in the spinner</td></tr>\\n<tr><th>realtime</th><td>        Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\\n</table>\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/6gnttWeJRRG73yYpYC6R_spinner.png\",\n        \"spinner.png\",\n        \"1570\",\n        \"90\",\n        \"#ec7474\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n## checked-spinner\n\nThe `checked-spinner` widget creates a row that combines a checkbox and a spinner\n\n```\n{\n    title: \"Print Margin\",\n    type: \"checked-spinner\",\n    min: \"1\",\n    max: \"64\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>Property</th><td>                Possible Value</td></tr>\\n<tr><th>defaultCheckboxValue</th><td>    The default value of the checkbox. This is the value that is set initially and after calling {@link #reset}</td></tr>\\n<tr><th>defaultValue</th><td>            The default value of the spinner. This is the value that is set initially and after calling {@link #reset}</td></tr>\\n<tr><th>min</th><td>                     The smallest value that a number can have in the spinner</td></tr>\\n<tr><th>max</th><td>                     The largest value that a number can have in the spinner</td></tr>\\n<tr><th>realtime</th><td>                Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\\n</table>\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/z5NqrRlpTNKW0SYfy1LC_checked-spinner.png\",\n        \"checked-spinner.png\",\n        \"1570\",\n        \"96\",\n        \"#c77a7a\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n## textbox\n\nThe `textbox` widget creates a simple textbox.\n\n```\n{\n    title: \"What is your name?\",\n    type: \"textbox\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>message</th><td>        The message displayed while the textbox has no value</td></tr>\\n<tr><th>defaultValue</th><td>   The default value of the textbox. This is the value that is set initially and after calling <code>reset()</code></td></tr>\\n<tr><th>realtime</th><td>       Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\\n</table>\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/vriNVfOwTDmbTYkRDER7_textbox.png\",\n        \"textbox.png\",\n        \"1570\",\n        \"100\",\n        \"#b7b7b7\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## password widget\n\nThe `password` widget creates a textbox that doesn't show the content while the user types into it.\n\n```\n{\n    title: \"Password\",\n    type: \"password\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>defaultValue</th><td>    The default value of the password element. This is the value that is set initially and after calling {@link #reset}</td></tr>\\n<tr><th>realtime</th><td>        Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\\n</table>\"\n}\n[/block]\n\n## textarea\n\nThe `textarea` widget creates a multi line input widget.\n\n```\n{\n    title: \"Ignore these files\",\n    type: \"textarea\",\n    width: 150,\n    height: 130,\n    rowheight: 155\n}\n```\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/lH7Z8mzjRJa2U6WA7V2u_textarea.png\",\n        \"textarea.png\",\n        \"1570\",\n        \"294\",\n        \"#acacac\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>height</th><td>          The height of the textarea in pixels.</td></tr>\\n<tr><th>defaultValue</th><td>    The default value of the password element. This is the value that is set initially and after calling {@link #reset}</td></tr>\\n<tr><th>realtime</th><td>        Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\\n</table>\"\n}\n[/block]\n\n## colorbox\n\nThe `colorbox` widget allows a user to select a color.\n\n```\n{\n    title: \"What is your favorite color?\",\n    type: \"colorbox\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>defaultValue</th><td>    The default value of the colorbox. This is the value that is set initially and after calling {@link #reset}</td></tr>\\n<tr><th>realtime</th><td>        Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\\n</table>\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/NaTQYgrTtqm00IfH0Yhz_colorbox.png\",\n        \"colorbox.png\",\n        \"1570\",\n        \"96\",\n        \"#474747\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n## button\n\nThe `button` widget creates a simple button with a caption.\n\n```\n{\n    type: \"button\",\n    title: \"Reset to Default Keybindings\",\n    caption: \"Reset to Defaults\",\n    width: 140,\n    onclick: function(){\n        alert('hello!')\n    }\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>caption</th><td>         The text displayed on the button</td></tr>\\n<tr><th>onclick</th><td>         The function that is executed when a user clicks on the button</td></tr>\\n</table>\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/7GFJ1DKVQ96fVYV6EZjh_button.png\",\n        \"button.png\",\n        \"1570\",\n        \"104\",\n        \"#acacac\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## submit\n\nThe `submit` widget creates a button that is centered across the complete width of the form and can be used to submit the form.\n\n```\n{\n    type: \"submit\",\n    caption: \"Update Preview\",\n    margin: \"10 10 5 10\",\n    onclick: function(){\n        alert(\"hello!\")\n    }\n},\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>margin</th><td>          The edges on the top, right, bottom, left side of the submit element in pixels, space separated (e.g. \\\"5 5 10 5\\\").</td></tr>\\n<tr><th>caption</th><td>         The text displayed on the button</td></tr>\\n<tr><th>submenu</th><td>         A reference to a menu that is shown when the button is clicked</td></tr>\\n<tr><th>onclick</th><td>         The function that is executed when a user clicks on the button</td></tr>\\n<tr><th>default</th><td>         Whether this is the action that is executed when the user presses Enter in one of the form elements</td></tr>\\n</table>\"\n}\n[/block]\n## label\n\nThe `label` widget creates a label that is centered across the complete width of the form and can be used for instance for status messages.\n\n```\n{\n    type: \"label\",\n    caption: \"This is an example!\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>caption</th><td>         The text displayed on the button</td></tr>\\n<tr><th>style</th><td>           A css string that is applied to the label</td></tr>\\n</table>\"\n}\n[/block]\n\n## image\n\nThe `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.\n\n```\n{\n    type: \"image\",\n    src: \"banner.png\"\n}\n```\n\n### Additional Properties\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>src</th><td>             The URL to load the image from</td></tr>\\n<tr><th>margin</th><td>          The edges on the top, right, bottom, left side of the submit element in pixels, space separated (e.g. \\\"5 5 10 5\\\").</td></tr>\\n<tr><th>height</th><td>          The height of the image in pixels</td></tr>\\n</table>\"\n}\n[/block]\n\n## divider\n\nThe `divider` widget creates a line that separates the content before from the content after the divider widget.\n\n```\n{\n    type: \"divider\"\n}\n```\n\n## Updating Widgets\n\nAfter 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.\n\n```\nform.update([\n    { id: \"widgetName\", value: \"newValue\" }\n]);\n```\n\nMake sure to set the `name` property of a widget in order for this to work.\n\n## Getting a reference to the Cloud9 ui element\n\nAn alternative to the above method is to fetch a reference to the widget directly.\n\n```\nvar el = form.getElement(\"widgetName\");\n```\n\nAgain, the `name` property of a widget needs to be set. The widgets are any of the [Cloud9 ui widgets](https://docs.c9.io/api/#!/api/ui).\n\n# To JSON\n\nWhen 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.\n\n```\nvar json = form.toJson();\n```","excerpt":"","slug":"form","type":"basic","title":"Form"}
Forms are a common way to ask for input from users. Instances of `Form()` are used in the [preference panels](doc:preference-panel) as well as several other plugins throughout Cloud9 and they are commonly combined with [dialogs](doc:dialog). 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. [block:html] { "html": "<table>\n<tr><th>edge</th><td>Space separated integers that specify the top, right, bottom and left edge size in pixels (i.e. \"5 10 10 5\").</td></tr>\n<tr><th>rowheight</th><td>The height in pixels of each row.</td></tr>\n<tr><th>colwidth</th><td>The width of the left column containing the label.</td></tr>\n<tr><th>widths</th><td>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.</td></tr>\n<tr><th>skins</th><td>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.</td></tr>\n<tr><th>html</th><td>A reference to the html element to attach the form to.</td></tr>\n<tr><th>form</th><td>Array of widget definitions.</td></tr>\n<tr><th>className</th><td>The classname added to the form container.</td></tr>\n<tr><th>style</th><td>Style attribute added to the form container.</td></tr>\n</table>" } [/block] # 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. [block:html] { "html": "<table>\n<tr><th>title</th><td> The text of the label in the first column</td></tr>\n<tr><th>name</th><td> This value is used when creating a json object using {@link #toJson}</td></tr>\n<tr><th>width</th><td> A different width for the element in the 2nd column</td></tr>\n<tr><th>rowheight</th><td> A different height for this row</td></tr>\n<tr><th>edge</th><td> The edges on the top, right, bottom, left side of the form element in pixels, space separated (e.g. \"5 5 10 5\").</td></tr>\n<tr><th>position</th><td> Integer specifying the position in the form.</td></tr>\n<tr><th valign=\"top\">type</th><td> The type of form element to create. See below for a complete list</td></tr>\n</table>" } [/block] 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](#section-checkbox) - A simple two-state checkbox * [dropdown](#section-dropdown) - A dropdown containing items that a user can select * [spinner](#section-spinner) - A widget that lets a users select integers * [checked-spinner](#section-checked-spinner) - A combination of a checkbox and a spinner * [textbox](#section-textbox) - A simple textbox * [password](#section-password-widget) - A textbox that doesn't show the content while the user types into it * [colorbox](#section-colorbox) - A widget that allows a user to select a color * [button](#section-button) - A simple button * [submit](#section-submit) - A button without a label * [label](#section-label) - A label that spans both columns * [image](#section-image) - An image that spans both columns * [divider](#section-divider) - A divider that spans both columns * [textarea](#section-textarea) - A multi line input widget * [custom](#section-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 [block:html] { "html": "<table>\n<tr><th>defaultValue</th><td> The default value of the checkbox. This is the value that is set initially and after calling <code>reset()</code></td></tr>\n<tr><th>values</th><td> Array defining values corresponding to the checked and unchecked state. (i.e. <code>[\"on\", \"off\"]</code>)</td></tr>\n</table>" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/AOacP29BRxydqkHu6IKW_2015-03-26_1648.png", "2015-03-26_1648.png", "1570", "182", "#81ab68", "" ] } ] } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>items</th><td> Array of objects with a value and caption property.</td></tr>\n<tr><th>defaultValue</th><td> The value of the default selected item</td></tr>\n<tr><th>empty-message</td><td> The message displayed when no items have been selected</td></tr>\n</table>" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/cznvV0TSSPiPsVML6DZs_dropdown.png", "dropdown.png", "1570", "222", "#66adfc", "" ] } ] } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>defaultValue</th><td> The default value of the spinner. This is the value that is set initially and after calling {@link #reset}</td></tr>\n<tr><th>min</th><td> The smallest value that a number can have in the spinner</td></tr>\n<tr><th>max</th><td> The largest value that a number can have in the spinner</td></tr>\n<tr><th>realtime</th><td> Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\n</table>" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/6gnttWeJRRG73yYpYC6R_spinner.png", "spinner.png", "1570", "90", "#ec7474", "" ] } ] } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>Property</th><td> Possible Value</td></tr>\n<tr><th>defaultCheckboxValue</th><td> The default value of the checkbox. This is the value that is set initially and after calling {@link #reset}</td></tr>\n<tr><th>defaultValue</th><td> The default value of the spinner. This is the value that is set initially and after calling {@link #reset}</td></tr>\n<tr><th>min</th><td> The smallest value that a number can have in the spinner</td></tr>\n<tr><th>max</th><td> The largest value that a number can have in the spinner</td></tr>\n<tr><th>realtime</th><td> Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\n</table>" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/z5NqrRlpTNKW0SYfy1LC_checked-spinner.png", "checked-spinner.png", "1570", "96", "#c77a7a", "" ] } ] } [/block] ## textbox The `textbox` widget creates a simple textbox. ``` { title: "What is your name?", type: "textbox" } ``` ### Additional Properties [block:html] { "html": "<table>\n<tr><th>message</th><td> The message displayed while the textbox has no value</td></tr>\n<tr><th>defaultValue</th><td> The default value of the textbox. This is the value that is set initially and after calling <code>reset()</code></td></tr>\n<tr><th>realtime</th><td> Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\n</table>" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/vriNVfOwTDmbTYkRDER7_textbox.png", "textbox.png", "1570", "100", "#b7b7b7", "" ] } ] } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>defaultValue</th><td> The default value of the password element. This is the value that is set initially and after calling {@link #reset}</td></tr>\n<tr><th>realtime</th><td> Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\n</table>" } [/block] ## textarea The `textarea` widget creates a multi line input widget. ``` { title: "Ignore these files", type: "textarea", width: 150, height: 130, rowheight: 155 } ``` [block:image] { "images": [ { "image": [ "https://files.readme.io/lH7Z8mzjRJa2U6WA7V2u_textarea.png", "textarea.png", "1570", "294", "#acacac", "" ] } ] } [/block] ### Additional Properties [block:html] { "html": "<table>\n<tr><th>height</th><td> The height of the textarea in pixels.</td></tr>\n<tr><th>defaultValue</th><td> The default value of the password element. This is the value that is set initially and after calling {@link #reset}</td></tr>\n<tr><th>realtime</th><td> Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\n</table>" } [/block] ## colorbox The `colorbox` widget allows a user to select a color. ``` { title: "What is your favorite color?", type: "colorbox" } ``` ### Additional Properties [block:html] { "html": "<table>\n<tr><th>defaultValue</th><td> The default value of the colorbox. This is the value that is set initially and after calling {@link #reset}</td></tr>\n<tr><th>realtime</th><td> Whether the values are updated while typing, or only when the form element has lost focus</td></tr>\n</table>" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/NaTQYgrTtqm00IfH0Yhz_colorbox.png", "colorbox.png", "1570", "96", "#474747", "" ] } ] } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>caption</th><td> The text displayed on the button</td></tr>\n<tr><th>onclick</th><td> The function that is executed when a user clicks on the button</td></tr>\n</table>" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/7GFJ1DKVQ96fVYV6EZjh_button.png", "button.png", "1570", "104", "#acacac", "" ] } ] } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>margin</th><td> The edges on the top, right, bottom, left side of the submit element in pixels, space separated (e.g. \"5 5 10 5\").</td></tr>\n<tr><th>caption</th><td> The text displayed on the button</td></tr>\n<tr><th>submenu</th><td> A reference to a menu that is shown when the button is clicked</td></tr>\n<tr><th>onclick</th><td> The function that is executed when a user clicks on the button</td></tr>\n<tr><th>default</th><td> Whether this is the action that is executed when the user presses Enter in one of the form elements</td></tr>\n</table>" } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>caption</th><td> The text displayed on the button</td></tr>\n<tr><th>style</th><td> A css string that is applied to the label</td></tr>\n</table>" } [/block] ## 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 [block:html] { "html": "<table>\n<tr><th>src</th><td> The URL to load the image from</td></tr>\n<tr><th>margin</th><td> The edges on the top, right, bottom, left side of the submit element in pixels, space separated (e.g. \"5 5 10 5\").</td></tr>\n<tr><th>height</th><td> The height of the image in pixels</td></tr>\n</table>" } [/block] ## 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](https://docs.c9.io/api/#!/api/ui). # 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(); ```