Jenkins : Understanding Jelly Tags

Jenkins developers will soon notice that jelly files are made up of many diverse jelly tags, and that jelly files live in many places in the Jenkins source tree. The mapping from jelly tag to jelly file or other implementation is tricky to figure out; this page attempts to explain it.

A Jenkins page usually starts with a jelly page named index.jelly. Let's consider src/main/resources/hudson/model/Job/index.jelly. Here's the first line of jelly:

<j:jelly
   xmlns:j="jelly:core"
   xmlns:st="jelly:stapler"
   xmlns:d="jelly:define"
   xmlns:l="/lib/layout"
   xmlns:t="/lib/hudson"
   xmlns:f="/lib/form"
   xmlns:i="jelly:fmt"
   xmlns:p="/lib/hudson/project">

That tag tells us where to find the jelly files or other implementation of tags in the specified namespace:

xmlns:namespace_name="where to find resources in that namespace"

The path /lib/foo refers to hudson/main/core/src/main/resources/lib/.

Let's look at the rest of index.jelly; I've pulled out a few of the interesting pieces:

   <l:layout .... >
      <st:include page="sidepanel.jelly" />
      <l:main-panel> ...
         <t:editableDescription ... />
         <j:if test="..."> </j:if>
      </l:main-panel>
     </l:layout>
... </j:jelly>

The first tag we encounter is <l:layout>. The "l" tells us to look in "/lib/layout", because that's what was declared in the j:jelly tag:

 xmlns:l="/lib/layout"

I happen to know that /lib/layout means core/src/main/resources/lib/layout/ so to find the source for the l:layout tag, I simply look at core/src/main/resources/lib/layout/layout.jelly.

The next tag we encounter is st:include which declares the st namespace as somehow related to "jelly:stapler". I suspect this is a jelly feature that I don't know about yet; probably it sends us to a stapler jar for the implementation of the include tag.

Let's skip over l:main-panel, which should be clear already, and jump to t:editableDescription. The namespace declaration xmlns:t="/lib/hudson" points us to
core/src/main/resources/lib/hudson/editableDescription.jelly.

Using these simple rules, you can now find the source for jelly tags implemented by Jenkins.