Add a jQuery UI Slider to Your Cognos Prompt Page

The prompt controls and interfaces provided in Cognos BI Report Studio are limited and a bit old-fashioned. In fact, the look and feel of these controls has not changed much in the last decade in which I’ve been working with the tool. Meanwhile, Web interface look and feel has advanced considerably. Modern users expect more out of their Web-based interfaces around appearance and usability. With this gap in mind, I’m going to show you how to use the most popular JavaScript framework, jQuery, to add a simple slider control that can set the value of a text prompt.

Let’s get started.

Background

The jQuery JavaScript framework has gained wide adoption in recent years due to its ease of use and flexibility. The jQuery UI subset extends jQuery by providing many easy to use sophisticated user interface controls that can be deployed fairly easily. More information regarding jQuery UI can be found here: jQuery UI Home

The Technique

This tutorial will show you how to bind jQuery UI controls to Cognos’ own controls providing the report author more flexibility and usability options. We will be binding a jQuery UI slider to a hidden standard Cognos text box prompt. The slider will allow quick selection of a value between 1 and 1000. The text box prompt value will be synced with the slider and visual feedback of the number selected will be provided in real-time via a standard HTML span.

As the user drags the slider the value of both the Cognos prompt, hidden after development, and the user-visible HTML ‘Minimum Amount’ span will change in real-time to reflect the position on the slider.

This tutorial is not intended to match up 1-to-1 to a real-world use of a slider in a Cognos prompt page. It’s just a theoretical example used to demonstrate how jQuery UI and Cognos prompt integration can be done.

If you want to download a sample report spec you can get it here: jQuery UI Slider Sample Report

Create the Table

We are going to create a three row, one column table to hold the HTML objects and prompts in this tutorial. If you are unfamiliar with adding a table to a Cognos prompt page, follow these steps:

1. Click on the Table menu and select Insert>Table…
2. In the dialog that comes up, select 1 for ‘Number of columns’ and 3 for ‘Number of rows’. Uncheck ‘Maximize width’. The dialog should look like this:
   
   
3. Click ‘OK’ to insert your table

Add the Target HTML Object

Next we need to add the HTML object that will define the container for the slider as well as the user feedback container and label:

1. Drag over a ‘HTML Item’ object from your Toolbox and drop it in the first row of your table
2. Select the new HTML Item
3. Put ‘Slider’ in the ‘Description’ property
4. Double-click on the new ‘Slider’ HTML item
5. Paste the following code in the the HTML expression window:
   Slider container

   JavaScript

   <div> <span>Minimum Amount: <span id="minAmount">0</span></span> <div id="slider"> </div> </div> <style> #slider { margin: 10px 0 20px 5px; } </style>

   1 2 3 4 5 6 7 8 9 10 11

   <div> <span>Minimum Amount: <span id="minAmount">0</span></span> <div id="slider"> </div> </div>   <style> #slider { margin: 10px 0 20px 5px; } </style>

6. Click OK

We have placed objects that will receive the jQuery UI slider and defined a span that will give the user feedback as to which value they have selected with the slider. We’ve also added some CSS to give the controls some breathing room.

Add the Cognos Text Prompt

We need a way to pass in the value selected with the slider into a Cognos report for use in a filter, conditional style, or other purpose. To do this, we need to create a standard Cognos prompt which will receive the value selected by the slider:

1. Drag over a ‘Text Box Prompt’ control from your Toolbox and drop it in the middle row of your table
2. Click ‘Finish’ on the wizard to accept the prompt defaults
3. Select the new prompt control
4. Put ‘minAmountText’ in the ‘Name’ property
5. Double-click on the ‘Default Selections’ property
6. Click on the plus icon and put 0 in the box and click ‘OK’

We give the prompt control a name as that’s the only way to reference it with the Cognos JavaScript prompt API supplied with Cognos BI versions 10.2 and above. We set the default to ‘0’ because that will be the initial value of our slider.

This prompt should be hidden before release but I recommend leaving it visible while you are developing. With the prompt hidden the user will only see the updated jQuery UI powered control.

Add the jQuery UI Framework

We need to load in the jQuery and jQuery UI framework. This can either be done by downloading the code and pasting it into HTML items or through links to a hosted version of the files. For simplicity, I’m going to show how to get the code through hosted links:

1. Drag over a ‘HTML Item’ object from your Toolbox and drop it in the third row of your table
2. Select the new HTML Item
3. Put ‘jQuery Framework’ in the ‘Description’ property
4. Double-click the new ‘jQuery Framework’ HTML item
5. Paste the following code into the HTML expression window:
   
   Load jQuery

   JavaScript

   <link href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.min.css" rel="stylesheet" type="text/css" /> <script src="//code.jquery.com/jquery-1.11.3.min.js"></script> <script src="//code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>

   1 2 3

   <link href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.min.css" rel="stylesheet" type="text/css" /> <script src="//code.jquery.com/jquery-1.11.3.min.js"></script> <script src="//code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script>

6. Click OK

This HTML loads a default CSS theme, the appropriate parent jQuery framework, and the jQuery UI extension.

Add the Custom jQuery/JavaScript

The last major task is to add the custom jQuery and JavaScript that will define the slider and its behavior and link the value of the slider to the Cognos text prompt control:

1. Drag over a ‘HTML Item’ object from your Toolbox and drop it in the last row of your table, to the right of the ‘jQuery Framework’ HTML item
2. Select the new HTML item
3. Put ‘Custom jQuery/JavaScript’ in the ‘Description’ property
4. Double-click on the new ‘Custom jQuery/JavaScript’ HTML item
5. Paste the following code in the expression window:
   Custom jQuery/JavaScript

   JavaScript

   <script> var report = cognos.Report.getReport('THIS_'); var minAmountText = report.prompt.getControlByName('minAmountText'); var minAmount = document.getElementById('minAmount'); $(document).ready(function() { $( '#slider' ).slider({ value: 0, max: 1000, animate: 'slow', slide: function(event,ui) { var currentValue = $('#slider').slider('value').toString(); minAmount.innerHTML = currentValue; minAmountText.addValues([{'use':currentValue}]); }, stop: function(event,ui) { var currentValue = $('#slider').slider('value').toString(); minAmount.innerHTML = currentValue; minAmountText.addValues([{'use':currentValue}]); } }); }); </script>

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

   <script> var report = cognos.Report.getReport('THIS_'); var minAmountText = report.prompt.getControlByName('minAmountText'); var minAmount = document.getElementById('minAmount');   $(document).ready(function() { $( '#slider' ).slider({ value: 0, max: 1000, animate: 'slow', slide: function(event,ui) { var currentValue = $('#slider').slider('value').toString(); minAmount.innerHTML = currentValue; minAmountText.addValues([{'use':currentValue}]); }, stop: function(event,ui) { var currentValue = $('#slider').slider('value').toString(); minAmount.innerHTML = currentValue; minAmountText.addValues([{'use':currentValue}]); } }); }); </script>

6. Click OK

Let’s look at the code in detail:

This is a common pattern when working with the Cognos BI JavaScript API. The first line assigns a variable to the page instance. The second line uses the page and prompt name reference to assign a variable to the Cognos prompt object. We can now manipulate the prompt directly using this reference and Cognos JavaScript Prompt API calls. These two lines are the only pure JavaScript in the code.

We are starting to define a function that will be executed when the page has finished loading. Within that function we identify the div that will contain the slider using its id and attach the slider behavior by calling the slider method on that object.

We set some initial properties for the slider, in this case the initial value, maximum value and animation speed.

We define a function to fire while the slider is sliding.

We grab the slider’s current value and assign it to a variable.

We set the innerHTML property of the feedback span to the current value.

We set the value of the Cognos text prompt by calling the Cognos JavaScript API addValues() function and passing in the current value from the slider in Cognos value object form.

For more information about Cognos value objects see the Cognos JavaScript API

We define a function to fire when the slider movement stops. We perform the same operations on the feedback span and Cognos text prompt as we did for the slide event. This seems redundant but since the sliding is animated, the value grabbed when the slide event fires will sometimes not reflect the ultimate value once the slide has completed. Thus we update the values during the slide for real-time feedback and again when the slide is complete which is represented by the stop event.

Result

After following those steps your page should look like this:

When you run the report, your output should look like this:

As you drag the slider back and forth the value in both the feedback span and the Cognos prompt changes in real-time. When you submit the prompt page, the value stored in the Cognos prompt can then be used in the report itself like any other parameter.

I encourage you to look over the documentation for the slider widget on the jQuery UI Web site. There are many other parameters you can add and tweak to change the behavior and look of the slider control. For instance, you can have a vertical, rather than the default horizontal orientation.

There are also many more jQuery UI widgets that can be used in a similar way on Cognos prompt pages. There are also more themes that can be applied to change the look and feel of jQuery UI controls. The only limit is the imagination of the developer.

Conclusion

Cognos’ dated and limited prompt controls can be given a fresh new look by linking them to more advanced and responsive jQuery UI controls. By use of the Cognos JavaScript API we can take the values supplied by the jQuery interface elements and update hidden standard prompts in real-time. The submitted parameters can then be used like any other Cognos parameter. The result is a make over for your stale prompt page designs.

Updates

2015.11.26 – The initial post contained a fatal line omission that caused the JavaScript to break and the slider to not function. I have corrected the code and included a link to a report spec that demonstrates the technique. Thank you Nick Waters and Georgios Dimitrakis for bringing this to my attention.

2016.11.27 – I added some margin to the slider for presentation purposes. I added the slide event to the slider to provide feedback in real-time instead of just when the slide has stopped. I also set the animation speed to ‘slow’ for a cool effect.