The following Jelly tag libraries are defined in this project.

Namespace URI Description
/lib/form

/lib/form

/lib/hudson

/lib/hudson

/lib/test

/lib/test

/lib/hudson/project

Tag files used in project pages

/lib/layout

Tag library that defines the basic layouts of Jenkins pages.

/lib/hudson/newFromList

These tags provide a higher level primitive for building a form page for creating a new item from a list of descriptors.Used in "create new job" page, for an example.

/lib/form

/lib/form

This tag library is also available as an XML Schema

Tag Name Description
advanced

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.

apply

"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.

block

Full-width space in the form table that can be filled with arbitrary HTML.

booleanRadio

Binds a boolean field to two radio buttons that say Yes/No OK/Cancel Top/Bottom.

bottomButtonBar

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 at the bottom of the screen.

breadcrumb-config-outline

Adds one more in-page breadcrumb that jumps to sections in the page. Put this tag right before <l:main-panel>

checkbox

<input type="checkbox"> tag that takes true/false for @checked, which is more Jelly friendly.

class-entry

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.

combobox

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.

For a read only input set <j:set var="readOnlyMode" value="true"/> inside your entry tag See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support

description

Renders a row that shows description text below an input field.

descriptorList

Generate config pages from a list of Descriptors into a section.

descriptorRadioList

Generate config pages from a list of Descriptors into a section.

dropdownDescriptorSelector

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.

dropdownList

Foldable block expanded when the corresponding item is selected in the drop-down list.

dropdownListBlock

Foldable block expanded when the corresponding item is selected in the drop-down list.

editableComboBox

Editable drop-down combo box. Deprecated as of 1.356. Use f:combobox and databinding instead.

editableComboBoxValue

Used inside <f:editableComboBox/> to specify one value of a combobox. Normally one would use multiple values.

entry

An entry of the <f:form>, which is one logical row (that consists of several <TR> tags.

One entry normally host one control.

enum

Binds an enum field to a <select> element. The body of this tag is evaluated for each enum value, which is passed as 'it'.

enumSet

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.

expandableTextbox

A 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.)

file

Generates an input field All unknown attributes are passed through to the field.

@since 2.385

form

Outer-most tag of the entire form taglib, that generates <form> element.

helpArea

Place holder to lazy-load help text via AJAX.

helpLink

Outputs a 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

hetero-list

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 />

hetero-radio

Sibling of hetero-list, which only allows the user to pick one type from the list of descriptors and configure it.

invisibleEntry

Invisible <f:entry> type. Useful for adding hidden field values.

link

Generates an anchor element with the ability to send POST requests.

@since 1.584

nested
number

Generates an input field to be used inside <f:entry/>

option

<option> tag for the <select> element that takes true/false for selected.

optionalBlock

Foldable block that can be expanded to show more controls by checking the checkbox.

optionalProperty

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.

password

Glorified <input type="password">

possibleReadOnlyField
prepareDatabinding

Modifies the 'attrs.field' of the parent to inherit @field from the enclosing <f:entry> if available. Also computes the @checkUrl attribute.

property

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

radio

<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.

For a read only radio input set <j:set var="readOnlyMode" value="true"/> inside your entry tag See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support

radioBlock

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.

readOnlyTextbox

Generates an input field to be used inside <f:entry/>

repeatable

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.

HTML structure

This tag mainly produces the nested DIVs with CSS classes as follows:

      <div class="repeated-container">   // container for the whole thing
        <div class="repeated-chunk">
          ... copy 1 ...
        <div class="repeated-chunk">
          ... copy 2 ...
        ...
      

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)

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.

repeatableDeleteButton

Delete button for the <repeatable> tag.

repeatableHeteroProperty

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.

repeatableProperty

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:block>
          <div align="right">
            <f:repeatableDeleteButton />
          </div>
        </f:block>
        

Due to a bug in Stapler data binding the model elements are only set if they consist of one or more values. If all values have been removed in the user interface (i.e. the associated form is empty), then the setter is not invoked anymore. As a workaround, you need to override the corresponding configure method and clear the model property manually before invoking the data binding. See warnings-ng-plugin PR#266.

rowSet

Adds @nameRef to all table rows inside this tag, so that when the form is submitted, it gets grouped in one JSON object.

secretTextarea

Enhanced version of <f:textarea/> for editing multi-line secrets.

Example usage:

<j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">
    <f:entry title="Secret" field="secret">
        <f:secretTextarea/>
    </f:entry>
    <f:entry title="Secret 2">
        <f:secretTextarea field="secret2"/>
    </f:entry>
    <f:entry title="Another Secret">
        <f:secretTextarea name="foo" value="${it.foo}"/>
    </f:entry>
</j:jelly>

section

Section header in the form table.

select

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.

slave-mode

A listbox for choosing the agent's usage.

submit

Submit button. This should be always used instead of the plain <button> tag.

textarea

<textarea> tag on steroids. The textarea will be rendered to fit the content. It also gets the resize handle.

textbox

Generates an input field to be used inside <f:entry/>

For a read only input set <j:set var="readOnlyMode" value="true"/> inside your entry tag See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support

toggleSwitch

<input type="checkbox"> tag that takes true/false for @checked, which is more Jelly friendly.

validateButton

See https://www.jenkins.io/doc/developer/forms/jelly-form-controls/ for the reference.

withCustomDescriptorByName

Execute the body with a temporary currentDescriptorByNameUrl value

advanced

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.

Attribute Name Type Description
title -

Caption of the button. By default "Advanced"

apply

"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.

Attribute Name Type Description
value -

The text of the apply button.

This tag does not accept any child elements/text.

block

Full-width space in the form table that can be filled with arbitrary HTML.

booleanRadio

Binds a boolean field to two radio buttons that say Yes/No OK/Cancel Top/Bottom.

Attribute Name Type Description
false -

Text to be displayed for the 'false' value. Defaults to 'No'.

field -

Databinding field.

true -

Text to be displayed for the 'true' value. Defaults to 'Yes'.

This tag does not accept any child elements/text.

bottomButtonBar

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 at the bottom of the screen.

breadcrumb-config-outline

Adds one more in-page breadcrumb that jumps to sections in the page. Put this tag right before <l:main-panel>

Attribute Name Type Description
title -

Optional title for this breadcrumb

This tag does not accept any child elements/text.

checkbox

<input type="checkbox"> tag that takes true/false for @checked, which is more Jelly friendly.

Attribute Name Type Description
checked -
class -
default -

The default value of the checkbox, in case both @checked and @instance are null. If this attribute is unspecified or null, it defaults to unchecked, otherwise checked.

field -

Used for databinding. TBD.

id -
json -

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.

name -
negative -
onclick (deprecated) -

Inline JavaScript to execute when the checkbox is clicked. Deprecated because this attribute is incompatible with adding Content-Security-Policy to the Jenkins UI in the future. Set 'id' or 'class' attributes as appropriate to look up this element in external Javascript files (e.g. adjuncts) to add the desired behavior there (DOMContentLoaded event in static forms, Behaviour.specify if this element may be dynamically added). See https://github.com/jenkinsci/jenkins/pull/6852 for an example.

readonly (deprecated) -

If set to true, this will take precedence over the onclick attribute and prevent the state of the checkbox from being changed.

Note: if you want an actual read only checkbox then add: <j:set var="readOnlyMode" value="true"/> inside your entry tag See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support

title -

If specified, this human readable text will follow the checkbox, and clicking this text also toggles the checkbox.

tooltip -

Used as tooltip of the checkbox, and, if a title is specified, of the title

value -

This tag does not accept any child elements/text.

class-entry

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.

Attribute Name Type Description
clazz -

The describable class that we are instantiating via structured form submission.

descriptor -

The descriptor of the describable that we are instantiating via structured form submission. Mutually exclusive with clazz.

This tag does not accept any child elements/text.

combobox

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.

For a read only input set <j:set var="readOnlyMode" value="true"/> inside your entry tag See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support

Attribute Name Type Description
checkMethod String

Specify 'get' (must be lowercase) to change the HTTP method used for the AJAX requests to @checkUrl from a POST to a GET. If any other value is specified then requests will use POST. The historical default was GET and 'post' had to be specified to change that, but this was changed in Jenkins 2.285.

checkUrl -

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.

clazz -

Additional CSS classes that the control gets.

default -

The default value of the combo box, in case both @value and 'instancefield' are null.

field -

Used for databinding.

name -

This becomes @name of the <input> tag. If @field is specified, this value is inferred from it.

value -

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.

This tag does not accept any child elements/text.

description

Renders a row that shows description text below an input field.

descriptorList

Generate config pages from a list of Descriptors into a section.

Attribute Name Type Description
descriptors (required) -

hudson.model.Descriptor collection whose configuration page is rendered.

field -

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 instancefield.

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.

forceRowSet -

If specified, instead of a sequence of <f:optionalBlock>s, draw a sequence of <rowSet>s.

icon -

Sets the icon on the sidebar item for the section anchor link The icon isn't visible in the section itself

instances -

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.

targetType -

the type for which descriptors will be configured. default to ${it.class}

title -

Human readable title of the section to be rendered in HTML.

descriptorRadioList

Generate config pages from a list of Descriptors into a section.

Attribute Name Type Description
descriptors (required) -

hudson.model.Descriptor collection whose configuration page is rendered.

instance (required) -

The currently configured instance used to fill the initial values of the form.

targetType -

the type for which descriptors will be configured. default to ${it.class}

title (required) -

Human readable title of the section to be rendered in HTML.

varName (required) -

Used as a variable name as well as block name.

dropdownDescriptorSelector

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.

Attribute Name Type Description
capture -

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.

default -

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.

descriptors -

Collection that lists up all the valid candidate descriptors. If unspecified, inferred from the type of the field.

field (required) -

Form field name. Used for databinding.

title (required) -

Human readable title of this control.

dropdownList

Foldable block expanded when the corresponding item is selected in the drop-down list.

Attribute Name Type Description
help -

Path to the inline help. See <f:entry help="..." />

name (required) -

name of the drop-down list.

title -

Human readable title text of this drop-down listbox. Shown in the same position as <f:entry title="..." />

dropdownListBlock

Foldable block expanded when the corresponding item is selected in the drop-down list.

Attribute Name Type Description
lazy -

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.

selected boolean

is this value initially selected?

staplerClass -

provide hint for stapler data binding. typically set to ${descriptor.clazz.name} if dropdownList is for a list of descriptors.

title (required) -

human readable text displayed for this list item.

value (required) -

value of the list item. set to <option value="...">

editableComboBox

Editable drop-down combo box. Deprecated as of 1.356. Use f:combobox and databinding instead.

Attribute Name Type Description
clazz -

Additional CSS classes that the control gets.

field -

Used for databinding.

items -

List of possible values. Either this or nested <f:editableComboBoxValue/>s are required.

editableComboBoxValue

Used inside <f:editableComboBox/> to specify one value of a combobox. Normally one would use multiple values.

Attribute Name Type Description
value (required) -

This tag does not accept any child elements/text.

entry

An entry of the <f:form>, which is one logical row (that consists of several <TR> tags.

One entry normally host one control.

Attribute Name Type Description
class -

Classes to apply to the form item

description -

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.

field -

Used for the databinding. TBD. When this attribute is specified, @help is inferred, and nested input controls don't need the @field nor @name.

help -

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".

title -

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.

enum

Binds an enum field to a <select> element. The body of this tag is evaluated for each enum value, which is passed as 'it'.

Attribute Name Type Description
default -

The name of the enum to set as default value for the first configuration.

field -

Used for databinding. TBD.

enumSet

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.

Attribute Name Type Description
field -

Used for databinding.

This tag does not accept any child elements/text.

expandableTextbox

A 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.)

Attribute Name Type Description
field -

Used for databinding. TBD.

name -

This becomes @name of the <input> tag. If @field is specified, this value is inferred from it.

value -

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.

This tag does not accept any child elements/text.

file

Generates an input field All unknown attributes are passed through to the field.

@since 2.385

Attribute Name Type Description
accept -

Defines the file types the file input should accept. This string is a comma-separated list.

clazz -

Additional CSS class(es) to add.

field -

Used for databinding.

jsonAware -

Enable structured form submission.

name -

This becomes @name of the <input> tag. If @field is specified, this value is inferred from it.

This tag does not accept any child elements/text.

form

Outer-most tag of the entire form taglib, that generates <form> element.

Attribute Name Type Description
action (required) -

@action of the form field. The URL where the submission is sent.

autocomplete -

Optional attribute for allowing browsers to perform auto complete or pre-fill the form from history. Default: false

class -

Classes to apply to the form

enctype -

@enctype of the <form> HTML element.

id -

ID of the form.

method (required) -

Submission method. Either post or get.

name (required) -

@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.

tableClass -

Optional class attribute for <table> that is created in the form.

target -

@target of the <form> HTML element. Works like <a target="..."> and controls which window the result of the submission goes to.

helpArea

Place holder to lazy-load help text via AJAX.

This tag does not accept any child elements/text.

helpLink

Outputs a 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

Attribute Name Type Description
featureName -

Name of the feature described by the help text, used for constructing the icon's alt attribute. Optional.

url -

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".

This tag does not accept any child elements/text.

hetero-list

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 />

Attribute Name Type Description
addCaption -

caption of the 'add' button.

capture -

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.

deleteCaption -

caption of the 'delete' button.

descriptors (required) -

all types that the user can add.

disableDragAndDrop java.lang.Boolean

If true the drag and drop will not be activated. This just removes the drag and drop UI, it will not prevent users from manually submitting a different order.

hasHeader -

For each item, add a caption from descriptor.getDisplayName(). This also activates drag&drop (where the header is a grip), and help text support.

honorOrder -

If true, insert new addition by default to their 'desired' location, which is the order induced by the descriptors.

items (required) java.util.Collection

existing items to be displayed. Something iterable, such as array or collection.

menuAlign -

Menu alignment against the button. Defaults to tl-bl

name (required) -

form name that receives an array for all the items in the heterogeneous list.

oneEach -

If true, only allow up to one instance per descriptor.

targetType -

the type for which descriptors will be configured. Defaults to ${it.class} (optional)

titleClassMethod -

If set to an item of the form , it will be used to call to calculate each item title.

hetero-radio

Sibling of hetero-list, which only allows the user to pick one type from the list of descriptors and configure it.

Attribute Name Type Description
descriptors (required) -

all types that the user can add.

field (required) -

Field name in the parent object where databinding happens.

This tag does not accept any child elements/text.

invisibleEntry

Invisible <f:entry> type. Useful for adding hidden field values.

link

Generates an anchor element with the ability to send POST requests.

@since 1.584

Attribute Name Type Description
clazz -

Additional CSS classes.

href -

Link destination URL.

post -

If this must send a POST request.

nested

number

Generates an input field to be used inside <f:entry/>

Attribute Name Type Description
checkMessage -

Override the default error message when client-side validation fails, as with clazz="required", etc.

checkMethod String

Specify 'get' (must be lowercase) to change the HTTP method used for the AJAX requests to @checkUrl from a POST to a GET. If any other value is specified then requests will use POST. The historical default was GET and 'post' had to be specified to change that, but this was changed in Jenkins 2.285.

checkUrl -

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.

clazz -

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").

default -

The default value of the text box, in case both @value is and 'instancefield' is null.

field java.lang.String

Used for databinding. TBD.

max -

The maximum of the @value. This becomes the @max of the <input> tag. This will work only @clazz is 'number', 'number-required', 'non-negative-number-required', 'positive-number', 'positive-number-required'. If specified, the @value should be less than this value, or errors will be rendered under the text field. If this value contains non-digit characters, it will not work. If @min is specified and @min is greater than this value, both @min and @max will not work.

min -

The minimum of the @value. This becomes the @min of the <input> tag. This will work only @clazz is 'number', 'number-required', 'non-negative-number-required', 'positive-number', 'positive-number-required'. If specified, the @value should be greater than this value, or errors will be rendered under the text field. If this value contains non-digit characters, it will not work. If @max is specified and @max is less than this value, both @min and @max will not work.

name java.lang.String

This becomes @name of the <input> tag. If @field is specified, this value is inferred from it.

value -

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.

This tag does not accept any child elements/text.

option

<option> tag for the <select> element that takes true/false for selected.

Attribute Name Type Description
selected boolean

If true, the option value appears as selected.

value -

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).

optionalBlock

Foldable block that can be expanded to show more controls by checking the checkbox.

Attribute Name Type Description
checked -

initial checkbox status. true/false.

field -

Used for databinding. TBD. Either this or @name/@title combo is required.

help -

If present, the (?) icon will be rendered on the right to show inline help. See @help for <f:entry>.

inline -

if present, the foldable section will not be grouped into a separate JSON object upon submission

name -

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>)

negative -

if present, the foldable section expands when the checkbox is unchecked.

title -

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.)

optionalProperty

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.

Attribute Name Type Description
field (required) -
help -
title (required) -

This tag does not accept any child elements/text.

password

Glorified <input type="password">

Attribute Name Type Description
checkMessage -

Override the default error message when client-side validation fails, as with clazz="required", etc.

checkUrl -

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.

clazz -

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").

field -

Used for databinding. TBD.

name -

This becomes @name of the <input> tag. If @field is specified, this value is inferred from it.

value -

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.

This tag does not accept any child elements/text.

possibleReadOnlyField

prepareDatabinding

Modifies the 'attrs.field' of the parent to inherit @field from the enclosing <f:entry> if available. Also computes the @checkUrl attribute.

This tag does not accept any child elements/text.

property

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

Attribute Name Type Description
field (required) -
propertyDescriptor -

If specified, bypass the item descriptor inference and use this instead.

This tag does not accept any child elements/text.

radio

<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.

For a read only radio input set <j:set var="readOnlyMode" value="true"/> inside your entry tag See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support

Attribute Name Type Description
checked -
id -
name -
onclick -
title -

If specified, this human readable text will follow the radio, and clicking this text also toggles the radio.

value -

radioBlock

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.

Attribute Name Type Description
checked (required) boolean

Should this control be initially checked or not?

help -

If specified, the (?) help icon will be rendered on the right, for in place help text. See <f:entry> for the details.

inline -

if present, the folded section will not be grouped into a separate JSON object upon submission.

name (required) -

Name of the radio button group. Radio buttons that are mutually exclusive need to have the same name.

title (required) -

Human readable label text to be rendered next to the radio button.

value (required) -

@value of the <input> element.

readOnlyTextbox

Generates an input field to be used inside <f:entry/>

Attribute Name Type Description
checkMessage -

Override the default error message when client-side validation fails, as with clazz="required", etc.

checkUrl -

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.

clazz -

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").

default -

The default value of the text box, in case both @value is and 'instancefield' is null.

field -

Used for databinding. TBD.

name -

This becomes @name of the <input> tag. If @field is specified, this value is inferred from it.

value -

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.

This tag does not accept any child elements/text.

repeatable

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.

HTML structure

This tag mainly produces the nested DIVs with CSS classes as follows:

      <div class="repeated-container">   // container for the whole thing
        <div class="repeated-chunk">
          ... copy 1 ...
        <div class="repeated-chunk">
          ... copy 2 ...
        ...
      

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)

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.

Attribute Name Type Description
add -

If specified, this text will replace the standard "Add" text.

default -

Use this collection for items if items or @field is null

enableTopButton -

true if a new Add button, for adding new copy of repeatable item, should be displayed above repeatable form. Display of top button depends also on number of items. If there is no item, only one button is displayed. When at least one item is present, there are two buttons displayed (only when enableTopButton is true). One above and one below. Top button adds item on top of repeatable form. Bottom button adds item on the bottom of repeatable form.

field -

Used for the data binding.

header -

For each item, add this header. This also activates drag&drop (where the header is a grip).

items -

The item collection to loop over. Required unless @field is given.

minimum -

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.

name -

name used in the structured form submission. Defaults to the same name as @var.

noAddButton -

true if the default 'add' button (that adds a new copy) shouldn't be displayed. When you use this attribute,

var -

variable that receives the item of the current iteration. Accessible from the body. Required unless @field is given.

varStatus -

Status variable that indicates the loop status.

repeatableDeleteButton

Delete button for the <repeatable> tag.

Attribute Name Type Description
value -

Caption of the button. Defaults to 'Delete'.

This tag does not accept any child elements/text.

repeatableHeteroProperty

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.

Attribute Name Type Description
addCaption -

caption of the 'add' button.

capture -

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.

deleteCaption -

caption of the 'delete' button.

field -

Used for the data binding.

hasHeader -

For each item, add a caption from descriptor.getDisplayName(). This also activates drag&drop (where the header is a grip), and help text support.

honorOrder -

If true, insert new addition by default to their 'desired' location, which is the order induced by the descriptors.

menuAlign -

Menu alignment against the button. Defaults to tl-bl

oneEach -

If true, only allow up to one instance per descriptor.

targetType -

the type for which descriptors will be configured. Defaults to ${it.class} (optional)

This tag does not accept any child elements/text.

repeatableProperty

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:block>
          <div align="right">
            <f:repeatableDeleteButton />
          </div>
        </f:block>
        

Due to a bug in Stapler data binding the model elements are only set if they consist of one or more values. If all values have been removed in the user interface (i.e. the associated form is empty), then the setter is not invoked anymore. As a workaround, you need to override the corresponding configure method and clear the model property manually before invoking the data binding. See warnings-ng-plugin PR#266.

Attribute Name Type Description
add -

If specified, this text will replace the standard "Add" text.

default -

The default value to use for this collection when 'instancefield' is null.

enableTopButton -

true if a new Add button, for adding new copy of repeatable item, should be displayed above repeatable form. Display of top button depends also on number of items. If there is no item, only one button is displayed. When at least one item is present, there are two buttons displayed (only when enableTopButton is true). One above and one below. Top button adds item on top of repeatable form. Bottom button adds item on the bottom of repeatable form.

field -

Used for the data binding.

header -

For each item, add this header. This also activates drag&drop (where the header is a grip).

minimum -

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.

noAddButton -

true if the default 'add' button (that adds a new copy) shouldn't be displayed. When you use this attribute,

rowSet

Adds @nameRef to all table rows inside this tag, so that when the form is submitted, it gets grouped in one JSON object.

Attribute Name Type Description
name -

if the group head is not available outside, use this attribute to specify the name. @name and @ref are mutually exclusive.

ref -

id of the thing that serves as the group head, if that's available separately

secretTextarea

Enhanced version of <f:textarea/> for editing multi-line secrets.

Example usage:

<j:jelly xmlns:j="jelly:core" xmlns:f="/lib/form">
    <f:entry title="Secret" field="secret">
        <f:secretTextarea/>
    </f:entry>
    <f:entry title="Secret 2">
        <f:secretTextarea field="secret2"/>
    </f:entry>
    <f:entry title="Another Secret">
        <f:secretTextarea name="foo" value="${it.foo}"/>
    </f:entry>
</j:jelly>

Attribute Name Type Description
field -

Used for databinding. Must be compatible with hudson.util.Secret for round-trip ciphertext.

name -

Name to use for form input name. Calculated from @field by default.

placeholder -

Placeholder text for input field when displayed.

value -

Value of the secret. Calculated from instance@field by default. This value must be of type hudson.util.Secret. The value will be encrypted when sent to the client if the client has Item.CONFIGURE permissions.

This tag does not accept any child elements/text.

section

Section header in the form table.

Attribute Name Type Description
icon -

Optional attribute to set an icon for the section, this is only visible when using section-to-sidebar-items.js

name -

Optional attribute to create a JSON object from this section.

title -

The section header text. If null is given, the entire <f:section> tag becomes no-op.

select

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.

Attribute Name Type Description
checkMessage -

Override the default error message when client-side validation fails, as with clazz="required", etc.

checkMethod String

Specify 'get' (must be lowercase) to change the HTTP method used for the AJAX requests to @checkUrl from a POST to a GET. If any other value is specified then requests will use POST. The historical default was GET and 'post' had to be specified to change that, but this was changed in Jenkins 2.285.

checkUrl -

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.

clazz -

Additional CSS classes that the control gets.

default -

The default value of the text box, in case both @value is and 'instancefield' is null.

field -

Used for databinding.

This tag does not accept any child elements/text.

slave-mode

A listbox for choosing the agent's usage.

Attribute Name Type Description
name -

Name of the <select> element.

node -

Node object.

This tag does not accept any child elements/text.

submit

Submit button. This should be always used instead of the plain <button> tag.

Attribute Name Type Description
clazz -
icon -

@since 2.411

id -

If specified the ID of the button.

@since 2.376

name -

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.

primary -

Sets whether this button is a primary button or not. Defaults to true.

@since 2.376

value (required) -

The text of the submit button, defaults to 'Submit' It's recommended to be more descriptive when possible, e.g. 'Create', 'Next'

This tag does not accept any child elements/text.

textarea

<textarea> tag on steroids. The textarea will be rendered to fit the content. It also gets the resize handle.

Attribute Name Type Description
checkMessage -

Override the default error message when client-side validation fails, as with clazz="required", etc.

checkMethod String

Specify 'get' (must be lowercase) to change the HTTP method used for the AJAX requests to @checkUrl from a POST to a GET. If any other value is specified then requests will use POST. The historical default was GET and 'post' had to be specified to change that, but this was changed in Jenkins 2.285.

checkUrl -

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.

codemirror-config -

Specifies additional key/value pairs in the JSON format (except the start and end bracket) to be passed as CodeMirror option object.

codemirror-mode -

Turns this text area into CodeMirror-assisted code editing text area. This attribute specifies the mode of CodeMirror, such as "text/x-java". See https://codemirror.net/ for more details.

default -

The default value of the text box, in case both @value is and 'instancefield' is null.

field -

Used for databinding. TBD.

name -

This becomes @name of the <textarea> tag. If @field is specified, this value is inferred from it.

previewEndpoint -

If specified, this text area has preview feature. The previewEndpoint is used to obtain formatted html.

value -

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.

This tag does not accept any child elements/text.

textbox

Generates an input field to be used inside <f:entry/>

For a read only input set <j:set var="readOnlyMode" value="true"/> inside your entry tag See https://www.jenkins.io/doc/developer/views/read-only/#enabling-read-only-view-support

Attribute Name Type Description
autoCompleteDelimChar -

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.

autoCompleteField -

Used for determining the autocomplete URL. If @field is specified, that will be used for this.

autoCompleteUrl -

Url to use for auto-completion

If @field is specified, this will be inferred automatically, which is the recommended approach.

checkDependsOn -

Fields to be sent during form validation.

If @field is specified, this will be inferred automatically, which is the recommended approach.

checkMessage -

Override the default error message when client-side validation fails, as with clazz="required", etc.

checkMethod String

Specify 'get' (must be lowercase) to change the HTTP method used for the AJAX requests to @checkUrl from a POST to a GET. If any other value is specified then requests will use POST. The historical default was GET and 'post' had to be specified to change that, but this was changed in Jenkins 2.285.

checkUrl -

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.

clazz -

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").

default -

The default value of the text box, in case both @value is and 'instancefield' is null.

field -

Used for databinding. TBD.

name -

This becomes @name of the <input> tag. If @field is specified, this value is inferred from it.

placeholder -

Placeholder text for the text box

value -

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.

This tag does not accept any child elements/text.

toggleSwitch

<input type="checkbox"> tag that takes true/false for @checked, which is more Jelly friendly.

Attribute Name Type Description
checked -
checkedTitle -

If specified, this title will be used when the toggle switch is checked - otherwise the title attribute will be used for both states

class -
default -

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.

field -

Used for databinding. TBD.

id -
invertLabel -

Move the label of the toggle switch to the opposite side

json -

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.

name -
title -

If specified, this text will follow the toggle switch

tooltip -

Used as tooltip of the checkbox, and, if a title is specified, of the title

value -

This tag does not accept any child elements/text.

validateButton

See https://www.jenkins.io/doc/developer/forms/jelly-form-controls/ for the reference.

Attribute Name Type Description
clazz -

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").

method (required) -

Server-side method that handles the validation. For example, if this is 'foo', you need "doFoo" on your descriptor class.

progress -

Caption of the text shown while the AJAX call is in progress. For example, "checking..."

title (required) -

Caption of the validate button. Should be internationalized.

with -

','-separated list of fields that are sent to the server.

This tag does not accept any child elements/text.

withCustomDescriptorByName

Execute the body with a temporary currentDescriptorByNameUrl value

Attribute Name Type Description
value (required) -

/lib/hudson

/lib/hudson

This tag library is also available as an XML Schema

Tag Name Description
abstractItemLink

Displays a link when given an AbstractItem. It is assumed that that Abstract Item is passed in ${it}

actions

Shows a list of tasks.

aggregated-failed-tests

DEPRECATED

artifactList

Generates a listing of the build artifacts. Depending on the size of the artifact, this will either produce a list or a link to the directory view.

ballColorTd

Display the ball in a TD.

buildCaption
buildEnvVar

Renders a help entry for one environment variable. See EnvironmentContributor. The body of this tag renders the content.

buildHealth
buildLink

Generates a link to a build.

buildListTable

Creates a table of builds.

buildProgressBar

Progress bar for a build in progress.

buildRangeLink
buildStatusSummary
editTypeIcon
editableDescription

Renders ${it.description} and then allow it to be editable in place, if the current user has the specified permission.

executors

Displays the status of executors.

failed-test

DEPRECATED

help

Displays a help button

iconSize
jobLink

Generates a link to a job.

listScmBrowsers

List browser SCMs

logRecords

Displays a list of log records.

node

Displays a link to a node.

progressBar
progressiveText
projectView

Renders a list of jobs and their key information.

projectViewRow
propertyTable

Display sortable table of properties.

queue

Displays the build queue as <l:pane>

rssBar
rssBar-with-iconSize

Deprecated since 1.345: use <t:iconSize><t:rssBar/></t:iconSize>

scriptConsole
setIconSize
summary

Displays a link with a large icon. Used in the project top page.

test-result

DEPRECATED

thirdPartyLicenses

abstractItemLink

Displays a link when given an AbstractItem. It is assumed that that Abstract Item is passed in ${it}

This tag does not accept any child elements/text.

actions

Shows a list of tasks.

Attribute Name Type Description
actions -

List of actions. Defaults to "it.allActions ?: it.actions"

This tag does not accept any child elements/text.

aggregated-failed-tests

DEPRECATED

This tag does not accept any child elements/text.

artifactList

Generates a listing of the build artifacts. Depending on the size of the artifact, this will either produce a list or a link to the directory view.

Attribute Name Type Description
baseURL -

If the hyperlink to artifacts are at another URL, specify the prefix.

build (required) hudson.model.Build

Build object for which the artifacts are displayed

caption (required) -

Human readable title text

This tag does not accept any child elements/text.

ballColorTd

Display the ball in a TD.

Attribute Name Type Description
iconSizeClass -

Specifies the size of the icon. If unspecified, it inherits from the nearest setting in the ancestor call tree. Possible values are "icon-sm" (16x16), "icon-md" (24x24), "icon-lg" (32x32), "icon-xlg" (48x48)

it hudson.model.BallColor

Color of the ball or null to skip drawing.

style -

Additional CSS styles to apply.

This tag does not accept any child elements/text.

buildCaption

buildEnvVar

Renders a help entry for one environment variable. See EnvironmentContributor. The body of this tag renders the content.

Attribute Name Type Description
name (required) -

Name of the environment variable.

buildHealth

This tag does not accept any child elements/text.

buildLink

Generates a link to a build.

Attribute Name Type Description
href String

Link target. If missing, the top page of the build.

job hudson.model.Job

Job object to be displayed. Can be omitted if you don't want to link.

jobName String

Name of the job. Can be omitted if you don't want to show a name.

number (required) int

Build number to link to.

This tag does not accept any child elements/text.

buildListTable

Creates a table of builds.

Attribute Name Type Description
builds (required) -

A collection of builds to be displayed.

This tag does not accept any child elements/text.

buildProgressBar

Progress bar for a build in progress.

Attribute Name Type Description
build (required) hudson.model.Queue.Executable

Build in progress. Must have a url property.

executor -

Executor that's carrying out the build. If null, defaults to "build.executor"

This tag does not accept any child elements/text.

buildRangeLink

This tag does not accept any child elements/text.

buildStatusSummary

This tag does not accept any child elements/text.

editTypeIcon

This tag does not accept any child elements/text.

editableDescription

Renders ${it.description} and then allow it to be editable in place, if the current user has the specified permission.

Attribute Name Type Description
description -

Optional value of the description. If not specified, will use '${it.description}'.

permission (required) -

If the current user doesn't have this permission, the description is not editable.

submissionUrl -

Optional submission URL. If not specified, will use 'submitDescription'.

This tag does not accept any child elements/text.

executors

Displays the status of executors.

Attribute Name Type Description
computers -

If specified, this is the list of computers whose executors are rendered. If omitted, all the computers in the system will be rendered.

This tag does not accept any child elements/text.

failed-test

DEPRECATED

This tag does not accept any child elements/text.

help

Displays a help button

Attribute Name Type Description
href (required) -

Destination of the help icon's link

tooltip -

The tooltip to display

This tag does not accept any child elements/text.

iconSize

jobLink

Generates a link to a job.

Attribute Name Type Description
job (required) hudson.model.Job

Job object to be displayed.

This tag does not accept any child elements/text.

listScmBrowsers

List browser SCMs

Attribute Name Type Description
name (required) -

form field name.

This tag does not accept any child elements/text.

logRecords

Displays a list of log records.

Attribute Name Type Description
logRecords (required) java.util.Collection<java.util.logging.LogRecord>

Records to be displayed (assumed to be in reverse chronological order).

This tag does not accept any child elements/text.

node

Displays a link to a node.

Attribute Name Type Description
value (required) Node
valueStr String

This tag does not accept any child elements/text.

progressBar

This tag does not accept any child elements/text.

progressiveText

This tag does not accept any child elements/text.

projectView

Renders a list of jobs and their key information.

Attribute Name Type Description
columnExtensions Collection<hudson.views.ListViewColumn>

List view columns to render. If omitted, the default ones from ListView.getDefaultColumns() are used.

indenter hudson.Indenter

Optional Indenter instance used to indent items.

itemGroup hudson.model.ItemGroup

The containing group, for purposes of name calculation.

jobBaseUrl String

Deprecated. Using this attribute has no effect.

jobs (required) -

Items to show.

showViewTabs boolean

If the caller rendered a view tabes, set this attribute so that CSS is adjusted accordingly.

useFullName boolean

May be interpreted by columns to display the full name of a job.

views Collection<View>

If non-null, render nested views.

projectViewRow

This tag does not accept any child elements/text.

propertyTable

Display sortable table of properties.

Attribute Name Type Description
items (required) -

A Map object that gets rendered as a table.

sensitive -

Set to true if the information shown in the table is sensitive and should be hidden by default. Since 2.385.

This tag does not accept any child elements/text.

queue

Displays the build queue as <l:pane>

Attribute Name Type Description
filtered -

Indicates that the queue has been filtered, i.e. might not show all items.

items (required) -

Queue items to be displayed. Normally you should specify ${app.queue.items}, but for example you can specify a sublist after some filtering to narrow down the list.

This tag does not accept any child elements/text.

rssBar

This tag does not accept any child elements/text.

rssBar-with-iconSize

Deprecated since 1.345: use <t:iconSize><t:rssBar/></t:iconSize>

This tag does not accept any child elements/text.

scriptConsole

setIconSize

This tag does not accept any child elements/text.

summary

Displays a link with a large icon. Used in the project top page.

Attribute Name Type Description
href -

where the summary icon links to.

icon (required) -

Supports Jenkins Symbols (e.g. 'symbol-search') Supports path to bitmap image (e.g. '/plugin/foo/abc.gif') Supports icon class specification (e.g. 'icon-help icon-sm', 'icon-blue icon-md', 'icon-blue-anime icon-xlg')

iconOnly boolean

if true, hyperlink will only cover the icon, not the body.

permission hudson.security.Permission

permission object. If specified, the link will be displayed only if you have a permission

test-result

DEPRECATED

This tag does not accept any child elements/text.

thirdPartyLicenses

/lib/test

/lib/test

This tag library is also available as an XML Schema

Tag Name Description
bar

bar

This tag does not accept any child elements/text.

/lib/hudson/project

Tag files used in project pages

This tag library is also available as an XML Schema

Tag Name Description
build-permalink
config-assignedLabel
config-blockWhenDownstreamBuilding
config-blockWhenUpstreamBuilding
config-buildWrappers
config-builders
config-concurrentBuild
config-customWorkspace
config-disableBuild

Configuration entry for disabling a project; applies to ParameterizedJob

config-publishers

Deprecated as of 1.463. Use <config-publishers2> and update your code to do publishers.rebuildHetero(req, json, Publisher.all(), "publisher");

config-publishers2
config-quietPeriod
config-retryCount
config-scm
config-trigger
config-upstream-pseudo-trigger

Deprecated; empty. See ReverseBuildTrigger.

configurable
console-link
makeDisabled
projectActionFloatingBox
upstream-downstream

build-permalink

This tag does not accept any child elements/text.

config-assignedLabel

This tag does not accept any child elements/text.

config-blockWhenDownstreamBuilding

This tag does not accept any child elements/text.

config-blockWhenUpstreamBuilding

This tag does not accept any child elements/text.

config-buildWrappers

This tag does not accept any child elements/text.

config-builders

This tag does not accept any child elements/text.

config-concurrentBuild

This tag does not accept any child elements/text.

config-customWorkspace

This tag does not accept any child elements/text.

config-disableBuild

Configuration entry for disabling a project; applies to ParameterizedJob

Attribute Name Type Description
tooltip -

Replaces the default tooltip for the toggle switch

This tag does not accept any child elements/text.

config-publishers

Deprecated as of 1.463. Use <config-publishers2> and update your code to do publishers.rebuildHetero(req, json, Publisher.all(), "publisher");

This tag does not accept any child elements/text.

config-publishers2

This tag does not accept any child elements/text.

config-quietPeriod

This tag does not accept any child elements/text.

config-retryCount

This tag does not accept any child elements/text.

config-scm

This tag does not accept any child elements/text.

config-trigger

config-upstream-pseudo-trigger

Deprecated; empty. See ReverseBuildTrigger.

This tag does not accept any child elements/text.

configurable

This tag does not accept any child elements/text.

console-link

This tag does not accept any child elements/text.

makeDisabled

This tag does not accept any child elements/text.

projectActionFloatingBox

This tag does not accept any child elements/text.

upstream-downstream

This tag does not accept any child elements/text.

/lib/layout

Tag library that defines the basic layouts of Jenkins pages.

This tag library is also available as an XML Schema

Tag Name Description
ajax

Sets up the same 'global' variables that the l:layout tag does for content loaded by AJAX scripts.

app-bar

Generates a row containing the page title and an optional set of controls

breadcrumb

Used inside <l:layout> to render additional breadcrumb items.

breadcrumbBar

Generates the bar that shows breadcrumbs, along with its associated dynamic behaviours. This tag is used by l:layout and not expected to be used by anyone else, but it's written as separate tag for better readability of code.

To render additional breadcrumb items (for example to provide in-page navigations), use the <l:breadcrumb> tag.

breakable

Send escaped value to output decorated to be safely broken into lines when necessary @since 1.517

confirmationLink

Produces a hyperlink which when clicked first asks for confirmation, then goes to that URL if confirmed. The body is displayed as the link text. @since 1.512

copyButton

Button that copies text into the user's clipboard upon click

delete

Creates a delete link with confirmation and trashcan icon in the left navigation pane of Jenkins. Requires that the target has implemented the doDoDelete method.

@since 2.415

hasAdministerOrManage
hasPermission

Renders the body only if the current user has the specified permission

header

Header portion of the HTML page, that gets rendered into the <head> tag. Multiple <l:header> elements can be specified, and can even come after <l:main-panel>.

This tag can be placed inside <l:layout>.

helpIcon

Outputs a help icon

The help link is rendered as an SVG with an (?) icon.

@since 2.234

icon

@since 1.576

isAdmin
isAdminOrTest

Deprecated, do not use.

layout

Outer-most tag for a normal (non-AJAX) HTML rendering. This is used with nested <header>, <side-panel>, and <main-panel> to form Jenkins's basic HTML layout.

main-panel

Generates the body as the main content part of a Jenkins page.

notice
overflowButton
pageHeader

Generates the page header, along with its associated dynamic behaviours. This tag is used by l:layout and not expected to be used by anyone else, but it's written as separate tag for better readability of code.

pane

Used in the <l:side-panel> to draw a box with a title.

The box is drawn as a table, and the body of this tag is expected to draw a series of <TR>s to fill in the contents of the box.

progressAnimation

Display a CSS animation for progressive logging. This tag supersedes spinner.gif and is a drop in replacement:

From

<img src="${imagesURL}/spinner.gif" alt=""/>

to

<l:progressAnimation/>

@since 2.320

progressiveRendering
renderOnDemand
rightspace

Creates a space for the right-hand side of the page. This sticks to the right of the page even when the content overflows.

rowSelectionController

Controls checkbox selections in tables

search-bar

Creates a search input

@since 2.369

side-panel

Generates a left side content as part of a Jenkins page. Typically known as two-column or left-side + main-content layouts

spinner

Customizable spinner component

stopButton

Creates a clickable "Stop" button.

svgIcon

Opinionated helper to use icons via <svg> tags. Can be used by passing a href or a body:

        # <l:svgIcon href="/path/to/my/sprite.svg#my-icon" />
        # <l:svgIcon><path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"></path></l:svgIcon>
        

@since 2.222

tab
tabBar
tabNewItem
tabPane

@since 2.385

task

This tag inside <l:tasks> tag renders the left navigation bar of Jenkins. Each <task> tag gets an icon and link.

tasks
userExperimentalFlag

Retrieve the value of a given experimental flag for the current user.

view

Declares a view as dispatchable. Views that do not use this tag or another tag that invokes this are considered fragment views and are not dispatchable.

yui

Load Yahoo UI module.

ajax

Sets up the same 'global' variables that the l:layout tag does for content loaded by AJAX scripts.

Attribute Name Type Description
contentType -

Content-type of the response page. This will be ignored if this tag is encountered while evaluating a page that has called l:layout tag.

app-bar

Generates a row containing the page title and an optional set of controls

Attribute Name Type Description
headingLevel -

Defaults to h1

title (required) -

The title for the application bar

breadcrumb

Used inside <l:layout> to render additional breadcrumb items.

Attribute Name Type Description
hasMenu -

If true, this breadcrumb item will include a '⌄' symbol to display a dropdown menu with items from the '{breadcrumb.href}/contextMenu' path. Since 2.361.

href -

URL that the breadcrumb item links to. Can be omitted.

id -

If specified, this ID will be assigned to the LI element. This is useful for programmatically adding the context menu

title (required) -

Display name of the breadcrumb.

This tag does not accept any child elements/text.

breadcrumbBar

Generates the bar that shows breadcrumbs, along with its associated dynamic behaviours. This tag is used by l:layout and not expected to be used by anyone else, but it's written as separate tag for better readability of code.

To render additional breadcrumb items (for example to provide in-page navigations), use the <l:breadcrumb> tag.

breakable

Send escaped value to output decorated to be safely broken into lines when necessary @since 1.517

Attribute Name Type Description
value (required) -

Unescaped value to output

This tag does not accept any child elements/text.

confirmationLink

Produces a hyperlink which when clicked first asks for confirmation, then goes to that URL if confirmed. The body is displayed as the link text. @since 1.512

Attribute Name Type Description
class -

A CSS class to use to style the link.

destructive boolean

Show a red confirmation button

href (required) -

The URL to go to.

message (required) -

The confirmation dialog message.

post boolean

Use POST rather than GET (recommended).

title -

The title to show in the confirmation dialog

copyButton

Button that copies text into the user's clipboard upon click

Attribute Name Type Description
clazz -

Additional CSS class names

iconOnly -

Hides the background plate of the button

message -

Confirmation message to be shown once the text is copied.

text (required) -

Text to be copied into the clipboard.

tooltip -

Tooltip of the button.

This tag does not accept any child elements/text.

delete

Creates a delete link with confirmation and trashcan icon in the left navigation pane of Jenkins. Requires that the target has implemented the doDoDelete method.

@since 2.415

Attribute Name Type Description
message -

Message to use for confirmation, if requested; defaults to title.

permission -

If specified, the link will be only displayed when the current user has the specified permission against the "it" object.

This is useful for showing links to restricted pages, as showing them to unprivileged users don't make sense.

If both permission and permissions is set, then permissions will be used

permissions -

If specified, the link will be only displayed when the current user has one or more of the specified permissions against the "it" object.

If both permission and permissions is set, then permissions will be used

title (required) -

Human readable text that follows the icon.

urlPrefix -

Calls the ${urlPrefix}/doDelete page

This tag does not accept any child elements/text.

hasAdministerOrManage

hasPermission

Renders the body only if the current user has the specified permission

Attribute Name Type Description
it -

By default it will reuse the current context. If the provided value does not inherit from hudson.security.AccessControlled, the tag will look for the first ancestor satisfying the condition. The hasPermission will be performed against that value.

permission (required) hudson.security.Permission

permission object to check. If this is null, the body will be also rendered.

header

Header portion of the HTML page, that gets rendered into the <head> tag. Multiple <l:header> elements can be specified, and can even come after <l:main-panel>.

This tag can be placed inside <l:layout>.

helpIcon

Outputs a help icon

The help link is rendered as an SVG with an (?) icon.

@since 2.234

Attribute Name Type Description
class -

Class name to apply

iconSize -

Icon size, available are: small, medium, large, xlarge

tooltip -

The tooltip to display

This tag does not accept any child elements/text.

icon

@since 1.576

Attribute Name Type Description
alt -

alt, adds invisible text suitable for screen-readers for symbols, sets the alt attribute for normal images

class -

The icon class specification e.g. 'icon-help icon-sm', 'icon-blue icon-md', 'icon-blue-anime icon-xlg'.

htmlTooltip -

Tooltip but with HTML support. Make sure to call h.htmlAttributeEscape on all user-specified parts of the value to prevent cross-site scripting. Use 'tooltip' if you don't need to pass HTML.

id -

ID of the icon element. Since 2.360.

onclick (deprecated) -

onclick handler. Deprecated; assign an ID and look up the element that way to attach event handlers.

src -

Icon source Supports Jenkins Symbols (e.g. 'symbol-search') Supports path to bitmap image Only relevant if the 'class' attribute is NOT specified.

style -

style

title (deprecated) -

title, deprecated use tooltip instead, or htmlTooltip if you intend to pass HTML.

tooltip -

Adds a tooltip to the icon, ignores HTML except 'br' tags (but '\n' should be preferred for line breaks).

This tag does not accept any child elements/text.

isAdmin

isAdminOrTest

Deprecated, do not use.

layout

Outer-most tag for a normal (non-AJAX) HTML rendering. This is used with nested <header>, <side-panel>, and <main-panel> to form Jenkins's basic HTML layout.

Attribute Name Type Description
css (deprecated) -

specify path that starts from "/" for loading additional CSS stylesheet. path is interpreted as relative to the context root. e.g.,

<l:layout css="/plugin/mysuperplugin/css/myneatstyle.css">

This was originally added to allow plugins to load their stylesheets, but the use of the attribute is discouraged now. plugins should now do so by inserting <style> elements and/or <script> elements in <l:header/> tag.

nogrid -

Do not include Bootstrap 3 grid. When a plugin wants to use a more recent version of Bootstrap then the bundled grid will cause conflicts.

norefresh -

Deprecated: Used to disable auto refresh for a page. The feature has been removed.

permission -

If given, this page is only made available to users who have the specified permission. (The permission will be checked against the "it" object.)

permissions -

If given, this page is made available to users who have one or more of the specified permissions. (The permissions will be checked against the "it" object.)

title (required) -

Title of the HTML page. Rendered into <title> tag.

type -

Available values: two-column (by default), one-column (full-width size) or full-screen (since 2.53).

main-panel

Generates the body as the main content part of a Jenkins page.

notice

Attribute Name Type Description
icon (required) -

Sets the icon for the notice. Supports Jenkins Symbols and regular images.

text (required) -

Sets the text for the notice. HTML isn't supported.

This tag does not accept any child elements/text.

overflowButton

Attribute Name Type Description
clazz -

Additional CSS class names for the button

icon -

Optional icon to be used for the button, defaults to three dots

id -

Optional ID for the button

text -

Optional text to be displayed on the button

tooltip -

Optional tooltip of the button, defaults to 'More actions'

pageHeader

Generates the page header, along with its associated dynamic behaviours. This tag is used by l:layout and not expected to be used by anyone else, but it's written as separate tag for better readability of code.

Attribute Name Type Description
logoAlt (required) -

Alt text for the logo

logout (required) -

Text for the logout link

searchHelpUrl (required) -

Link value for the help icon on the search box

searchPlaceholder (required) -

Placeholder text for the search input

title (required) -

Page title and title attribute for the logo

This tag does not accept any child elements/text.

pane

Used in the <l:side-panel> to draw a box with a title.

The box is drawn as a table, and the body of this tag is expected to draw a series of <TR>s to fill in the contents of the box.

Attribute Name Type Description
class -

Pane table class specification.

collapsedText -

Text shown instead of the regular pane content when it is collapsed.

footer -

Footer of the box. Can include HTML.

id -

@id of the table, if specified. Required for a pane to be collapsible.

title (required) -

Title of the box. Can include HTML.

width (required) -

Specify the number of columns in the table (so that the title can stretch to the entire table width.

progressAnimation

Display a CSS animation for progressive logging. This tag supersedes spinner.gif and is a drop in replacement:

From

<img src="${imagesURL}/spinner.gif" alt=""/>

to

<l:progressAnimation/>

@since 2.320

This tag does not accept any child elements/text.

progressiveRendering

Attribute Name Type Description
callback (required) -

Name of a global scope JavaScript function that takes one JSON-valued parameter which renders results as they come.

handler (required) -

Instance of jenkins.util.ProgressiveRendering.

tooltip -

Optional tooltip for progress bar.

This tag does not accept any child elements/text.

renderOnDemand

Attribute Name Type Description
capture -

','-separated list of variables to capture and make available when later evaluating the body.

clazz -

Additional CSS class names, so that you can discover this tag more easily from your JavaScript.

tag -

Place holder HTML tag. By default it's DIV, but depending on where this is used, you might need other tags (e.g., inside a table.)

This tag does not accept any child elements/text.

rightspace

Creates a space for the right-hand side of the page. This sticks to the right of the page even when the content overflows.

rowSelectionController

Controls checkbox selections in tables

search-bar

Creates a search input

@since 2.369

Attribute Name Type Description
autofocus -
clazz -
enabled -

Defaults to true. Sets whether the search bar is enabled or not.

hasKeyboardShortcut -

If false the default keyboard shortcut for the input is disabled. Defaults to true.

id -
placeholder -
value -

This tag does not accept any child elements/text.

side-panel

Generates a left side content as part of a Jenkins page. Typically known as two-column or left-side + main-content layouts

Attribute Name Type Description
sticky -

Make the side panel sticky. Should not be used on pages that include widgets in the sidepanel and when plugins can add their own tasks, so the number of tasks is not fixed.

spinner

Customizable spinner component

Attribute Name Type Description
text -

Text to use alongside the spinner

This tag does not accept any child elements/text.

stopButton

Creates a clickable "Stop" button.

Attribute Name Type Description
alt (required) -

Alt text for image.

confirm -

If defined, the user will be asked for confirmation first, and the value will be used as question.

href (required) -

Link target. Relative to the current page.

This tag does not accept any child elements/text.

svgIcon

Opinionated helper to use icons via <svg> tags. Can be used by passing a href or a body:

        # <l:svgIcon href="/path/to/my/sprite.svg#my-icon" />
        # <l:svgIcon><path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"></path></l:svgIcon>
        

@since 2.222

Attribute Name Type Description
ariaHidden -

aria-hidden

class -

Extra CSS classes passed to the icon. Currently only the 'svg-icon' class is applied by default.

focusable -

Whether the icon can receive keyboard focus. Possible values 'true' or 'false'

href -

Href of the 'use' tag. Normally path to a sprite plus an icon id

id -

ID of the icon element. Since 2.289.

onclick (deprecated) -

onclick handler. Deprecated; assign an ID and look up the element that way to attach event handlers.

style -

style

tooltip -

tooltip

viewBox -

viewbox (default 0 0 24 24)

tab

Attribute Name Type Description
active java.lang.Boolean

Whether the tab is active or not

href (required) -

The url of the tab

name (required) -

The name of the tab

title -

The title of the tab

This tag does not accept any child elements/text.

tabBar

Attribute Name Type Description
class -

'tabBarFrame' class specification. This will allow styling.

showBaseline -

Set to true to show the baseline

tabNewItem

Attribute Name Type Description
href (required) -

The url of the tab

title -

The title of the tab

This tag does not accept any child elements/text.

tabPane

@since 2.385

Attribute Name Type Description
title (required) -

The title of the tab

task

This tag inside <l:tasks> tag renders the left navigation bar of Jenkins. Each <task> tag gets an icon and link.

Attribute Name Type Description
badge jenkins.management.Badge

If set, displays the value as a small badge on the right side of the sidepanel item. (since 2.401)

confirmationMessage -

Message to use for confirmation, if requested; defaults to title. (since 1.512)

contextMenu boolean

If "false", remove this item from the context menu.

data-callback -

Name of a global function to call when clicked. It will be called with an element (currently 'a') as first argument, and the event as second argument. You can specify further data-* attributes to customize behavior, those will be defined on the element passed as first argument. See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset for more information about these attributes. Has no effect if you specify the 'requiresConfirmation' attribute. Has no effect on menu items showing in context menus, only 'href', 'post', and 'requiresConfirmation' attributes substantially change behavior there. Set 'contextMenu' to 'false' to remove this task from those menus.

destructive boolean

Show red confirmation button.

enabled -

If specified, then this controls whether the task is enabled or not.

href (required) -

Link target. Relative to the current page.

icon (required) -

URL to an icon image, or the icon class specification. If using an image URL, the image should be 24x24 in size and relative to the context path of Hudson.

Common values include:

# "symbol-search" / "symbol-terminal" / "symbol-settings" - use a Jenkins Symbol as the icon for your task # "icon-folder icon-md" is an example of using a class spec for a medium folder icon # "images/24x24/..." then points to the stock icon resources # "plugin/foobar/abc/def.png" that points to "src/main/webapp/abc/def.png" in your plugin resources

onclick (deprecated) -

Onclick inline JS handler. Deprecated, specify data-callback attribute instead.

permission -

If specified, the link will be only displayed when the current user has the specified permission against the "it" object.

This is useful for showing links to restricted pages, as showing them to unprivileged users don't make sense.

If both permission and permissions is set, then permissions will be used

permissions -

If specified, the link will be only displayed when the current user has one or more of the specified permissions against the "it" object.

If both permission and permissions is set, then permissions will be used

post boolean

If true, send a POST rather than a GET request. (onclick supersedes this except in the context menu.) (since 1.504)

requiresConfirmation boolean

If true, require confirmation before clicking. Generally used with post="true". (onclick supersedes this except in the context menu.) (since 1.512)

title (required) -

Human readable text that follows the icon.

tasks

userExperimentalFlag

Retrieve the value of a given experimental flag for the current user.

Attribute Name Type Description
flagClassName java.lang.String

The canonical class name of the flag

var java.lang.String

The variable that receives the value of the flag for the current user.

This tag does not accept any child elements/text.

view

Declares a view as dispatchable. Views that do not use this tag or another tag that invokes this are considered fragment views and are not dispatchable.

Attribute Name Type Description
contentType -

HTTP Content-Type header value to use for this view.

yui

Load Yahoo UI module.

Attribute Name Type Description
module (required) -

YUI module name to load.

This tag does not accept any child elements/text.

/lib/hudson/newFromList

These tags provide a higher level primitive for building a form page for creating a new item from a list of descriptors.Used in "create new job" page, for an example.

This tag library is also available as an XML Schema

Tag Name Description
form

Generates a form for creating something out of descriptors by (1) selecting a descriptor and specifying a name. This also presents a copy option. This should be placed inside <l:main-panel>.

form

Generates a form for creating something out of descriptors by (1) selecting a descriptor and specifying a name. This also presents a copy option. This should be placed inside <l:main-panel>.

Attribute Name Type Description
action -

Specify where the form will be submitted to. Defaults to 'createItem'.

checkUrl (required) -

relative URL that point to the check method that validates the new name.

copyTitle -

Caption of the radio button that allows the user to copy from something that already exists.

descriptors (required) -

Collection of Descriptors to be rendered.

nameTitle (required) -

Caption of the text box to receive the name of the newly created item. Something like "Job name"

showCopyOption -

If true, an extra radio button will appear that allows the user to copy from something that already exists. See @copyTitle.

title (required) -

Title for the form

This tag does not accept any child elements/text.