Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

WARNING: much of this document is old and suggests code patterns which are not recommended. As of this writing, the official documentation for this area of Jenkins has not been written. The ui-samples plugin is somewhat better maintained than this.

Jelly form controls

Building Tag Library Documentation

Most of the the jelly files in the Jenkins source have embedded documentation. Unfortunately, this documentation is not currently published on the web (only an old version is available). You can generate your own easily! First, get a Jenkins build going, following these directions. Then run "mvn site" which will generate the jelly tag library documentation in hudson/main/core/target/site/jelly-taglib-ref.html (on disk). If you are trying to understand Jenkins' jelly-isms, this document will help a lot.

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.

Jelly code


<f:entry title="${%Access Key ID}" help="...">
  <f:textbox field="accessId" />
<f:entry title="${%Secret Access Key}" help="...">
  <f:password field="secretKey" />
   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.

Finally, 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:

public FormValidation doTestConnection(@QueryParameter("accessId") final String accessId,
        @QueryParameter("secretKey") final String secretKey) throws IOException, ServletException {
    try {
        ... 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.


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

Optional attributes:
  • help (optional) If present, URL of the help HTML page.
  • title (optional) Overrides the button's text content. If not present "Advanced" is used.

Jelly code


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

At start only button is shown:

When the button is clicked it disappears, and the content is displayed instead


Foldable block expanded when the menu item is checked.

Mandatory attributes:
  • name Name of the checkbox.
  • title Human readable text that follows the checkbox
  • checked Initial checkbox status. true/false.
Optional attributes:
  • help (optional) If present, URL of the help HTML page.

Jelly code


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

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.

Jelly code


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

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();
            for (BuildGoal goal : getBuildGoals()) {
                items.add(goal.getDisplayName(), goal.getId());
            return items;

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

Jelly code


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

  • No labels


  1. Unknown User (msreekanth)

    Hi , Can any one point  me location where I can find documentation for jelly form tags?



  2. Unknown User (johnlon)

    Is there a user guide anywhere fo the jelly markup

  3. Unknown User (mindless)

    In the Additional references section of Extend Hudson you'll find links to core Jelly tag documentation.
    For Hudson specific tags, look in the source files.. most have some documentation (for example, look under lib/form from that link to find the form tags).

  4. Unknown User (bshine@yahoo-inc.com)

    Great page! Thank you!

  5. Unknown User (jtatibouet@besancon.parkeon.com)

    Hi everyone,

    "This method needs to be on the Descriptor class that owns this form fragment."

    My question is the following:

    How do you know which Descriptor owns the form fragment ?

    Thank you.

  6. Unknown User (payal)

    Any comments on how do we handle dynamic layout using jelly?

    Like handling event on select drop-down menu?

  7. Unknown User (montapas)


    I have dropdown say the items are item1 item2 and item3. now I want to introduce onchange event for the dropdown. if I select item1 then it will show a textbox say text1 beneath of the dropdown. if I select Item2 then it will show two textboxes text1 and text2. Can anyone help me on this. I am very new on jelly and plugin extension. Thanks in advance.

    With Regards,


    1. Unknown User (jkrthk)

      i am also looking for a similar solution, or even a checkbox which hide a text box would do(i see only check box which shows a text box every where)