TM toolkit reference

Every event, action, dialog option, and UI component the TM toolkit gives a UI Script, with the identifier each surface takes in code.

TM is the one global object a UI Script talks to. Every function on this page is a method on it, and the autocomplete in the Script Content editor mirrors this reference. A script never touches React or Test Management internals. It registers callbacks with TM, and Test Management calls them at the right moment.

Functions fall into two groups. Events tell you that something happened. Actions change the form, open a dialog, or open a URL.

Surface identifiers

Every event that takes a surface takes it as a string. Use the exact identifier, not the label shown in settings:

Events

Register an event handler at the top level of your script. Test Management calls it when the matching event fires:

This reference names the first callback argument formState. Your callback can name it anything, and the snippets on these pages call it form.

TM.onBeforeSave is the only event that can stop a save. Return the result of TM.blockSave from its callback to block the save. Return nothing and the save proceeds. Calling TM.blockSave without return does nothing, and the save goes through silently. This is the most common mistake in a save rule, and the TM.blockSave section shows the right pattern.

TM.onFieldChange receives the new value first and the previous value second. Both arrive in the same shape the field uses on form, so a system dropdown arrives as an object and a text field arrives as a string. For the name to pass as the first argument, see Fields in UI Scripts.

Actions

Call an action from inside an event handler. Each one changes the form, opens a dialog, or opens a URL:

Three constraints apply across the field actions:

• A field you mark required can no longer be hidden or made read-only.
• TM.setFieldValue takes the value in the field’s own shape. A custom dropdown takes an option object shaped as { value, label }. On the run, plan, and session forms, a text or boolean field takes its value directly, and a structured field renders the value only when the shape matches.
• TM.openUrl opens http and https addresses only. It ignores every other scheme, including javascript:.

TM.blockSave and where its message appears

TM.blockSave(message, fieldName) stops a save and shows message. It works only as a return value from a TM.onBeforeSave callback:

The second argument is optional, and it decides where the message lands:

• Pass a field name that supports an inline error, and the message renders under that field. The form scrolls to the field and focuses it, the same way built-in validation behaves.
• Pass nothing, and the message renders in a message strip on the form.
• Pass a field that does not support an inline error, and the message falls back to the message strip anyway.

Prefer the inline form whenever the rule concerns one field, because the form scrolls to the field that needs fixing. Keep the field-less form for a rule that spans the whole form. For the list of fields that support the inline error, see Fields in UI Scripts.

TM.openDialog

TM.openDialog(config) opens a pop-up and returns a dialog ID. You build the body from TM.ui components rather than HTML, so the dialog matches the rest of Test Management.

Two rules govern dialogs:

• A dialog built from a content tree renders no footer. You put your own TM.ui.Button nodes in the tree.
• A dialog built from a fields list instead of a content tree does render a Submit and Cancel footer, labeled by submitLabel and cancelLabel.

Dialog options

Each key on the config object is optional unless the table says otherwise:

Named inputs arrive in onSubmit on the formData object, keyed by the name you gave each input.

Layout and display components

These components arrange the dialog and show static content:

Inside a TM.ui.Row, each child can set its own width to full, half, third, or quarter.

Input components

Each input needs a name, because that name becomes the key in formData:

A TM.ui.Checkbox stores a boolean and ignores required.

Button action semantics

TM.ui.Button(props, label) takes a variant and an action. Set variant to "primary" for the brand-colored button. Any other value renders a white button. The action value decides what the click does. Only cancel closes the dialog on its own.

A button whose action has no matching TM.onAction handler does nothing. The dialog stays open.

Next steps

• UI Script examples
• Fields in UI Scripts
• Manage UI Scripts
• UI Scripts overview