Captialize Cognos Text Prompt Input in Real-Time

By | 2015.11.30

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

Auto-Capitalizing Text PromptWe 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.

Auto-Capitalizing Text Prompt

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.

11 thoughts on “Captialize Cognos Text Prompt Input in Real-Time

  1. Tim Young

    Great code worked on both my text boxes. One HTML Item per box.

    Reply
  2. sharath

    This is a great code to use if we have only one entry. Could you let me know how can we do this if prompt has multiple values.

    Reply
    1. Scott E. Johnson Post author

      The Cognos Prompt API has bugs when trying to use it with multi text prompts. It’s impossible to reliably to read the contents of the text input box as well as trap the update event. Due to this, multi text boxes are not supported. However, I created a method to utilize a single text box to populate a hidden multi text box. This allows for multiple value entry using a comma-separated list. You can combine this method with the auto-capitalization method to support auto-capitalization of multi text entry. Here’s a link to that blog post:

      http://cogblogger.com/2015/03/comma-separated-multi-value-text-prompt-input/

      Reply
  3. Basil

    Hey great scripts.. I have both working on separate reports, however, i want to pass the UPPER to the search.. Seems the UPPER and Text Prompt Input in Real-Time is not working for me in the same report.. Any thoughts or tricks?

    Reply
    1. Scott E. Johnson Post author

      Can you clarify? Which two transformations do you want to combine in the same report?

      By the way, the examples I’ve provided are meant to be instructional. The idea is to give people an idea what is possible using the Cognos JavaScript prompt API, which they can then adapt to fit their particular needs. Combining two transformations into one would take some doing beyond the examples provided.

      Reply
  4. sree

    This technique is beautiful Scott.
    How to change this code for multiselect text box prompt values?

    Reply
    1. Scott E. Johnson Post author

      Hi,

      Unfortunately, there is a bug in Cognos regarding multi-select text prompt controls. API validation events fired on such prompts affect both the input text box and the box that collects the choices. This results in major problems when trying to use the technique described here.

      As an alternative, you might consider exploring a comma-separated multi-value text prompt. I described a technique to implement this is in another blog post:

      http://cogblogger.com/2015/03/comma-separated-multi-value-text-prompt-input/

      You could easily adapt this method to change the value to uppercase before adding it to the hidden multi-value text prompt.

      Scott

      Reply
  5. Sharon C.

    Do you know what changes are needed in the Javascript for 10.1.1?

    Reply
  6. Sharon C.

    Thanks and I did prove that it works in 10.2. Do you know what changes need to be made to make in work in 10.1.1?

    Reply
  7. Sharon C.

    What version of Cognos did you use for this? It works in Cognos 10.2.2 but not in Cognos 10.1

    Reply
    1. Scott E. Johnson Post author

      All of my JavaScript solutions utilize the Cognos JavaScript Prompt API that was officially added to Cognos BI 10.2. They should work on version 10.2 and above.

      Reply

Leave a Reply