Cognos only supports two type of text box prompt validation; required and numbers only. In both cases Cognos evaluates the text input in real-time. If the validation fails, the prompt gets an orange dashed line underneath it and the Finish button is grayed out. The required validation fails if the prompt is empty and the numbers only validation fails if the value entered in the text prompt contains any non-numerical characters. More advanced validation logic is not available.
Starting with Cognos BI version 10.2, Cognos provides a documented and supported JavaScript prompt API to allow developers to manipulate prompts using custom JavaScript. One of the key features of this API is the ability to supply your own validation logic for prompts. This custom logic replaces any existing Cognos validation checks with the custom code. Alerting the user to an invalid condition is still handled by Cognos, the code simply tells Cognos whether the prompt is to be consider valid or not.
We can use the Cognos JavaScript prompt API to perform real-time custom validation of prompts with the sophistication only limited by the skill and imagination of the developer.
Technique
The technique hooks into the Cognos validation routine via the API setValidator() method. We call this function, passing in our custom validation function as a parameter. Cognos then fires our validation function whenever the prompt value is changed. The function returns true if the contents are considered valid and false if not.
Tutorial
The purpose of this tutorial is to give a basic example showing how custom validation via the Cognos JavaScript Prompt API works. We are going to perform a numeric range validation. If the contents of the text input fall within the numeric range we specify we’ll tell Cognos it is valid by returning true, otherwise we will return false. However, if the prompt is empty or contains non-numbers, we’ll also return false.
If you want to skip the coding, you can download an example report with the coding completed here.
Preparation
Before we code we have to do some preparation. I’m assuming you have a test report with a blank prompt page.
- Add a new text prompt to a prompt page. Name it textPrompt. In order to reference the prompt in the code you have to provide a value for its name property.
- Set the existing validation settings to No. These are the Required and Numbers Only properties. We will override them anyway but we want to be sure the behavior comes from our code and not from the built-in Cognos validation.
- Add a new HTML Item to the report. Place the item after the prompt added in step 1.
- Enter Custom JavaScript in the Description property for the new HTML item. This step isn’t necessary but is recommended to provide context.
Code
Open the HTML item and paste in the following code:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
<script> var report = cognos.Report.getReport('_THIS_'); //Get report reference var textPrompt = report.prompt.getControlByName('textPrompt'); //Get prompt reference textPrompt.setValidator(validation); //Assign custom validator function function validation(values) { var lower = 20; //Lower range limit var upper = 75; //Upper range limit var result = false; //We default to invalid to support required validation if (values && values.length > 0) { //Check to see if the prompt has values result = ( !isNaN(values[0].display) //Return true if content all numbers && values[0].display >= lower //Return true if value greater than lower limit && values[0].display <= upper //Return true if value less than lower limit ); //All three checks must return true for result to be true } return result; //Pass the result to Cognos } </script> |
Let’s take a look at some important pieces of the code:
|
2 3 |
var report = cognos.Report.getReport('_THIS_'); var textPrompt = report.prompt.getControlByName('textPrompt'); |
We get a reference to the report as a whole using a call to the Cognos JavaScript Prompt API. We then use this reference to get a reference to the specific prompt using the API’s getControByName() method. This pattern appears often in custom JavaScript that utilizes the API.
|
5 |
textPrompt.setValidator(validation); |
We call the API setValidator() method against the textPrompt object, passing in the name of a custom validation function that we will define later in the code.
|
7 |
function validation(values) { |
This is the beginning of our custom function. When Cognos calls custom validation functions, it automatically passes in an array containing all of the current value objects for that prompt. In the code that array will be referenced as values.
|
8 9 |
var lower = 20; //Lower range limit var upper = 75; //Upper range limit |
We define the lower and upper limit of our range. These numbers can be changed to enforce any range desired.
|
9 |
var result = false; |
We store the result of the validation in a boolean variable called result. This is the value that we will ultimately return to Cognos. Since don’t want the prompt to be valid if it is empty, our default state is to invalidate the prompt. If we wanted the prompt to be optional we would set this variable to true here.
|
10 |
if (values && values.length > 0) { |
There’s no need to perform range validation on a prompt that has no value. We check here to make sure that there is a value in the prompt before we do any of the validation logic. Note that even though text prompts can only contain one value, Cognos always stores this in an array; one with only one element.
|
11 12 13 14 15 |
result = ( !isNaN(values[0].display) //Return true if content all numbers && values[0].display >= lower //Return true if value greater than lower limit && values[0].display <= upper //Return true if value less than lower limit ); |
We perform three checks on the value of the prompt. All three have to return true for us to consider the prompt valid. The first uses the JavaScript isNaN() (is not a number) function to determine if the prompt is all numbers. The second checks to see if the number is greater than the lower limit and the last determines if the value is less than the upper limit.
|
17 |
return result; |
All custom validation functions have to return a boolean value to Cognos, either true or false, representing the state of the prompt.
Result
As the user types, their input will be evaluated in real-time to make sure it contains only numbers and is within the numeric range we specify. If the value they supply fails one of our validation checks the prompt will receive the standard Cognos invalid styling and the Finish button will be grayed out.
Conclusion
Cognos text prompt validation options are severely limited. With the Cognos JavaScript Prompt API and a bit of code we can supply our own robust validation code to enforce any number of rules.