Jenkins 3: Text Input & Validation

Our builder UI is progressing: today we will add a text box with nice defaults and add input validation to it.

Jenkins Tutorials

For a list of all jenkins related tutorials see Jenkins Tutorials Overview.

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Step 1: The Text Box

Adding a text box is as simple as adding the checkbox before. Add a new entry to the config.jelly file:

 <f:entry title="Custom build message" field="buildMessage">
  <f:textbox />
 </f:entry>

Make sure you use a unique ID for field. Then add the new field to your builder by adding it to the constructor and create a getter for it:

public class HelloBuilder extends Builder implements SimpleBuildStep {

 private String fBuildMessage;

 @DataBoundConstructor
 public HelloBuilder(boolean failBuild, String buildMessage) {
  fFailBuild = failBuild;
  fBuildMessage = buildMessage;
 }

 @Override
 public void perform(Run<?, ?> run, FilePath workspace, Launcher launcher, TaskListener listener)
   throws InterruptedException, IOException {
  listener.getLogger().println(getBuildMessage());
  
  if (isFailBuild())
   throw new AbortException("Build error forced by plugin settings");
 }

 public String getBuildMessage() {
  return fBuildMessage;
 }
}

All done, give it a try!

Step 2: Default Value

Some example data might help our users when filling out the buid parameters. Therefore lets provide a nice default value. This is done by adding a default attribute to the textbox:

<f:textbox default="${descriptor.getDefaultBuildMessage()}" />

We could have provided the default text directly in the attribute data. Instead we decided to fetch the default dynamically from the Descriptor class. No magic data binding here, so we need to implement the method:

 public static final class Descriptor extends BuildStepDescriptor<Builder> {
  
  public String getDefaultBuildMessage() {
   return "This is a great build";
  }
 }

Step 3: Input Validation

Having no build message would result in an empty log file, which is not what we want. With input validation we can force users to enter some text to the input box. Validation is done by providing a validator in the Descriptor class:

 public static final class Descriptor extends BuildStepDescriptor<Builder> {

  public FormValidation doCheckBuildMessage(@QueryParameter String buildMessage) {
   if (buildMessage.isEmpty())
    return FormValidation.error("Please provide a build message.");
   else if (buildMessage.trim().isEmpty())
    return FormValidation.error("White space is not sufficient for a build message.");
   else
    return FormValidation.ok();
  }
 }

The method name needs to stick to the pattern doCheck<Parameter>. Normally you would only provide the parameter in question to that method (again the parameter name needs to match your field ID) but if needed you could add parameters for other fields of the builder. This comes in handy when parameters depend on each other.