Jenkins Taglib Documentation

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.

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.

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>

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.

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.

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

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.

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.

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.

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.

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

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

This tag does not accept any child elements/text.

form

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

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

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

hetero-radio

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

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

nested

number

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

This tag does not accept any child elements/text.

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.

This tag does not accept any child elements/text.

password

Glorified <input type="password">

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

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

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

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.

repeatableDeleteButton

Delete button for the <repeatable> tag.

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.

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.

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>

This tag does not accept any child elements/text.

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.

This tag does not accept any child elements/text.

slave-mode

A listbox for choosing the agent's usage.

This tag does not accept any child elements/text.

submit

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

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.

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

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.

This tag does not accept any child elements/text.

validateButton

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

This tag does not accept any child elements/text.

withCustomDescriptorByName

Execute the body with a temporary currentDescriptorByNameUrl value

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.

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.

This tag does not accept any child elements/text.

ballColorTd

Display the ball in a TD.

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.

buildHealth

This tag does not accept any child elements/text.

buildLink

Generates a link to a build.

This tag does not accept any child elements/text.

buildListTable

Creates a table of builds.

This tag does not accept any child elements/text.

buildProgressBar

Progress bar for a build in progress.

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.

editDescriptionButton

Renders a button to add/edit the description of an item. Typically used when the button should appear in the app-bar instead of appearing below the description. To be used in combination with `editableDescription`.

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.

This tag does not accept any child elements/text.

executors

Displays the status of executors.

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

This tag does not accept any child elements/text.

iconSize

jobLink

Generates a link to a job.

This tag does not accept any child elements/text.

listScmBrowsers

List browser SCMs

This tag does not accept any child elements/text.

logRecords

Displays a list of log records.

This tag does not accept any child elements/text.

node

Displays a link to a node.

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.

projectViewRow

This tag does not accept any child elements/text.

propertyTable

Display sortable table of properties.

This tag does not accept any child elements/text.

queue

Displays the build queue as <l:pane>

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.

test-result

DEPRECATED

This tag does not accept any child elements/text.

thirdPartyLicenses

bar

This tag does not accept any child elements/text.

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

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.

custom

Allows for custom components inside of dropdowns

Pass HTML as the child of this component to render it inside of a dropdown, e.g.

<dd:custom> <img src="jenkins.svg" /> </dd:custom>

header

Displays a header to visually group items in a dropdown

This tag does not accept any child elements/text.

item

This tag does not accept any child elements/text.

separator

Displays a horizontal line to visually separate items in a dropdown

This tag does not accept any child elements/text.

submenu

Displays the contents as a submenu to a menu item

login

This tag does not accept any child elements/text.

logo

This tag does not accept any child elements/text.

searchbox

This tag does not accept any child elements/text.

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

badge

If a Badge is informed it will be displayed, otherwise nothing is done.

@since 2.445

This tag does not accept any child elements/text.

breadcrumb

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

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

This tag does not accept any child elements/text.

card

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, either or is required.

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

This tag does not accept any child elements/text.

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

This tag does not accept any child elements/text.

icon

@since 1.576

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.

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

main-panel

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

notice

overflowButton

Displays a button which when clicked displays a dropdown of the component's children

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.

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.

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

This tag does not accept any child elements/text.

renderOnDemand

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

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

spinner

Customizable spinner component

This tag does not accept any child elements/text.

stopButton

Creates a clickable "Stop" button.

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

tab

This tag does not accept any child elements/text.

tabBar

tabNewItem

This tag does not accept any child elements/text.

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.

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.

yui

Load Yahoo UI module.

This tag does not accept any child elements/text.

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

This tag does not accept any child elements/text.