The data model of HTML form submission is a map — each form field has a name, and when submit it, the server retrieves the values by names. This model has several problems.
One is the lack of structure; if you have a repeated structure in a form, which in turn contains a nested repeated structure, just giving it a name doesn't allow you to distinguish the nesting structure. IOW, you can't tell ((A,B),(C,D)) from ((A,B,C),(D)) because the map just gives you a single list of 4 items. A similar related issue is when you put a checkbox in a repeated part of a form. If some are checked by some are not, the server can never figure out which ones are checked because that information is lost when a form is submitted.
Another issue is the scope of the name. In HTML, all the form fields need to have unique names. This is akin to have all your variables as global in a programming language, and in a modular extensible system like Hudson, this is not preferable. Scoping of names also prevent a part of the form to be reused elsewhere in the same form.
To avoid these issues and further simplify the server side, in Hudson the notion of the "structured form submission" is introduced.
Structured form submission is a form submission where the data model is a JSON object tree, not a map. This is done by having a client compute the JSON representation at the form submission time, and send that to the server as a hidden text field (along with all the other fields.)
Structure is determined by several factors. First, the name of the form field becomes the JSON property name. For compatibility reasons, a name can have any "abc.def." kind of prefix, and the prefix portion will be ignored. So for example, in the simplest case, the following form will produce the JSON result on the right.
Any intermediate tag can have the 'name' attribute, and that would group the descendants into a intermediate object. Consider the following example:
If there are multiple elements with the same name, their values are aggregated into an array. Consider the following example:
The nesting can be arbitrary deep.
This section applies to Stapler 1.81/Hudson 1.246 and onward.
File uploads in the structured form are renamed to unique names, and the JSON tree will have the name of this unique form name. To remain backward compatible, this processing requires that the file INPUT element contains jsonAware="yes" attribute:
staplerRequest.getFileItem("randomId1234567") would return the file uploaded for Kohsuke, and
Sometimes, the mark up and the layout of the form makes it impossible for a grouped form fields to have a single common ancestor element (for example, often a grouped form elements are spread across multiple table rows.) In such a case, you can put the nameref attribute to merge multiple tree of elements into one. This mechanism is mostly used inside Hudson form layout tags behind the scene, so it's not something plugin developers would need to worry about.
If the nameref attribute points to a check box or a radio button INPUT element, the subordinate structure is only submitted when the INPUT element is selected/checked. This is convenient when such an INPUT element is used to control the visibility of nested form parts.
You can access the entire JSON tree by calling StructuredForm.get(request), but such code is generally only necessary when you are in charge of the entire form submission. Descriptor.configure() and Descriptor.newInstance() take JSONObject, which corresponds to the form fragment that you cntributed via config.jelly/global.jelly.
See some of the Descriptor implementations in Hudson core as an example.
StaplerRequest provides several data-binding method from JSONObject, which greatly simplifies the object instantiaion from form data. See the javadoc of the StaplerRequest.bindJSONXXX methods for details.