Comma-Separated Multi-Value Text Prompt Input

In Cognos text prompt interfaces come in two major forms. There is the standard single-value text prompt:

…and the multi-value text prompt:

If you want your user to be able to enter multiple text values in a single prompt the multi-value text prompt interface is the only option available out of the box.

This interface has several drawbacks:

• The prompt control takes up a lot of space on the page impeding efficient and compact prompt page design
• The Insert button must be clicked or the enter key struck to add the current text to the choices. This can be tedious when a lot of entries must be keyed in
• There is no way to bulk insert multiple entries, such as a comma-separated list

I’m proposing an alternate way to handle mutlti-item text input. The technique uses JavaScript and specifically the Cognos JavaScript API provided in versions 10.2 and above of the Cognos BI product to extend the functionality of the provided default text input prompt controls to support bulk-entry of comma-separated values.

The trick has several benefits:

• Facilitates compact prompt layouts
• Allows fast input without having to hit enter between values, perfect for power typists
• Supports copy and paste functionality for importing bulk text values from other applications

Let’s get started.

The Technique

The solution uses a standard text box prompt, either single or multi-line, to enter comma-separated values. The corresponding individual entries will be added to a hidden multi-value text prompt via JavaScript validation events in real-time. In the report query the parameter assigned to the standard text prompt can be ignored and the parameter associated with the hidden multi-value text prompt can be used in filters just like the values were entered into the hidden prompt directly. The trick works even if text is bulk-inserted in the standard prompt via pasting from the clipboard. The result will look like this after entering some comma-separated values in the standard multi-line text prompt:

It’s important to note that I simply typed the comma-separated values as shown straight into the prompt on the left and the values were automatically added to the multi-value prompt on the right. I didn’t hit enter or click the Insert button on the control. At all times the two boxes’ contents are synchronized by the JavaScript code, in real-time.

The key to the solution is that every time the text within the standard text prompt is changed, the custom JavaScript validation routine fires. The code parses the contents of the standard text prompt, determines the individual values, and enters them automatically in the hidden multi-value text prompt. This all happens very rapidly, after each keystroke. If the basic text prompt contents are cleared, the hidden prompt’s contents are cleared as well. Because of this approach the two prompts are always in sync.

Preparation

Before we can reference any Cognos prompt within JavaScript we have to provide a name for the prompt in the prompt object’s Name property. Ideally, the name should conform to JavaScript variable naming conventions. See the JavaScript Identifiers section of the w3schools.com JavaScript Variables Web page for more information. JavaScript compliant names allow us to use the same name to create reference variables in the code. This makes writing and maintaining the code much easier.

Assumptions

The code provided assumes there are two prompts on your page: a standard text prompt with the name textPromptSource and a multi-value text prompt with the name textPromptTarget. At some point the mutli-select text prompt will be hidden so the user only sees the standard text prompt for input but while testing I recommend keeping the target prompt visible.

The Code

All code below should reside in an HTML item that is located after all prompts on the page. The code should be inserted between opening and closing script tags. See w3schools.com HTML Script Tag Web page for more information.

Let’s examine the core bits of code in detail.

For those who have looked at other posts involving the Cognos JavaScript API these lines should look familiar. All work with the API first requires that we grab a reference to the report and store it in a variable. Using that report reference we assign variables to the JavaScript objects representing our two prompts by calling the API’s getControlByName() function.

The setValidator() Cognos JavaScript API function takes a custom function and assigns it as the validator for the prompt it’s called on. The validation function fires on every change to the prompt contents and either returns true or false. If true is returned then the prompt is considered valid. If false is returned the prompt is considered invalid and will receive the standard Cognos invalid prompt styling (squiggly orange line etc.). It’s up to the coder to determine programatically whether a prompt is valid or not. Even if we don’t care about validation we can use this hook to perform all kinds of tasks which execute when the user changes the contents of the prompt.

This is where all the magic happens. The code within the function will fire each time the contents of the standard text box are changed. If you specify a parameter for the function (in this case values) that parameter will receive all selected or entered values of the relevant prompt in the form of a JSON object. This will always be an array, even if there is only a single value as with our case.

The if statement makes sure that the prompt has at least one value before proceeding with the bulk of the actions. This is a very common pattern used when writing Cognos JavaScript API validation functions. If the prompt is empty we have no need to do anything with its contents and we avoid errors by not calling methods on non-existent value objects.

This is an important part of the technique. We call the standard JavaScript string method split() which takes a separator character and breaks a string up into an array based on the separator. This will allow us to iterate through each value and build a JSON object representing all current values.

We iterate through all individual entries we found in the standard text box prompt. In each loop we create an empty object and assign the current entry’s value to the new object’s use property. Lastly, we push that object onto the targetvalues array.

Once we are out of the loop we take the newly created array of values and pass them to the Cognos JavaScript API setValues() method to add them to the target prompt. The setValues() function performs two API methods in succession: clearValues() and addValues(). By clearing the prompt each time we are assured that the multi-value prompt always matches the values entered in the standard text prompt.

The code in the else block fires when the standard text prompt contains no values. We clear the multi-value prompt in this instance to be sure that its contents reflects the state of the standard text prompt.

We return true to tell Cognos that the prompt is valid.

We could have performed other checks to determine if the prompt input is valid and returned false if not. For instance, we could limit our input values to numbers only and return false if any of them contain something other than a number. Validation of this nature will be covered in a future post so I won’t cover it here.

Notes:

Once again, we put our code in an if block in order to guarantee that the code only runs once.

Edit: The original version of this post enclosed all of the code in an if block to prevent the code from running more than once. For more information see JavaScript: Running Code Only Once. Some time after posting I realized that Cognos page reprompts behave differently than I had thought. Cognos creates new instances of all API objects on each reprompt. Because of this problems will arise if some types of statements are not executed every time. Any statement that assigns a reference to a Cognos API object must be executed each time to get a reference to the current object instance. For this reason I removed the if block to avoid reprompt issues. The functionality hasn’t changed.

We used a comma as a separator but there is no reason we are limited to that character. You could easily use pipe or another separator character. To change this simply change the separator passed into the split() function on line 9. My forthcoming Cognos JavaScript Library (CJL) contains advanced regular expression type matching that can extend the behavior described in this post to any number of separators, or even all of them at once. Better yet, the functionality can be implemented with a simple HTML tag and some attributes. No custom JavaScript required! Stay tuned!

Conclusion

The standard Cognos muti-value text prompt implementation leaves a lot to be desired. The control takes up a lot of room on a prompt page and slows down data-entry by requiring that each value be inserted individually. There is also no facility for pasting in bulk delimited text. By utilizing the Cognos JavaScript API and a bit of code we can transform a standard text box into a dynamic and efficient multi-value interface. The result is faster and more flexible data-entry coupled with minimal page footprint.

Hopefully, this novel solution helps you to understand how JavaScript along with the fully-supported Cognos JavaScript API can be harnessed to provide a whole new set of functionality likely not thought of by the software creators. This is only the beginning.