How to use optionalBlock in build step's config.jelly

Question

I have problem with creating constructor, which Jenkins can call for some JSON data originating from a Jelly form,. For testing, I created a minimal Jenkins plugin with `mvn hpi:create` and following two custom files: src/main/resources/foo/hyde/jenkins/plugins/OptionalBlockSampleBuilder/config.jelly ```

``` src/main/java/foo/hyde/jenkins/plugins/OptionalBlockSampleBuilder.java ``` package foo.hyde.jenkins.plugins; public class OptionalBlockSampleBuilder extends hudson.tasks.Builder { public final String text; public final boolean enableText; @org.kohsuke.stapler.DataBoundConstructor public OptionalBlockSampleBuilder(String…

Accepted Answer

The hint comes from the JSON data:

```
{
"enableText":{"text":"xx"},
"kind":"foo.hyde.jenkins.plugins.OptionalBlockSampleBuilder",
"stapler-class":"foo.hyde.jenkins.plugins.OptionalBlockSampleBuilder"
}
```

You can see here that `enableText` contains a child property, `text`. That means that the `f:optionalBlock` is actually expecting an encapsulation of all the fields contained within the block -- when the block is checked, you will receive an instance of the encapsulation field class; when it is unchecked, that field will be `null`. To use the `optionalBlock` properly, you would need the `@DataBoundConstructor` to take in a single nullable class instance that encapsulates the entire `optionalBlock`. For example:

```
private String text;

@DataBoundConstructor
public MyClass(EnableTextBlock enableText)
{
    if (enableText != null)
    {
        this.text = enableText.text;
    }
}

public static class EnableTextBlock
{
    private String text;

@DataBoundConstructor
    public EnableTextBlock(String text)
    {
        this.text = text;
    }
}
```

Notice that the `enableText` field in this case is actually an instance of `EnableTextBlock` class, which contains a child property, `text`. That will satisfy the JSON object that is being sent in the form.

Instead, if all you need is a single field that has a checkbox to enable entry of that field, you might want to consider instead using the `f:optionalProperty` tag, which will take care of that single-field encapsulation for you. However, in many cases, the `optionalBlock` is actually needed to configure multiple fields, in which case the encapsulation class--as exampled above--is usually the correct way to go.

The encapsulation class does not have to be a static inner class; it could be a separate class within your package, but the important part is that the `DataBoundConstructor` should take in an argument that matches the JSON structure being passed from the form.

How to use optionalBlock in build step's config.jelly

Solution

Problem