External JavaScript Extensions

From codebeamer 22.04 (Felicity), external JavaScript and CSS files can be used to extend codebeamer functionality and customize the UI.

The following pages can be extended and customized with extensions:

• Tracker Views
• Tracker Item Views
• Reference selector
• Reports

Using external scripts

The following should apply to custom script files before they can be loaded and used:

• Script files must be located in <codebeamer Installation dir>/repository/config/customization/js before starting codebeamer. If codebeamer is running, changes made to the folder or the script files are not processed until codebeamer is restarted.
• Custom scripts must be wrapped in jQuery's load function.
• externalScripts must be enabled in Application Configuration.

Wrapping external scripts

In order for the DOM to be ready, external scripts have to be wrapped in jQuery's load function, in the following way:

$(window).on('load', function() {
  ...
  <external script>
  ...
});

Application Configuration

Loading external scripts to various codebeamer pages can be enabled or disabled in System Admin ► Application Configuration menu, by adding the following section:

...
"externalScripts" : {
    "enabled" : true
}
...

The default value is false.

For more information about the Application Configuration, see: Application configuration.

Example

This example provides a step-by-step description of using scripts for customizing and extending codebeamer functionality and UI, given that appropriate settings were applied in Application Configuration before. In this example, the page title of the Reports ► New Report page changes color to red and back to white when clicked.

1. Stop codebeamer.
2. Download the following files:
   • script.js
   • style.css
3. Copy the files to <codebeamer Installation dir>/repository/config/customization/js, before starting codebeamer.
4. Start codebeamer.
5. Go to Reports ► New Report page.
6. Click the page title: 'New Report', it should change to red.
7. Click the title again, it should change back to wihte.
8. Console log should display the following message: external script - title clicked.
9. A message with the same text is also recorded in codebeamer log.

Content of files

script.js:

$(window).on('load', function() {

    const msg = "external script - title clicked";

    $( ".page-title" ).click(
      function() {
        $(this).toggleClass( "title-red" );
        console.log(msg);
        codebeamer.MessageLogger.error(msg);
      }
    );

});

style.css:

.title-red {
    color: red !important;
}