JavaScript: Automatic Prompt Variable Creation

An important part of the process of working with the Cognos JavaScript API is creating variables that reference the JavaScript objects that Cognos creates to represent the prompts on the page. It’s via these variables that we manipulate the properties and call the methods on the prompt objects. This post will detail a technique to automatically take care of this for you, resulting in cleaner code and a consistent naming convention.

Manual Method

Before we go into the automatic pattern, let’s review how creating variables would work doing it the manual way.

The first thing we need to do is assign a variable that points to the report object itself.

The next thing we need to do is assign a variable that points to each prompt object. We do this by calling the getControlByName() method of the report object. We use the previously created report variable to do this.

Now that we have a variable that references the prompt we can access or change properties or call methods.

The second step will have to be repeated for each prompt on the page. With a large number of prompts this can quickly get tedious and hard to maintain. Additionally, any new prompts added to the page will also have to have a corresponding line added to the code defining the variable used to reference the prompt.

A Better Way

Instead of manually maintaining the variable creation process, we can leverage some lesser-used API calls to do all of it automatically for us. The code can then be added to your JavaScript, most likely at the top, or even better integrated in a standard JavaScript library. The result is simplified modular code which is much easier to work with, especially for less-experienced developers.

The Code

Since we are creating modular code, it’s best to put the code into a function. We can then call this function at will. Code within a JavaScript function has its own scope so variables we use within it will not collide with any variables in the global scope or those in other functions.

Here is the function code:

Let’s examine the code in detail.

We need a variable to represent the Cognos report instance. All operations against the Cognos JavaScript API start with getting a report instance reference.

We call the getControls() method using the report reference. This function returns an array containing all of the Cognos JavaScript API prompt objects. We store the resulting array in the variable ‘controls’.

It’s best practice to always initialize variables. The ‘controlname’ variable will be assigned multiple values in the forthcoming loop. Thus, it’s best to initialize it before entering the loop.

We initiate a loop through each prompt object stored in our ‘controls’ array.

We call the getName() method on the current control object and store the result in the ‘controlname’ variable. The returned string will be the name given to the prompt in Cognos.

We check to see if we successfully acquired the name of the control.

We create a global variable with the same name as the current prompt and assign it the reference to the associated prompt object.

Now we simply need to call the function when we want the variables to be created.

Now we have a modular function that we can place in our scripts or even better in a standardized library. Due to the way Cognos processes HTML objects on a page, it’s recommended that this function be called at the beginning of your JavaScript code. Just know that the code has to be in an HTML object below the prompts to work as the prompts have to be already rendered by Cognos by the time the JavaScript is executed. I will go over HTML object placement best practices in a future post.

Please be aware that this technique assumes that authors will give their prompts legal JavaScript variable names. For instance, names with spaces in them will not work. See the JavaScript Identifiers section of the w3schools.com JavaScript Variables Web page for more information.

Variable Scope

The astute observer might notice that the variables created with this code are in the global scope. This is fine if you are careful how you name your prompts in Cognos. If you chose names that are not likely to collide with any existing global variables then the code will work as is. Care has to be taken to make sure those who build reports using this method take steps to use unique names for their prompts. To avoid the problem altogether, I recommend using namespacing which will be covered in detail in a future post.

For those that are using namespaces, a couple simple modifications to the code will allow the variables to be created in your namespace instead of in the global scope.

If your namespace is ‘abc’ then the following code will create all your variables automatically under that namespace:

Calls to the function in this scenario would need to be slightly modified as well:

Conclusion

Declaring variables for each prompt on a page is tedious, prone to syntax errors and confusing to many Cognos developers. By leveraging the JavaScript API we can automate the process and ensure correlation between the name given to a prompt in the Cognos GUI and the variable used to reference the associated prompt in any JavaScript we use. This simplifies the usage of JavaScript in Cognos reports, especially for Cognos developers that have minimal JavaScript experience. When incorporated into a standardized library even more advantages are gained as custom JavaScript added by the report author will be cleaner, easier to read, and more consistent.