Cognos Forum 2008 - Advanced Prompting

Tip or Technique

IBM Cognos Forum 2008

Session 1259 Advanced Prompting

Product(s): IBM Cognos 8 BI

Area of Interest: Reporting

Session 1259 Advanced Prompting 2

Copyright Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to the information contained in this document will be documented in subsequent editions. This document contains proprietary information of Cognos. All rights are reserved. No part of this document may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos. Cognos and the Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated) in the United States and/or other countries. IBM and the IBM logo are trademarks of International Business Machines Corporation in the United States, or other countries, or both. All other names are trademarks or registered trademarks of their respective companies. Information about Cognos products can be found at www.cognos.com This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to [email protected].

IBM Cognos Proprietary Information

mailto:[email protected]

mailto:[email protected]


Contents 1 INTRODUCTION............................................................................................ 4 2 ENHANCEMENTS TO PROMPT CACHING....................................................... 5 2.1 DYNAMIC PROMPT CACHE REFRESH..............................................................................5 2.2 MULTILINGUAL CACHE..............................................................................................6 2.3 UNILINGUAL CACHE .................................................................................................8 3 REUSABLE TOOLBOX OBJECTS ..................................................................... 9 3.1 WORKSHOP: RE-USABLE HTML ITEM......................................................................... 12 3.2 WORKSHOP: REUSABLE PROMPT CONTROLS ................................................................. 18 4 CUSTOM PROMPT CONTROLS OVERVIEW .................................................. 23 4.1 CREATE THE CUSTOM PROMPT CONTROL ..................................................................... 24 4.1.1 Beer Glass Control............................................................................................. 24 4.2 PLACE THE CUSTOM PROMPT INTO THE PROMPT PAGE..................................................... 25 4.3 SET THE PARAMETER VALUES ................................................................................... 26 5 WORKING WITH THE SAMPLES.................................................................. 27 5.1 SETTING UP THE SAMPLES....................................................................................... 27 5.2 CUSTOM PROMPT BUTTONS ..................................................................................... 28 5.3 BEER GLASS ........................................................................................................ 32 5.4 DYNAMIC PICKLIST PROMPT..................................................................................... 36 5.4.1 How does the Dynamic Picklist Prompt Work ....................................................... 39 5.5 TAB CONTROL PROMPT........................................................................................... 41 6 CONCLUSION .............................................................................................. 46



1 Introduction

In this paper we will cover two topics: changes to prompting in IBM Cognos 8.4 and custom prompt controls. The changes to prompting in the IBM Cognos 8.4 release are designed to both extend the prompt cache feature and make the prompt cache easier to administer. The custom prompt controls are designed to teach you the principles of creating your own prompt controls and provide some useful example such as a tabbed prompt interface and an on demand pick list. The custom prompt controls have been tested with both IBM Cognos 8.3 and IBM Cognos 8.4. This paper was presented at the 2008 North America IBM Cognos Forum.



2 Enhancements to Prompt Caching

IBM Cognos 8.4 adds two additional features to the existing prompt caching feature. The first makes administration of the caches much easier, the second provides enhanced multi-lingual user support.

2.1 Dynamic Prompt Cache Refresh IBM Cognos 8.3 introduced prompt caching which allows the prompt query values to be cached and reused. The cache refresh was controlled through the use of Jobs to run the report prompt queries to refresh the cache. Customer feedback indicated that while this feature went along way to providing better prompt performance by reusing query results, the use of jobs to administer the prompt cache refresh was an onerous task which increased the maintenance work required of an administrator. Therefore, the management of the prompt cache has been simplified for IBM Cognos 8.4. For upgrade compatibility, Jobs can still be used to maintain the prompt cache. However, a new option has now been added to the report properties Report Tab as so:

When this option is used, the prompt cache will be managed automatically by the system with no requirement for Jobs or other intervention. This option uses user report execution to drive the prompt cache refresh activity. When the report is executed, we determine if the cache is valid or expired based on the expiry period specified in the report properties. If the cache is fresh then no action is taken. If the cache is expired then the cached data is deleted and the prompt query is executed to create the new cache.



2.2 Multilingual Cache1 The prompt cache is multilingual and the query used to populate the cache is driven by the users Content Locale2 (the language used to run reports and view data). When the cache is refreshed using the dynamic refresh method, the content language of the current user is used to run the prompt query. Only when subsequent users with a different content language run the report will the cache for another language be created. When the prompt cache is expired, all languages are deleted at the same time. To see this in action consider the following scenario and events:

A report is newly created with no prompt cache. The Dynamic Prompt Cache option is set with an expiry of 7 days. On the day the report is created, a French language user runs the report causing the French language prompt cache to be created. This sets the cache creation date. On day 2, two more French language users run the same report. As the French language prompt cache already exists, it is used for all users. On day 3, a German language user runs the report. As there is no German prompt cache, the prompt query is run and the German prompt cache is created. The French cache is not affected by this operation. On day 3, new French language users also run the report and use the French language cache created on day 1. On days 4 through 7, additional French and German users run the report, using their respective language prompt caches. On day 8, a German user runs the report. Since the expiration date was set by the French cache on day 1, the prompt cache is now older than the 7 day threshold. The prompt cache is deleted in all languages even though the German cache is only 4 days old. To satisfy the German report request, a new German language cache is now created.

1 Note that with the IBM Cognos 8.3 job based cache refresh, the prompt cache was created in all languages when the job was run. 2 Locale is a combination of language and region. For example EN-US is English language in the United States region. While it is possible to differentiate data by locale – “Tire” in North America versus “Tyre” in the UK, most companies do not make such a differentiation and instead use only the language to differentiate data. The sample databases that come with IBM Cognos 8 are perfect examples of this approach.



No other users run the report for 6 months. The cache is unaffected as there is no user operation to drive the refresh. An English language user runs the report. The cache (German) is past the expiration date so it is cleared and an English cache created. And so on, with language specific data being cached as required.



2.3 Unilingual Cache An interesting variation on multilingual applications has a multilingual users reporting against a unilingual database. That is, the users wish to see the data presented according to their content locale – numbers and date in local format such as $123.45 versus 123,45$ or 1 January 2008 versus janvier 01, 2008 for example – but the data is all in a single language. One IBM Cognos customer, a major airline, records all information in English but allows users to choose their language for IBM Cognos 8 user interface and data formatting. In this variation, there is no value in creating prompt caches for different user content languages as they would all contain the same data from the unilingual database. To meet this need, IBM Cognos 8.4 includes an advanced server property which allows you to specify the single language for which all prompt caches are created. The property RSVP.PROMPTCACHE.LOCALE=<locale> is set in the server administration screens in Cognos Connection and tells the server which language is to be used for all prompt caches. This will take precedence over the user content locale when the prompt cache is created. As it is difficult to demonstrate the advanced server property in action, a workshop scenario will not be presented on this topic. For additional information on advanced server properties, please see the IBM Cognos 8.4 administration manual.



3 Reusable Toolbox Objects3 Many times reporting projects require the same Report Studio objects, such as a prompt definition, in different reports. This can be done either by using report layout references between reports or by using custom toolbox items. As the prompt techniques used later in this document use custom toolbox items this section will focus on this approach instead of layout component references, which are covered in the Report Studio User Guide. A custom toolbox item is simply a snippet of valid xml from a report4. For example, the HTML item in the standard Report Studio toolbox is the following xml report specification snippet: 

<HTMLItem id="HTMLItem">

<dataSource>

<staticValue/>

</dataSource>

</HTMLItem>

Before custom toolbox entries can be created you should have, at least, a basic understanding of the Report Studio XML report specification. The IBM Cognos 8 BI SDK guide fully documents and explains the report specification xml schema. Based on the report specification, custom HTML/JavaScript code to be added to the report appears in the <staticValue> tag of the HTMLItem element as so: <HTMLItem>

<dataSource>

<staticValue>This is my <b>CUSTOM</b> HTML.</staticValue>

</dataSource>

</HTMLItem>

This example would display simple text in the report in HTML format as so:

To add this to the Report Studio toolbox, you need to be aware of two files5:

1. Toolbox.xml 2. ToolboxControls.xml

3 This topic has been well covered previously in documentation and proven practices papers if you feel the need for more information. 4 Report Studio toolbox items are not all simple xml report specification snippets but the snippet mechanism is documented and supported and meets our needs. 5 These files are located in the ..\c8\webcontent\pat\res directory.



Toolbox.xml creates the structure of the toolbox determining which items show up in which Report Studio context; as you navigate to different parts of the Report Studio user interface, different objects will appear in the toolbox. The item name, context, parameters and so on are defined in the Toolbox.xml file. In toolbox.xml, the HTML item definition for example appears as so: Definition Meaning <listItem This item appears in a list of items

controlRef="HTMLItem" The id of the item as it appears in ToolboxControls.xml (HTMLItem). This id must be unique in this file.

value="" Reserved for Report Studio use. When creating new entries, always use the same value that has been used for a default item.

label="HTML Item" The label which appears in the Report Studio toolbox6.

tooltip="HTML Item" The tool tip which appears in the Report Studio toolbox.

smallIcon="HTMLItem.gif"/> The name of the icon to appear in the toolbox. The icons can be found in the directory: …\c8\webcontent\pat\images

ToolboxControls.xml defines the xml report snippets. Remember that the name used in the toolbox.xml controlRef tag and the toolboxControls.xml id must be the same and that the xml snippet must be valid xml.

6 You will see idsLabel= and idsTooltip used by Report Studio. These are references to a localized message file if you wish to support Report Studio users in multiple languages.



ToolboxControls.xml defines the item itself as so: Definition Meaning <HTMLItem id="HTMLItem"> The HTMLItem element tells Report Studio

what type of object this is7.

The id=”HTMLItem” property links the element back to Toolbox.xml to ensure the correct placement of the object in the Report Studio toolbox. This id must be unique in this file.

<dataSource>

<staticValue/>

</dataSource>

The definition of the item as specified in the XML report specification schema.

</HTMLItem> Ends the definition

Remember that the XML snippet must be valid within a report specification. How do you know? Test it before you create the custom toolbox entry. Once the custom toolbox entry has been created, it appears in Report Studio and can be dropped into the report.

7 Remember that the report specification XML schema defines the object types available in a report. You must reference a valid report object type.



3.1 Workshop: Re-Usable HTML Item This workshop will demonstrate how to create an HTML item for use in Report Studio. Open Report Studio with the GO Sales (query) package8. Create a list report with

• \Sales (query)\Products\Product line As so:

Drop an HTML Item from the Report Studio toolbox into the page body after the list:

Double click the HTML item to edit the HTML content as so:

8 This package is provide with the IBM Cognos 8.4 samples. A system administrator can assist with deploying the sample content if required.



Click OK and run the report:

This shows that the HTML item is working and well formed. Return to Report Studio and select the HTML item. Copy the HTML item to the Windows clipboard using CTRL-c or the copy button from the Report Studio toolbar. Open notepad or another text editor and paste the contents of the clipboard into the text editor to see the XML code: <RSClipboardFragment version="2.0">

<HTMLItem>

<dataSource>

<staticValue>This is <b>MY</b> HTML item.</staticValue>

</dataSource>

</HTMLItem>

</RSClipboardFragment>

Line breaks have been added to make the xml snippet more legible. Delete the opening and closing tags of the RSCliboardFragment element (the first and last lines of the above sample): <HTMLItem>

<dataSource>


</dataSource>

</HTMLItem>

The staticValue content contains somewhat cryptic information such as <b;&gt. This is HTML encoded text to ensure that special characters such as < and > (&lt and &gt) are transmitted correctly. The toolbox objects do not required HTML encoding of special characters so the encoded characters could be replaced with regular characters. However, leaving them as encoded characters will not impact the toolbox object definition.



Open Toolbox.xml. Insert a new line as in the highlighted text below: 

<resources>



<listView id="Toolbox_PageView" classPrefix="clsListItem_tb">

<listItems>

<listItem controlRef="myHTMLItem" value="A" label="My HTML Item" tooltip="This is my personal HTML Item"/>

Note that the order of the entries in this file determines their order in Report Studio so the new item will appear first in the Toolbox. Save and close the Toolbox.xml file. Open ToolboxControls.xml. Copy and paste the new HTML item definition into this file: 

<resources>

<xmlFragment id="ToolboxControls">



<HTMLItem>

<dataSource>


</dataSource>

</HTMLItem>



Note that a comment tag has been added before the new HTML item. These comments are not strictly required by help to locate and document content if you are making changes to the ToolboxControls.xml file. Add the ID to create the link back to Toolbox.xml: 

<resources>




<HTMLItem id="myHTMLItem" >

<dataSource>


</dataSource>

</HTMLItem>

Save and close this file. The process to add the new item is now complete. To see the new item in Report Studio simply close and re-open Report Studio to apply the changes. The toolbox.xml and toolboxCongrols.xml are loaded when Report Studio starts, hence the requirement to re-open Report Studio. However, there is no need to restart the IBM Cognos 8 server to apply the changes. Create a new list report using Product line:



Open the Toolbox and note that our custom item appears first:

Drop the HTML item into the report after the list:

From this point forward, everything is just as if the HTML item had been created from scratch. You can make changes to the new HTML item in your report layout as you would with any other HTML item. Run the report:



Adding elements to the toolbox review: 1. Create the object you need in Report Studio. 2. Copy the item to the clipboard 3. Delete the first and last lines with the RSClipboardFragment

references. 4. Create a new entry in Toolbox.xml using a unique id name 5. Create the new entry in ToolboxControls.xml

a. Paste the report XML in b. Add an id

6. Use it in your report. Keep in mind that once the new object has been inserted into your report it exists independent of the object defined in the toolbox. This means that changes to the toolbox definition will not be applied objects that have already been inserted into the report.



3.2 Workshop: Reusable Prompt Controls There may be times when a report author wishes to make the re-use of a given prompt control definition very easy. For example, suppose the author has created a picklist prompt with a long series of static values. Setting this up in Report Studio each time involves:

1. Drag and drop a value prompt into the report 2. Set the Select UI property to List box 3. Set the Multi-select property to Yes 4. Enter the static values

For short lists this process is fairly simple but for long lists of static values, recreating the prompt each time can become tedious very quickly. This workshop will demonstrate how to create a reusable prompt so that an author does not need to enter the values for each new report. Open Report Studio with the GO Sales (query) package. Create a list report with:

• \Sales (query)\Order method\Order method:

Select Order method and press the Build Prompt Page toolbar button. Report Studio will create an appropriate Order method filter, insert a prompt page, and create the prompt with a query to populate it. Assuming that the list of order methods does not change it is possible to use a list of static values rather than a query to populate the prompt control. Select the prompt. Set the Query method to (Default).



Add static values for:

Run the report and test the various static values to make sure that they match the requirements of the query filter expression. Return to Report Studio. Select the prompt and copy it to the Windows clipboard.



Open notepad and paste the code in. Delete the RSClipboardFragment tags and you will have a standard prompt definition: <selectValue parameter="Order method" required="true" multiSelect="true" range="false" autoSubmit="false"

selectValueUI="listBox">

<XMLAttributes>

<XMLAttribute name="dataType" value="xsdString" render="true"/>

</XMLAttributes>

<selectOptions>

<selectOption useValue="E-mail">

<displayValue>E-mail</displayValue>

</selectOption>

<selectOption useValue="Fax">

<displayValue>Fax</displayValue>

</selectOption>

<selectOption useValue="Mail">

<displayValue>Mail</displayValue>

</selectOption>

<selectOption useValue="Sales Visit">

<displayValue>Sales Visit</displayValue>

</selectOption>

<selectOption UseValue="Special">

<displayValue>Special</displayValue>

</selectOption>

<selectOption UseValue="Telephone">

<displayValue>Telephone</displayValue>

</selectOption>

<selectOption useValue="Web">

<displayValue>Web</displayValue>

</selectOption>

</selectOptions>

</selectValue>

We will name our prompt OrderMethodPrompt.



Open Toolbox.xml. Create a new line: <listItem controlRef="OrderMethodPrompt" value="C" label="Order method

prompt" tooltip="Order method prompt with statis values"/>

Note that the value property is “C”. This is obtained from the default properties of a selectValue prompt object as listed in the Toolbox.xml file. The selectValue object is the basis for the custom value prompt control that was created in Report Studio. Save the Toolbox.xml file. Open ToolboxControls.xml and paste the prompt definition in within the <xmlFragment id="ToolboxControls"> element. Add the id=”OrderMethodPrompt” attribute. <selectValue id=”OrderMethodPrompt” parameter="Order method" required="true" multiSelect="true" range="false" autoSubmit="false" selectValueUI="listBox">

…

</selectValue>

Save this file. Close and re-open Report Studio. Create a list report with:

• \Sales (query)\Order method\Order method:

Create a filter on Order method (note that you must use the same parameter name as specified in the re-useable prompt control in the parameter="Order method" attribute from the ToolboxControls.xml file): [Order method] in (?Order method?)

Add a new prompt page.



Drag the new Order Method Prompt from the Toolbox into the layout of the new prompt page. Run the report. The report is now complete and is using the pre-defined object from the custom Toolbox definition. While this type of modification is not something that a report author would usually require, it will be used as a basis for setting up the content in the next section.



4 Custom Prompt Controls Overview This section discusses the basic functionality behind custom prompt controls followed by some specific prompting examples. The goal is to provide report authors with information on creating custom prompt controls and on using the provided samples. Custom prompt controls can be used when the supplied prompt controls do not meet the reporting requirements. Custom prompt controls can be defined using HTML/JavaScript code embedded in a report prompt page or query page layout to create the desired user experience and supply values to the report expressions. The easy part is supplying values to report expressions. There are three steps required to add a custom prompt to a report:

1. Create the custom prompt control 2. Place the custom prompt control into the prompt page9 3. Set the parameter values

9 Or into a report page as appropriate



4.1 Create the Custom Prompt Control The toughest part of this entire venture is designing and programming a custom prompt control to meet the reporting needs. This portion of creating a prompt control requires HTML/JavaScript programming skills which are not covered within this document but are available through many 3rd party instruction manuals, courses, and online references.

4.1.1 Beer Glass Control The following is an example of a custom prompt control. At run time it appears as so:

This prompt control is obviously far different from anything IBM Cognos supplies in Report Studio. The user can use the buttons to select a higher or lower value using the Drink and Fill buttons.



4.2 Place the Custom Prompt into the Prompt Page This is very easily done. Report Studio provides an HTML object in the Toolbox for just this sort of purpose. The HTML object can contain any HTML/JavaScript code you specify. The code is placed into the prompt page to allow the browser to execute it. If a custom prompt control will be used more than once, it would be worth while to add it into the Report Studio Toolbox as discussed in section 3 and 4. There are some things that should be considered when creating a re-useable custom prompt toolbox items:

1. All prompts must have a unique name – this is accomplished in the JavaScript using an HTML div. The unique name is specified by the report author as discussed in the workshop below.

2. Prompts set parameters – you need a way to pass the parameter name to the custom prompt control

3. The prompt may have additional parameters to set. For example, the Beer Glass prompt allows the Report Studio author to set the high and low values.

Prompts are uniquely identified by placing them into a named HTML div.



4.3 Set the Parameter Values Prompt values are passed to the report as parameters. Parameters are specified in Report Studio filters or calculations using the ?<parameter name>? syntax such as [Country] in ?CountryParm?. In a prompt page, when the Finish button is pressed, parameters are passed to the IBM Cognos 8 BI server as HTML form field variables. In order for the IBM Cognos 8 BI server to differentiate parameter variables from other variables, parameters use the naming convention p_<Parameter name>. Therefore, the parameter CountryName would be passed in the form field variable p_CountryName. This makes it very easy for a custom prompt control to pass a value to the parameter by simply setting a form field variable with the correct name. The prompt control must set the form field variable with the appropriate name to the value specified by the user.



5 Working with the Samples

5.1 Setting Up the Samples 1. Unzip the files into a new directory 2. The bmp and png images are used during report execution. Copy the

bmp and png files to the webcontent\samples\images directory. 3. The gif files are used to create the icons in the Report Studio toolbox.

Copy the gif files to the webcontect\pat\images directory 4. Insert the contents of toolbox.xml into the Toolbox.xml file located at

../c8/webcontent/pat/res. The items should be inserted in the Toolbox_PageView section, immediately after the following lines: <listView id="Toolbox_PageView" classPrefix="clsListItem_tb">

<listItems>

5. Insert the contents of toolboxControls.xml into the toolboxControls file located in the ../c8/webcontent/pat/res directory. The entries should be added immediately after the folloing lines: <resources>


6. Merge reportstudio_en.xml into the same-named file in webcontent/pat/res into the RSB UI section after the line that reads: <section name="RSB" type="UI">

7. Copy the customPromptControls.js file to webcontent\prompting The custom controls are coded in the customPromptControls.js file. The HTML/JavaScript found in toolboxControls.xml is the minimum required to expose the prompt controls in Report Studio. Using an external reference to the Javascript code using the customPromptControls.js allows the code to be updated and propagate the changes to all reports. While it is possible to define the Javascript code within the ToolboxControls.xml file, doing so will result in static Javascript code embedded in each report specification. Updating the code embedded in a report will require a report author to make changes to each of the reports individually.



5.2 Custom Prompt Buttons The custom prompt buttons are really just default prompt buttons with images used in place of text. The following steps will illustrate how to use these new items. Open Report Studio with the GO Sales (query) package. Create a new list report with:

• \Sales (query)\Product\Product line

Select Product line and press the Build Prompt Page toolbar button. A prompt page is created with the default prompt buttons:

Select and delete each of the prompt buttons. Drop a Prompt Button Set into the page footer.



Run the report:

A much nicer set of prompt buttons appears. The Prompt Button Set is actually a standard report Block object with 4 prompt buttons in it. The <contents> of each prompt button have been customized with a table, an image, and some text. Here is a standard Cancel button specification:

<promptButton type="cancel">

<contents/>

<style>

<defaultStyles>

<defaultStyle refStyle="bp"/>

</defaultStyles>

</style>

</promptButton>



Here is the custom Cancel button: <promptButton type="cancel">

<contents>

<table>

<style>

<defaultStyles>

<defaultStyle refStyle="tb"/>

</defaultStyles>

<CSS value="border-collapse:collapse;width:100%"/>

</style>

<tableRows>

<tableRow>

<tableCells>

<tableCell>

<contents>

<image>

<dataSource>

<staticValue>../samples/images/cancel.bmp

</staticValue>

</dataSource>

</image>

</contents>

</tableCell>

<tableCell>

<contents>

<textItem>

<dataSource>

<staticValue>Cancel</staticValue>

</dataSource>

</textItem>

</contents>

</tableCell>

</tableCells>

</tableRow>

</tableRows>

</table>

</contents>

<style>

<defaultStyles>

<defaultStyle refStyle="bp"/>

</defaultStyles>

</style>

</promptButton>



The definition for each of the buttons is part of the standard XML report specification, not custom HTML or JavaScript. The contents of each button are simply defined with a single-row table with two cells. One cell contains and image and the other cell contains the text “Cancel”. IBM Cognos 8 knows how a prompt button behaves, for example when it is enabled and disabled, so there is no need to do any custom programming for the button actions. At run time, the prompt buttons are just another part of the report to be executed using standard IBM Cognos 8 functionality.



5.3 Beer Glass The beer glass control is a custom HTML/JavaScript control that allows a user to select a parameter value by emptying or filling a visual beer glass. The following steps will walk through the process of creating a report using this custom prompt control. Open Report Studio with the GO Sales (query) model. Create a new list report

• \Sales (query)\Order\Order number • \Sales (query)\Sales\Quantity

Sort ascending on Quantity Run the report. Page down and notice that the Quantity values start at 1 and go to much higher values. Return to Report Studio. Create a filter [Quantity] >= ?pQty? Note that the name of the parameter is pQty. Add a prompt page to the report. Drop the Beer Glass Prompt into the new prompt page. You will see an HTML item in your report as so:

Remember that the custom prompt control is written in HTML/JavaScript that is executed by the browser when you run the report. Double click the HTML item to see the HTML source code. This code for the prompt control is not actually in the beer glass prompt toolbox object. Rather, it calls functions in the customPromptsControls.js file to create the prompt.



Access the HTML definition of the HTML item representing the custom prompt control. The individual elements of the prompt control are: Definition Meaning '<script

src="../prompting/customPromptControls.js

"></script>' +

Tells the browser which file the prompt control is in.

Do not change this. '<div id="[BeerGlassContainer1]"></div>' +

The HTML div provides a unique id for referencing the prompt control. Change this only if there are more than one beer glass prompts on the same prompt page so that each control has a unique name.

'<script>beerGlassControl ( The name of the function which creates the prompt. Do not change this.

"[BeerGlassContainer1]", Must match unique id assigned to the div element.

"[BeerGlassParameter1]", The parameter name you used in the report filter of expression.

The default parameter used by the beer glass prompt is [BeerGlassParameter1]10. As we used the parameter pQty in our filter, change this to “pQty”.

Note that the parameter name is case sensitive and must be in double quotes; pQTY will not work.

10 The [ ] are part of the parameter name.



Run the report:

Place the mouse cursor over the Drink or Fill button to change the value to 85. Press the Finish button and notice that the Quantity values have been filtered such that only values greater than 85 show up in the report output.

The report is now complete and the custom prompt allows the report author to tailor the report to needs the business and the consumer. The beer glass prompt JavaScript does some interesting things in terms of emptying and filling the glass. From a prompt perspective the most interesting thing it does is to change the value of the form field variable called p_pQty. Within the JavaScript code, one of the first lines takes the supplied variable name and prepends p_ to it: var sFullParameterName = 'p_' + sParameterName;

When you change the prompt value with the Drink and Fill buttons, the value of this p_pQty form field variable is set. This form variable is passed to the report once the prompt page is submitted using the Finish button.



The remainder of the Javascript simply defines the look and feel of the beer glass image as the drink and fill functions are applied to change the numeric value associated with the prompt control.



5.4 Dynamic Picklist Prompt This custom prompt control appears to be a normal picklist but it has one large difference – it is only populated when the user clicks on the control itself. This allows the prompt page to be displayed very quickly as the prompt query and associated processing are do not need to be processed before rendering the prompt page. This is ideal for prompts which are rarely used. Open Report Studio with the GO Sales (query) package. Create a new list report with:

• \Sales (query)\Product\Product number • \Sales (query)\Product\Product name

Sort ascending on Product number:

Create a new filter with Product number: [Product number] >= ?ProdNum? Note that the name of our parameter is ProdNum. Add a prompt page. Drop a Dynamic Picklist Prompt into the prompt page. The HTML item used to define the custom dynamic picklist control shows up in the report as so:

Remember that the custom prompt control is written in HTML/JavaScript which is processed by the client web browser when the report is executed. Double click the HTML item to see the HTML source code. This code is not actually the prompt. Rather, it calls functions in the customPromptsControls.js file to create the prompt. Definition Meaning '<script Tells the browser which file



src="../prompting/customPromptControls.js

"></script>' + the prompt control is in.

Do not change this. '<div id="[PicklistContainer1]"></div>' + The HTML div provides a

unique name. Change this only if you have more than one dynamic picklist prompts on the same prompt page so that each has a unique id.

'<script>dynamicPickListControl ("' +

ModelPath() + '",

The name of the function which creates the prompt. Do not change this.

"[PicklistContainer1]", Must match unique id defined by for the div element.

"[PicklistParameter1]", The parameter name you used in the report filter of expression.

"[Label]", The text label to display when an actual picklist value is not selected.

"[UseValue]", The model path of the required Use value data item

"[DisplayValue (optional)]" The model path of the optional Display value data item.

);</script>'

Change the parameter name to “ProdNum”. Change the label to “Product name”. To set the UseValue and DisplayValue the model path of the Product number and Product name data items must be determined.



In the Report Studio data tree (left pane model tree), locate the Product query subject:

Right click on Product number and select Properties. Copy the Ref value to the Windows clipboard.

Close the property sheet.



Double click the HTML item and replace the "[UseValue]" with the Ref value: "[Sales (query)].[Product].[Product number]"

Repeat this process to determine the model path for the Product name and use this path for the Display value:

Run the report. The prompt is displayed with the Label value:

At this time, the prompt is not populated. Nor has the prompt query been executed. Click the down arrow. The prompt is populated, the list expands and the report user can choose a value for the prompt control. You may have to scroll down to find the prompt buttons.

5.4.1 How does the Dynamic Picklist Prompt Work This is the most complex example included. The code to fetch the prompt values dynamically is very clever. When you click, the Dynamic Prompt Control JavaScript does the following:

1. Obtain the paths for the Use and Display data items 2. Create a simple XML report specification with a prompt page, a

prompt and a query with the Use and Display items 3. Runs the report specification with a return value of the prompt page

as HTML fragment a. In other words, a JavaScript variable now contains the HTML

for a prompt page. 4. Locate the prompt control in the HTML by identifying the data

between the <selectOptions> and </selectOptions> tags 5. Strip out extraneous characters and convert the HTML elements into

the values for the custom prompt control. 6. Insert these values into the dropdown list



The browser then displays the prompt, the user selects a value, and the p_ProdNum form field variable is set.



5.5 Tab Control Prompt The Tab Control Prompt allows a report author to create a tabbed prompt interface. This is ideal when there are prompts which used infrequently and can be removed from the primary prompt interface. The tabbed interface hides the prompts from view but keeps them within easy reach of the report consumer. The prompts which appear on the second and subsequent tabs are not processed until the user selects the tab. By delaying the execution of the prompt queries there is a reduction in the resources required to produce the prompt page so performance can be improved. The tab control operates using a conditional block driven by the tab selection. The following steps will create a report to illustrate the tabbed prompt interface. Open Report Studio with the GO Sales (query) package. Create a new list report with:

• \Sales (query)\Product\Product line • \Sales (query)\Order method\Order method • \Sales (query)\Sales\Quantity

As so:

Create two filters as so:



Note that the Order method name filter is optional. Create a prompt page. Drop the Tab Control Prompt onto the prompt page. Edit the HTML: Definition Meaning '<script

src="../prompting/customPromptControls.js"></script>' +

Tells the browser which file the prompt control is in.

Do not change this. '<div id="[tabContainer1]"></div>' + The HTML div provides a

unique id for referencing the prompt control. Change this only if you have more than one custom prompt on the same prompt page so that each control has a unique id.

"<script>tabControl ( The name of the function which creates the prompt. Do not change this.

'[tabContainer1]', Must match unique id defined by the div element.

'[tabParameter1]', The parameter name you used in expression of the variable tied to the prompt page conditional block.

['[Tab1]', '[Tab2]', '[Tab3]'], A JavaScript array of tab names. Change the tab names as required. You can specify any number of tab names separated by commas.

'" + (IF (ParamCount('[tabParameter1]') =

0) THEN ('0') ELSE (ParamDisplayValue ('[tabParameter1]'))) +

Tells the function how many tabs are defined in the array. Do not change this.

"');</script>" Ends the script. Do not change this.



Set the Tab names to Product line and Order method: '<script src="../prompting/customPromptControls.js"></script>' +

'<div id="[tabContainer1]"></div>' +

"<script>tabControl ( '[tabContainer1]',

'[tabParameter1]',

['Product line', 'Order method'],

'" + (IF (ParamCount('[tabParameter1]') = 0) THEN ('0') ELSE (ParamDisplayValue ('[tabParameter1]'))) +

"');</script>"

Be sure not to delete the [ ] around the tab names as these denote a JavaScript array. The tabs have now been created. When a user clicks a tab, the value of the parameter called [tabParameter1] is set. The next step is to create a variable using the tab parameter and tie the conditional block to this parameter. In Report Studio, open the Condition Explorer:

Create a new String Variable with the name SelectedTab and the expression: ParamValue('[tabParameter1]')

This ties the variable to the parameter used by the tabbed prompt controls for switching tabs. When a user clicks on a tab this will set the tab parameter value, the variable will then update, and the conditional block will change to reflect the new tab parameter value.



Add the value 1 to the Values list as so:

This really defines two variable values: 1 and Other. Additional tabs can be defined by adding the tab numbers as sequential values in the Values list of the variable. Go to the prompt page. Select the conditional block and set the Block Variable property to SelectedTab. Set the Current Block property to Other. Drop a Value prompt into the Conditional Block. When the Wizard starts, set the parameter to use the existing ProdLine parameter. Click Next. Click Finish (take the default query settings). Set the Current Block property to 1. Drop a Value prompt into the Conditional Block. When the Wizard starts, set the parameter to OrderMethod. Click Next. Click Finish (take the default query settings).



Run the report:

The user can click “Product line” or “Order method” to switch tabs. The Order method prompt is not processed (including running the prompt query) unless the user change tabs. This can both conserve resources and enhance performance. The Tab Header Control Prompt object that was added to the custom toolbox objects works in the same way but the report author must create the conditional block from scratch rather than using the one defined by the Tab Control Prompt toolbox object.




6 Conclusion The Report Studio interface can be updated with custom toolbox objects to simplify report creation and facilitate the distribution of custom prompt controls. These custom prompt controls expand the capabilities of IBM Cognos 8.4 to satisfy a much larger range of business prompting requirements and enhance the end user reporting experience.

Date post:	26-Oct-2014
Category:	Documents
Upload:	ignaciovlb
View:	99 times
Download:	1 times

Cognos Forum 2008 - Advanced Prompting

Documents