/lib/form
Glorified <select> control that supports the data binding and AJAX updates.
Your descriptor should have the 'doFillXyzItems' method, which returns a ListBoxModel
representation of the items in your drop-down list box, and your instance field should
hold the current value.
Additional CSS classes that the control gets.
Used for databinding.
The default value of the text box, in case both @value is and 'instance[field]' is null.
Foldable block expanded when the corresponding item is selected in the drop-down list.
Human readable title text of this drop-down listbox.
Shown in the same position as <f:entry title="..." />
name of the drop-down list.
Path to the inline help. See <f:entry help="..." />
Generate config pages from a list of Descriptors into a section.
Human readable title of the section to be rendered in HTML.
hudson.model.Descriptor collection whose configuration page is rendered.
The currently configured instance used to fill the initial values of the form.
the type for which descriptors will be configured.
default to ${it.class}
Used as a variable name as well as block name.
Modifies the 'attrs.field' of the parent to inherit @field from the enclosing <f:entry>
if available. Also computes the @checkUrl attribute.
Expandable section that shows "advanced..." button by default.
Upon clicking it, a section unfolds, and the HTML rendered by the body of this tag
appears.
Caption of the button. By default "Advanced"
Additional styles
'left' or 'center' to align the button to left or center.
listbox for choosing the agent's usage.
Name of the <select> element.
Node object.
Sibling of hetero-list, which only allows the user to pick one type from the list of descriptors and configure it.
Field name in the parent object where databinding happens.
all types that the user can add.
Generates an input field to be
used inside <f:entry/>
Used for databinding. TBD.
This becomes @name of the <input> tag.
If @field is specified, this value is inferred from it.
The initial value of the field. This becomes the @value of the <input> tag.
If @field is specified, the current property from the "instance" object
will be set as the initial value automatically,
which is the recommended approach.
The default value of the text box, in case both @value is and 'instance[field]' is null.
Additional CSS class(es) to add (such as client-side validation clazz="required",
"number" or "positive-number"; these may be combined, as clazz="required number").
Override the default error message when client-side validation fails,
as with clazz="required", etc.
If specified, the value entered in this input field will be checked (via AJAX)
against this URL, and errors will be rendered under the text field.
If @field is specified, this will be inferred automatically,
which is the recommended approach.
Renders inline an optional single-value nested data-bound property of the current instance,
by using a <f:optionalBlock>
This is useful when your object composes another data-bound object, and when that's optional,
where the absence of the value is signified as null (in which case the optionalBlock will be drawn unchecked),
and the presence of the value.
Full-width space in the form table that can be filled with arbitrary HTML.
Editable drop-down combo box that supports the data binding and AJAX updates.
Your descriptor should have the 'doFillXyzItems' method, which returns a ComboBoxModel
representation of the items in your combo box, and your instance field should
hold the current value.
Additional CSS classes that the control gets.
Used for databinding.
Outputs an help link for a <f:form> item if help is available or
a spacer if none is available.
The help link is rendered as a table cell with an (?) icon.
If the user clicks it, the content of the HTML fragment at the given URL
is rendered in the area designated as <f:helpArea> by the caller,
usually in a row beneath the item with help.
The alternative spacer is just an empty table cell.
This tag was introduced to ensure that the space reserved for help items
is consistent over the UI whether or not help exists.
@since 1.576
URL to the HTML page. Optional. If not given, no help icon is displayed.
The URL should return a UTF-8 encoded HTML fragment wrapped in a <div> tag.
The URL is interpreted to be rooted at the context path of Jenkins,
so it's normally something like "/plugin/foobar/help/abc.html".
Name of the feature described by the help text, used for constructing the
icon's alt attribute. Optional.
Used inside <f:editableComboBox/> to specify one value of a combobox.
Normally one would use multiple values.
<textarea> tag on steroids.
The textarea will be rendered to fit the content. It also gets the resize handle.
Used for databinding. TBD.
This becomes @name of the <textarea> tag.
If @field is specified, this value is inferred from it.
The initial value of the field. This becomes the value of the <textarea> tag.
If @field is specified, the current property from the "instance" object
will be set as the initial value automatically,
which is the recommended approach.
The default value of the text box, in case both @value is and 'instance[field]' is null.
If specified, the value entered in this input field will be checked (via AJAX)
against this URL, and errors will be rendered under the text field.
If @field is specified, this will be inferred automatically,
which is the recommended approach.
If specified, the HTTP method to use for input field will be checked (via AJAX)
Turns this text area into CodeMirror-assisted code editing text area.
This attribute specifies the mode of CodeMirror, such as "text/x-java".
See http://codemirror.net/ for more details.
Specifies additional key/value pairs in the JSON format (except the start and end bracket)
to be passed as CodeMirror option object.
If specified, this text area has preview feature.
The previewEndpoint is used to obtain formatted html.
Delete button for the <repeatable> tag.
Caption of the button. Defaults to 'Delete'.
Generates an input field to be
used inside <f:entry/>
Used for databinding. TBD.
Used for determining the autocomplete URL.
If @field is specified, that will be used for this.
This becomes @name of the <input> tag.
If @field is specified, this value is inferred from it.
The initial value of the field. This becomes the @value of the <input> tag.
If @field is specified, the current property from the "instance" object
will be set as the initial value automatically,
which is the recommended approach.
The default value of the text box, in case both @value is and 'instance[field]' is null.
Additional CSS class(es) to add (such as client-side validation clazz="required",
"number" or "positive-number"; these may be combined, as clazz="required number").
Override the default error message when client-side validation fails,
as with clazz="required", etc.
If specified, the value entered in this input field will be checked (via AJAX)
against this URL, and errors will be rendered under the text field.
If @field is specified, this will be inferred automatically,
which is the recommended approach.
A single character that can be used as a delimiter for autocompletion. Normal
autocomplete will replace the entire content of the text box with the autocomplete
selection. With this attribute set, the selection will be appended with the
delimiter to the existing value of the text box.
Renders a single <select> control for choosing a Describable.
Depending on the currently selected value, its config.jelly will be
rendered below <select>, allowing the user to configure Describable.
Form field name. Used for databinding.
Human readable title of this control.
Collection that lists up all the valid candidate descriptors.
If unspecified, inferred from the type of the field.
If specified, this will be chosen as the default value in case the current selection is null. The default can be a specific instance or a descriptor e.g.
${descriptor.defaultSettingsProvider} or ${descriptor.defaultSettingsProvider.descriptor}. In the later case, the from input fields will be empty.
Config fragments from descriptors are rendered lazily by default, which means
variables seen in the caller aren't visible to them. This attribute allows you
to nominate additional variables and their values to be captured for descriptors.
Generates an anchor element with the ability to send POST requests and/or
asynchronous requests. It depends the combination of post and async attributes.
@since 1.584
Additional CSS classes.
Link destination URL.
If this must send a POST request.
If this must send an asynchronous request.
Renders a row that shows description text below an input field.
Adds one more in-page breadcrumb that jumps to sections in the page.
Put this tag right before <l:main-panel>
Execute the body with a temporary currentDescriptorByNameUrl value
Generate config pages from a list of Descriptors into a section.
Human readable title of the section to be rendered in HTML.
hudson.model.Descriptor collection whose configuration page is rendered.
Map<Descriptor,Describable> that defines current instances of those descriptors.
These are used to fill initial values. Other classes that define the get(Descriptor)
method works fine, too, such as DescribableList.
Either @field or @instances are required (or @field may be inherited from the ancestor <entry> element).
If field is specified, instances are assumed to be instance[field].
When this attribute is specified, JSON structure is properly set up so that the databinding
can set the field (or pass this collection as a constructor parameter of the same name.
This is more modern way of doing databinding, and thus preferred approach.
the type for which descriptors will be configured.
default to ${it.class}
If specified, instead of a sequence of <f:optionalBlock>s, draw a sequence of <rowSet>s.
Glorified <input type="password">
Used for databinding. TBD.
This becomes @name of the <input> tag.
If @field is specified, this value is inferred from it.
The initial value of the field. This becomes the @value of the <input> tag.
If @field is specified, the current property from the "instance" object
will be set as the initial value automatically,
which is the recommended approach.
Additional CSS class(es) to add (such as client-side validation clazz="required",
"number" or "positive-number"; these may be combined, as clazz="required number").
If specified, the value entered in this input field will be checked (via AJAX)
against this URL, and errors will be rendered under the text field.
If @field is specified, this will be inferred automatically,
which is the recommended approach.
Generates an input field to be
used inside <f:entry/>
Used for databinding. TBD.
This becomes @name of the <input> tag.
If @field is specified, this value is inferred from it.
The initial value of the field. This becomes the @value of the <input> tag.
If @field is specified, the current property from the "instance" object
will be set as the initial value automatically,
which is the recommended approach.
The default value of the text box, in case both @value is and 'instance[field]' is null.
Additional CSS class(es) to add (such as client-side validation clazz="required",
"number" or "positive-number"; these may be combined, as clazz="required number").
Override the default error message when client-side validation fails,
as with clazz="required", etc.
If specified, the value entered in this input field will be checked (via AJAX)
against this URL, and errors will be rendered under the text field.
If @field is specified, this will be inferred automatically,
which is the recommended approach.
<input type="checkbox"> tag that takes true/false for @checked, which is more Jelly friendly.
Normally, the submitted JSON will be boolean indicating whether the checkbox was checked or not.
This is sometimes inconvenient if you have a UI that lets user select a subset of a set.
If this attribute is present, the submitted JSON will have this as a string value if the checkbox is checked,
and none otherwise, making the subset selection easier.
The default value of the check box, in case both @checked and @instance are null.
If this attribute is unspecified or null, it defaults to unchecked, otherwise checked.
If set to true, this will take precedence over the onclick attribute and prevent the state of the checkbox from being changed.
Used for databinding. TBD.
If specified, this human readable text will follow the checkbox, and clicking this text also
toggles the checkbox.
Used as tooltip of the checkbox, and, if a title is specified, of the title
An entry of the <f:form>, which is one logical row (that consists of
several <TR> tags.
One entry normally host one control.
Name of the entry. Think of this like a label for the control.
This content is HTML (unless the boolean variable escapeEntryTitleAndDescription is set). Use h.escape if necessary.
Used for the databinding. TBD. When this attribute
is specified, @help is inferred, and nested input controls don't need
the @field nor @name.
If it's not obvious to the user as to what the control expects,
specify some description text (which currently gets rendered as
small text under the control, but that may change.)
This text shouldn't get too long, and in recent Hudson, this feature
is somewhat de-emphasized, in favor of the inline foldable help page
specified via @help.
This content is HTML (unless the boolean variable escapeEntryTitleAndDescription is set). Use h.escape if necessary.
URL to the HTML page. When this attribute is specified, the entry gets
a (?) icon on the right, and if the user clicks it, the contents of the
given URL is rendered as a box below the entry.
The URL should return an HTML document wrapped in a <div> tag.
The URL is interpreted to be rooted at the context path of Hudson,
so it's normally something like "/plugin/foobar/help/abc.html".
Invisible <f:entry> type. Useful for adding hidden field values.
Foldable block expanded when the corresponding item is selected in the drop-down list.
value of the list item. set to <option value="...">
human readable text displayed for this list item.
is this value initially selected?
provide hint for stapler data binding.
typically set to ${descriptor.clazz.name} if dropdownList is for a list of descriptors.
If specified, the content of the dropdownListBlock will be rendered lazily when it first becomes visible.
The attribute value must be the variables to be captured. See the @capture of <renderOnDemand> tag.
Repeatable blocks used to present UI where the user can configure multiple entries
of the same kind (see the Java installations configuration in the system config.)
This tag works like <j:forEach> and repeatedly evaluate the body so that
initially all the items get their own copy. This tag also evaluate the body
once more with var=null to create a 'master copy', which is the template entry
used when a new copy is inserted.
h1. HTML structure
this tag mainly produces the nested DIVs with CSS classes as follows:
{noformat}
<div class="repeated-container"> // container for the whole thing
<div class="repeated-chunk">
... copy 1 ...
<div class="repeated-chunk">
... copy 2 ...
...
{noformat}
The 'repeated-chunk' DIVs will also have additional CSS classes that represent
their positions among siblings:
first : first chunk among the siblings
last : last chunk among the siblings
middle: neither first nor last
only : it is the only chunk (automatically get first and last at the same time)
h1. Usage Note
The caller of this tag should define a button to add a new copy and delete
the current copy. Such buttons should have 'repeatable-add' CSS class and
'repeatable-delete' CSS class respectively (it can have other CSS classes),
so that their event handlers get properly wired up.
The positional CSS classes on 'repeated-chunk' DIVs (as explained above)
can be used to control the visibility of such buttons. For example, this allows
you to hide 'delete' button if there's only one item, or only show 'add' button
on the last row. There are a few CSS classes already defined in style.css
for this purpose.
variable that receives the item of the current iteration.
Accessible from the body. Required unless @field is given.
Status variable that indicates the loop status.
name used in the structured form submission. Defaults to the same name as @var.
Used for the data binding.
The item collection to loop over. Required unless @field is given.
Use this collection for items if items or @field is null
true if the default 'add' button (that adds a new copy) shouldn't be displayed.
When you use this attribute,
If specified, this text will replace the standard "Add" text.
At least provide this number of copies initially.
minimum="1" is useful to make sure there's always at least one entry for the user to fill in.
For each item, add this header.
This also activates drag&drop (where the header is a grip).
Adds @nameRef to all table rows inside this tag, so that when the form is submitted,
it gets grouped in one JSON object.
if the group head is not available outside, use this attribute to specify the name.
@name and @ref are mutually exclusive.
id of the thing that serves as the group head, if that's available separately
Outer most tag for creating a heterogeneous list, where the user can choose arbitrary number of
arbitrary items from the given list of descriptors, and configure them independently.
The submission can be data-bound into List<T> where T is the common base type for the describable instances.
For databinding use, please use <f:repeatableHeteroProperty />
form name that receives an array for all the items in the heterogeneous list.
existing items to be displayed. Something iterable, such as array or collection.
all types that the user can add.
caption of the 'add' button.
caption of the 'delete' button.
the type for which descriptors will be configured. Defaults to ${it.class} (optional)
For each item, add a caption from descriptor.getDisplayName().
This also activates drag&drop (where the header is a grip), and help text support.
If true, only allow up to one instance per descriptor.
Menu alignment against the button. Defaults to tl-bl
If true, insert new addition by default to their 'desired' location, which
is the order induced by the descriptors.
Config fragments from descriptors are rendered lazily by default, which means
variables seen in the caller aren't visible to them. This attribute allows you
to nominate additional variables and their values to be captured for descriptors.
<input type="radio"> tag that takes true/false for @checked, which is more Jelly friendly.
Note that safari doesn't support onchange.
Beware that the name attribute should be uniquified among all radio blocks on the page, such as by prefixing it with "G0025." or whatever gensym.
If specified, this human readable text will follow the radio, and clicking this text also
toggles the radio.
See
http://wiki.jenkins-ci.org/display/JENKINS/Jelly+form+controls
for the reference.
Server-side method that handles the validation. For example, if this is 'foo', you need "doFoo" on
your descriptor class.
Caption of the validate button. Should be internationalized.
Caption of the text shown while the AJAX call is in progress. For example, "checking..."
','-separated list of fields that are sent to the server.
Binds an enum field to a <select> element.
The body of this tag is evaluated for each enum value,
which is passed as 'it'.
Used for databinding. TBD.
The name of the enum to set as default value for the first configuration.
Editable drop-down combo box. Deprecated as of 1.356. Use f:combobox and databinding instead.
Additional CSS classes that the control gets.
List of possible values. Either this or nested <f:editableComboBoxValue/>s are required.
Used for databinding.
Place holder to lazy-load help text via AJAX.
Binds a boolean field to two radio buttons that say Yes/No OK/Cancel Top/Bottom.
Databinding field.
Text to be displayed for the 'true' value. Defaults to 'Yes'.
Text to be displayed for the 'false' value. Defaults to 'No'.
Binds a set of Enum to a list of checkboxes, each with the label taken from enum Enum.toString()
Should be used inside an <f:entry field='...'> element.
Used for databinding.
on
Radio button with a label that hides additional controls.
When checked, those additional controls are displayed. This is useful
for presenting mutually exclusive options, where each option comes
with a sub-form that provides additional configuration.
Name of the radio button group. Radio buttons that are mutually exclusive need
to have the same name.
@value of the <input> element.
Human readable label text to be rendered next to the radio button.
Should this control be initially checked or not?
if present, the folded section will not be grouped into a separate JSON object upon submission.
If specified, the (?) help icon will be rendered on the right,
for in place help text. See <f:entry> for the details.
Data-bound only version of <f:hetero-list> that assumes the type pointed by the property is data-bound as well.
The nested property type must be Describable and it needs to have config.jelly.
Used for the data binding.
caption of the 'add' button.
caption of the 'delete' button.
the type for which descriptors will be configured. Defaults to ${it.class} (optional)
For each item, add a caption from descriptor.getDisplayName().
This also activates drag&drop (where the header is a grip), and help text support.
If true, only allow up to one instance per descriptor.
Menu alignment against the button. Defaults to tl-bl
If true, insert new addition by default to their 'desired' location, which
is the order induced by the descriptors.
Config fragments from descriptors are rendered lazily by default, which means
variables seen in the caller aren't visible to them. This attribute allows you
to nominate additional variables and their values to be captured for descriptors.
Data-bound only version of <f:repeatable> that assumes the type pointed by the property is data-bound as well.
The nested property type must be Describable and it needs to have config.jelly.
Unless that nested config.jelly already adds a delete button (deprecated), you should normally put the following inside this tag:
<f:entry title="">
<div align="right">
<f:repeatableDeleteButton />
</div>
</f:entry>
Used for the data binding.
The default value to use for this collection when 'instance[field]' is null.
true if the default 'add' button (that adds a new copy) shouldn't be displayed.
When you use this attribute,
If specified, this text will replace the standard "Add" text.
At least provide this number of copies initially.
minimum="1" is useful to make sure there's always at least one entry for the user to fill in.
For each item, add this header.
This also activates drag&drop (where the header is a grip).
Submit button themed by YUI. This should be always
used instead of the plain <input tag.
If specified, becomes the value of the name attribute.
When you have more than one submit button on the form, this can be used to determine
which button is pressed, as the server will get a parameter by this name.
The text of the submit button. Something like "submit", "OK", etc.
Section header in the form table.
The section header text.
If null is given, the entire <f:section> tag becomes no-op.
Optional attribute to create a JSON object from this section.
Rich HTML editor from http://developer.yahoo.com/yui/editor/
All the attributes are those of the <textarea> tag.
Invisible <f:entry> type for embedding a descriptor's $class field.
Most of the time a Descriptor has an unique class name that we can use to instantiate the right Describable
class, so we use the '$class' to represent that to clarify the intent.
In some other times, such as templates, there are multiple Descriptors with the same Descriptor.clazz
but different IDs, and in that case we put 'kind' to indicate that. In this case, to avoid confusing
readers we do not put non-unique '$class'.
See Descriptor.newInstancesFromHeteroList for how the reader side is handled.
The describable class that we are instantiating via structured form submission.
The descriptor of the describable that we are instantiating via
structured form submission. Mutually exclusive with clazz.
"Apply" button that submits the form but without a page transition.
See hudson.util.FormApply for the server-side code.
When this button is pressed, the FORM element fires the "jenkins:apply" event
that allows interested parties to write back whatever states back into the INPUT
elements.
The text of the apply button.
Renders inline a single-value nested data-bound property of the current instance.
This is useful when your object composes another data-bound object as a nested object,
yet your UI would still like to render it
If specified, bypass the item descriptor inference and use this instead.
Foldable block that can be expanded to show more controls by checking the checkbox.
Name of the checkbox. Can be used by the server to determine
if the block is collapsed or expanded at the time of submission.
Note that when the block is collapsed, none of its child controls will send
the values to the server (unlike <f:advanced>)
Human readable text that follows the checkbox.
If this field is null, the checkbox degrades to a <f:rowSet>, which provides
a grouping at JSON level but on the UI there's no checkbox (and you always see
the body of it.)
Used for databinding. TBD. Either this or @name/@title combo is required.
initial checkbox status. true/false.
If present, the (?) icon will be rendered on the right to show inline help.
See @help for <f:entry>.
if present, the foldable section expands when the checkbox is unchecked.
if present, the foldable section will not be grouped into a separate JSON object upon submission
Outer-most tag of the entire form taglib, that generates <form> element.
@action of the form field. The URL where the submission is sent.
Submission method. Either post or get.
@name of the form. In HTML this is not a mandatory attribute,
but in Hudson you should have it for testing and page scraping,
so this attribute is marked required.
@enctype of the <form> HTML element.
@target of the <form> HTML element. Works like <a target="...">
and controls which window the result of the submission goes to.
Optional class attribute for <table> that is created in the form.
Optional attribute for allowing browsers to perform auto complete or pre-fill the form from history.
Default: false
single-line textbox that can be expanded into a multi-line textarea.
This control is useful for a field that expects multiple whitespace-separated tokens
(such as URLs, glob patterns, etc.) When the user only enters a few tokens,
they can keep it as a single line to save space, but to enter a large number of values,
this can be turned into textarea for better visibility.
If the initial value is already multi-line text, the control starts with
textarea.
On the server side, your program is responsible for treating ' ', \t, \r, and \n for
separators. (StringTokenizer would do this.)
Used for databinding. TBD.
This becomes @name of the <input> tag.
If @field is specified, this value is inferred from it.
The initial value of the field. This becomes the @value of the <input> tag.
If @field is specified, the current property from the "instance" object
will be set as the initial value automatically,
which is the recommended approach.
Creates a button bar at the bottom of the page for things like "Submit".
The actual buttons should be specified as the body of this tag.
This area will always be visible in the bottom of the screen.
<option> tag for the <select> element that takes true/false for selected.
The value to be sent when the form is submitted.
If omitted, the body of the tag will be placed in the value attribute as well
(due to the browser incompatibility between IE and Firefox, value attribute
must be included).
If true, the option value appears as selected.