Jelly form controls

Most of the the jelly files in the Jenkins source have embedded documentation. See IDE Configuration for details on how to get this setup so you can click through to it in your IDE.

For example you can see the embedded documentation of the <form> tag .

You can also have a look at the referenced design-library-plugin, this repository contains executable examples of user interface elements, including forms. You can also check the live version in weekly.ci.jenkins.io/design-library

Validation Button

This tag creates a right-aligned button for performing server-side validation. It is suitable for situations where the validation depends on the values of multiple input fields, such as credential check that uses both username and password.

<f:entry title="${%Access Key ID}">
  <f:textbox field="accessId" />
</f:entry>
<f:entry title="${%Secret Access Key}">
  <f:password field="secretKey" />
</f:entry>
<f:validateButton
   title="${%Test Connection}" progress="${%Testing...}"
   method="testConnection" with="secretKey,accessId" />

The title attribute is used to determine the text written on the button. The progress attribute determines the message displayed while the server-side validation is in progress. The method attribute specifies the server-side method invoked by this button; this follows the stapler name mangling convention, so for example method="testConnection" will invoke the doTestConnection method. This method needs to be on the Descriptor class that owns this form fragment.

The with attribute specifies the input fields sent to the server for the validation. They are matched against the field attribute or the name attribute of other input controls. The values of the nearest input fields above the <f:validateButton/> are sent to the server, so this means the button has to come after the input fields. Multiple fields can be specified by using ','.

On the server side, this tag invokes the standard "do"-style method like this:

@POST
public FormValidation doTestConnection(@QueryParameter("accessId") final String accessId,
        @QueryParameter("secretKey") final String secretKey,
        @AncestorInPath Job job) throws IOException, ServletException {
    try {
         if (job == null) {
             Jenkins.get().checkPermission(Jenkins.ADMINISTER);
         } else {
             job.checkPermission(Item.CONFIGURE);
         }
        ... do some tests ...
        return FormValidation.ok("Success");
    } catch (EC2Exception e) {
        return FormValidation.error("Client error : "+e.getMessage());
    }
}

The doTestConnection method contains the validation logic. In the end, this method has to call either FormValidation.ok, .warning, or .error method. Depending on which method you use, the appropriate HTML will be rendered on the client side to indicate the status to the user.

Advanced

Expandable section that shows "advanced…​" button by default. Upon clicking it, a section unfolds.

<f:section title="Advanced Project Options">
  <f:advanced>
    <st:include page="configure-advanced.jelly" />
  </f:advanced>
</f:section>

OptionalBlock

Foldable block expanded when the menu item is checked.

<f:block>
  <table>
    <f:optionalBlock name="dynamic" title="Use existing dynamic view">
      <f:entry title="View drive">
        <f:textbox name="drive" value="${it.drive}"/>
      </f:entry>
    </f:optionalBlock>
  </table>
</f:block>

Unchecked the text box will not be displayed Checked the text box is displayed

Select (drop-down menu)

Use an <f:entry> tag to enclose the normal select tag.

<f:entry name="goalType" title="Choose Goal Type" field="goalType">
    <select name="goalType">
        <option value="buildGoal">Build Goal</option>
        <option value="spotBugsGoal">SpotBugs goal</option>
    </select>
</f:entry>

Select (drop-down menu) with model filled values

Basically the same as above. You need to define the following method in the descriptor of your Describable instance:

public ListBoxModel doFillGoalTypeItems() {
    ListBoxModel items = new ListBoxModel();

    items.add("Build Goal", "buildGoal");
    items.add("SpotBugs goal", "spotBugsGoal");

    return items;
}

Then, use an <f:entry> tag to enclose the normal select tag.

<f:entry field="goalType" title="Choose Goal Type">
   <f:select />
</f:entry>

Inline help

Add an inline help to a form element

Most form elements allow you to have inline help generated by adding a small HTML file and following some conventions.

For example the <f:entry> tag uses the field attribute.

Given a file in src/main/resources/myForm.jelly with this content:

<f:entry title="Name" field="name">
    <f:textbox />
</f:entry>

Adding a src/main/resources/help-name.html:

<div>
This is my content to help the end user understanding how to use this field.
</div>

Will automatically display the help button with the <div>…​</div> content.

Additional notes on inline help

  • Most controls support help.html as overall help for the Describable.

  • The help message can be overridden in jelly with the help attribute, but please use the convention help-fieldName.html as much as possible.

  • It is also possible to use localized help files, with the language specific suffix, so help-fieldName.html gets help-fieldName_de.html for the german version.

<f:entry title="This is a nice Title"  help="/plugin/my-plugin/help/custom-file.html">

References