There are a bunch of features in GI 3.9 that improve support for HTML forms.
In versions prior to 3.9 the only forms support was via the jsx3.net.Form class. This is a programatic class (not part of the GI DOM and not painted) that requires a lot of custom JavaScript coding. For example, when the user submits the form you must instantiate the class and copy all field names and values from GI DOM objects to the form. An additional significant shortcoming of jsx3.net.Form is that it has never supported file upload on Firefox.
In GI 3.9 you have two options if you want to integrate your GI application with services that expect submissions via HTML forms. You can still use jsx3.net.Form or you can use jsx3.gui.NativeForm, which is new in 3.9. This new class supports file upload (via POST) on all browsers and should require a lot less JavaScript code on your part.
jsx3.gui.NativeForm extends jsx3.app.Model so it is part of the GI DOM. We added it to the Component Libraries palette (under Form Elements) so you can drag and drop it into your GI component. Just like with a native HTML form, any form fields that are DOM children of a jsx3.gui.NativeForm become part of that form. When the form is submitted, all constituent fields are submitted with the form. There is very little magic going on here; a NativeForm simply renders as a <form> element in HTML and most functionality is provided by the native browser implementation.
There are several form element controls that are compatible with NativeForm. They are:
- jsx3.gui.TextBox - (Text Box, Text Area, Number Input, and Password)
- jsx3.gui.NativeSelect - New in 3.9 (jsx3.gui.Select is not compatible with NativeForm)
- jsx3.gui.FileUpload - New in 3.9
- jsx3.gui.NativeHidden - New in 3.9
- jsx3.NativeButton - New in 3.9 (You can use a jsx3.gui.Button to submit a form by writing an event handler on the button. However, only a NativeButton can submit a CGI parameter.)
- jsx3.gui.RadioButton
- jsx3.gui.CheckBox
- jsx3.gui.DatePicker
In each case besides RadioButton the name of the submitted form field (i.e. CGI parameter) is equal to the Name property of the GI object. In the case of RadioButton the form field is the Group Name property and only one value is submitted for all radio buttons that share the same Group Name.
There are a few important properties of NativeForm that control how the form is submitted. First of all you have Method (GET or POST) and Multipart. Multipart must be true (and Method must be POST) if your form includes a file upload field.
The Action property is the URL of the service to which to submit the form. Note that this can be an absolute or a relative URL. If it is relative, then the URL is resolved relative to the application directory (jsx3.app.Server.resolveURI()).
 | Don't ignore cross domain issues: you can submit to another domain/scheme/port but you will only be able to read the response from the submission if the URL scheme, domain and port are exactly the same as the URL of the page hosting the GI application. |
Finally, the Target and Target IFrame properties control where the response from the submission is displayed. In most cases you will probably want to submit the form invisibly and process the response programatically. In this case set Target to Invisible IFRAME. You can also have the response render in a native popup window (Target = New Window) or have it replace the page hosting the GI application (Target = Current Window). Using the Target IFrame property you can have the response render in an instance of jsx3.gui.IFrame.
We also added a bunch of new components that aid in creating accessible HTML forms. A new class, jsx3.gui.Label, renders a native <label> element. In HTML forms a label is associated with a form field. Set the For Control property of the label to the name of a GI form field to associate it with that field. Using labels helps screen readers and other accessibility software make better sense of the form.
Along with Label there are now components (all instances of jsx3.gui.Block) for <fieldset>, <legend> and <h1> through <h6>. None of these components can do anything visually that a plain old jsx3.gui.Block can't do with the right CSS. However, in general it is better to use the full range of built-in HTML elements when designing for accessibility because each element has meaning independent of how it is rendered.
Here's a screen shot taken from 3.9 Builder of a form being built:
And the source code: form.xml
Related JIRA tickets: