Captialize Cognos Text Prompt Input in Real-Time

There are times when the values in a table we need to filter on are stored as all-caps. If we supply the filter value via a Cognos prompt, we need to convert the input from the prompt to uppercase before we can make the comparison. This is usually done via the Cognos upper() function. A typical filter might look like this:

[Data] = upper(?parameter1?)

There’s nothing wrong with this pattern. However, what if we could convert the input to uppercase as the user types? This approach provides some benefits:

1. The input is already in the proper format for filtering, no need to apply a function at the filter
2. Users become aware of the input format needed over time
3. It’s kind of neat to see the input auto-correct itself

We can use some modest JavaScript, along with the Cognos JavaScript Prompt API, to easily convert input in a text prompt to uppercase in real-time, as the user types.

Let’s get started.

Assumptions

In order to manipulate Cognos prompts in JavaScript we have to be able find them. This is done by referencing the name provided in the ‘Name’ property of the prompt. By default, prompts don’t have a name. You have to manually provide a unique name for each prompt you want to address. The code assumes you have a single text prompt on the page named ‘textPrompt’.

The Code

For those that want to skip the coding, a sample report definition can be downloaded here.

The JavaScript below needs to be added to a HTML item on your prompt page. The HTML item should be placed at the bottom of the prompt page after all other objects.

Let’s take a look at the code:

This pattern is used at some level in every Cognos Prompt API JavaScript. We first get a reference to the report instance using the getReport() function. Using that reference we then call getControlByName() passing in the name we supplied to the prompt to get a reference to the actual prompt object.

Using the prompt object reference, we call the API setValidator() function passing in the name of a function that will handle validation.

The function set as the validator for a Cognos Prompt API object fires every time the prompt value is changed. For a text prompt this occurs after every key press. Even though we aren’t doing validation this time around we can use the validation hook to perform a number of actions when the text prompt changes.

This is the start of the validation function definition. For validation functions Cognos automatically passes in an array containing the existing prompt values. Here we’ve assigned that parameter as ‘values’. Note that with a text prompt there is only one value. Cognos still passes in array, one with only a single element with index 0.

We only want to perform our action if the prompt exists and has at least one value.

We convert the ‘use’ property of the existing value object to uppercase. Note that we have left the ‘display’ property alone. This is because Cognos only evalutates the value of the ‘use’ property when setting or adding a value in a prompt.

Now that we have an updated value object within the ‘values’ array, we can pass it into the Cognos JavaScript API function setValues(). The setValues() function performs two other API functions in succession: clearValues() and addValues(). The prompt is cleared first and then the new contents are added to it resulting in the previous text being replaced with a version converted to uppercase.

All validation functions have to return either true or false. Since we aren’t implementing validation here we simply return true in every case. A more sophisticated function might perform true validation in addition to the uppercase action. In that case, the value returned to Cognos would vary based on whether we found the contents of the prompt valid or not.

The Result

Any lower-case letters the user types will automatically be converted to uppercase as they type them.

This same technique can be adapted to do all sorts of things, including converting to other cases (e.g. lower, sentence, or camel), enforcing maximum length, or even automatically padding the input to a specific length. Look for future posts that will feature more exotic uses of this approach.

Conclusion

Providing good user experience is sometimes a matter of protecting users from themselves. If incorrectly formatted input is passed and the report returns no results users are usually not happy. By correcting input in real-time we provide clean parameter data that can be handled by less-complicated and often more efficient filter logic.