How do I add a page to Jenkins?

Question

I am looking to write a jenkins plugin that lets me add a new link that links to a new page of my creating. I have determined how to create the new link by extending RootAction and I can get it to link to a static resource in the webapp directory. My problem is many fold though. I think I need to use a jelly page because of the nature of action I want to do on this new page of mine and even if I could do what I wanted to with static web content the link pops me out of the jenkins interface to a page only containing my static web content.

What I need to know is, how do you go about creating a brand new page? I have been scowering the JavaDoc looking for an interface and the internet for more documentation on how to write plugins. But the internet seems to be sadly lacking on information pertaining to Jenkins plugin development.

What I want to do is be able to click my new link and have it take me to my new page, still with all the Jenkins navigation and such, and on this new page I am going to have a form for performing some actions on files.

Any help or pointers to documentation I have not found would be greatly appreciated.

Answer 1

As you found, the first step is to extend a RootAction or Action, depending on where you want the page to be located: globally or per-project, respectively.

A simple RootAction:

package my.package;

@Extension
public class MyNewPage implements hudson.model.RootAction
{

    @Override
    public String getDisplayName()
    {
        return "My Custom Page";
    }

    @Override
    public String getIconFileName()
    {
        return (Jenkins.RESOURCE_PATH + "/images/48x48/terminal.png").replaceFirst("^/", "");
    }

    @Override
    public String getUrlName()
    {
        return "my-url"; // the url path
    }
}

Next, add an associated jelly file located at src/main/resources/my/package/MyNewPage/index.jelly

<?jelly escape-by-default='true'?>
<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">
    <l:layout norefresh="true">
        <l:header title="My New Page" />
        <l:main-panel>
            <h1>Put content here</h1>
        </l:main-panel>
    </l:layout>
</j:jelly>

See the jenkins jelly tag reference for more tags. Note that the l:layout tag is completely optional, you don't have to use jenkins tags at all and can instead dump static HTML content in the jelly

Those two files will then be used to render requests for http://localhost:8080/jenkins/my-url

Alternatively, for completely dynamic content, use the stapler library built into jenkins to render arbitrary urls. Here is a silly little example that prints back the url:

public void doDynamic(StaplerRequest req, StaplerResponse resp) throws IOException
{
    resp.setStatus(418);
    resp.getOutputStream().print("I'm a teapot! You requested this path: " + req.getRestOfPath());
}

Just add that method, or any of the stapler methods, to the MyNewPage (or any extension that supports it). It will respond to all urls under http://localhost:8080/jenkins/my-url/*

Some other good references I've found:

• How to extend Jenkins job page with new links and icons
• The build-failure-analyzer plugin source, notably CauseManagement.java