Spice Up Your Jenkins Jobs: Adding Color and Customization with the Active Choices Plugin

Want to make your Jenkins jobs more user-friendly and visually appealing? Tired of the same old default parameter presentation? You can level up your Jenkins game by using the Active Choices plugin to inject custom HTML and JavaScript into your build parameter page. This allows you to dynamically modify the appearance and behavior of your parameters, making them more informative and easier to use. This guide will help you learn how to use the Active Choices plugin, giving you the knowledge to customize your Jenkins job colorful parameter displays.

Why Add Color and Customization to Jenkins Parameters?

Adding color and customized elements to your Jenkins parameters offers several key benefits:

• Improved User Experience: Make critical parameters stand out, guiding users to the right choices.
• Reduced Errors: Clearly differentiate between parameter types, minimizing input mistakes and failed builds.
• Enhanced Information: Display dynamic information alongside parameters, like descriptions that update based on other selections.
• Greater Clarity: With custom HTML added using the Active Choices plugin to inject Javascript code to change the parameter names, the Jenkins job with colorful parameters provides a better user interface.

The Active Choices Plugin: Your Gateway to Customization

The Active Choices plugin for Jenkins provides a powerful way to dynamically generate and control parameter options. It allows you to inject custom HTML (including JavaScript and CSS) into your "Build with Parameters" page. This opens the door to endless possibilities for customizing your Jenkins parameters.

Example: Highlighting a Parameter in Red

Let's look at a simple example of how to use the Active Choices plugin to change the background color of a parameter's label to red. This demo uses Groovy scripting to inject HTML and JavaScript to target the "USERNAME" parameter, highlighting how simple customization can be.

Here's a breakdown of the code:

properties([
    parameters([
        [$class: 'DynamicReferenceParameter',
         name: 'HTML_ADDITIONS',
         choiceType: 'ET_FORMATTED_HTML',
         omitValueField: true,
         description: '',
         script:
             [$class: 'GroovyScript',
              fallbackScript: [classpath: [], sandbox: false, script: ''],
              script: [classpath: [], sandbox: false, script: getHtmlAdditions()]
             ]
        ],
        [$class: 'StringParameterDefinition',
         name: 'USERNAME',
         defaultValue: '',
         description: '',
         trim: true,
        ],
        [$class: 'StringParameterDefinition',
         name: 'GROUP',
         defaultValue: '',
         description: '',
         trim: true,
        ],
    ])
])

def getHtmlAdditions() {
    return """
<style>
</style>
<script type="text/javascript">
jQuery(function() {
    var username = jQuery("input[type=hidden][value=USERNAME]").parents(".tr")
    username.css('background-color', 'red')
})
</script>
"""
}

This snippet does the following:

1. Defines Parameters: It creates an HTML_ADDITIONS parameter using DynamicReferenceParameter to dynamically inject HTML. It also defines USERNAME and GROUP as standard String parameters.
2. Injects HTML/JavaScript: The getHtmlAdditions() function returns an HTML string containing JavaScript code.
3. JavaScript Execution: The JavaScript code uses jQuery to find the table row (.tr) containing the USERNAME parameter and changes its background color to red.

Hiding Parameters with JavaScript

Beyond coloring parameters, you can also use JavaScript to dynamically hide or show parameters based on other user input. For example, the following JavaScript code hides the HTML_ADDITIONS field itself after it executes, presenting a cleaner user experience with only USERNAME and GROUP visible:

jQuery("input[type=hidden][value=HTML_ADDITIONS]").parents(".tr").hide()

Key Considerations

• Security: Exercise caution when using the Active Choices plugin. Ensure that all scripts are from trusted sources to prevent potential security vulnerabilities. Script approvals may be needed per Jenkins security settings.
• JavaScript/CSS Knowledge: A basic understanding of JavaScript and CSS is helpful for complex customizations.
• Testing: Thoroughly test your customizations to ensure they function as expected across different browsers and Jenkins versions.

Conclusion

The Active Choices plugin is a game-changer for making your Jenkins job colorful parameter displays. By leveraging its ability to inject HTML and JavaScript, you can elevate the user experience, reduce errors, and make your Jenkins jobs easier and more efficient to use. Experiment with the Active Choices plugin to create more intuitive and engaging Jenkins pipelines.