Configuring Cascading Input Controls Activity

 

 

 

Step

Action

1. 

Note: Create a report that displays information about stores in the country and states specified by the user.

 

This type of report is best served by cascading input controls.

2. 

Begin by opening a new report template in iReport.

 

Click the File menu.

3. 

Click the New menu item.

4. 

Note: Blank A4 is the default report template, and the correct one for this activity.

5. 

Click the Open this Template button.

6. 

Click to delete the default text.

7. 

Enter "store_report" into the Report name field.

8. 

Click the Next button.

9. 

Click the Finish button to open the store_report template.

10. 

Note: The store_report template opens and is ready for editing.

11. 

Note: Report data is pulled from the sample foodmart database that ships with JasperReports Server.

12. 

Now, configure two parameters required by the input controls.

 

In the Report Inspector panel, right-click the Parameters tree item.

13. 

Click the Add Parameter menu item.

14. 

Note: New parameters appear below the default parameters at the bottom of the list.

15. 

Note: The Properties panel is where parameters and other elements are configured. If the Properties panel is not visible, click the Window menu and select the Properties panel.

16. 

In the Properties panel, click in the Name field to select the default parameter name.

17. 

Enter "country" into the Name field.

18. 

Note: The country parameter accepts one country name.

 

A single name or word is called a String in programming languages.

19. 

Make sure the country parameter is of type String.

 

Click the Parameter Class button with the ellipsis (three dots) on it.

20. 

Note: java.lang.String is the correct datatype.

21. 

Click the OK button.

22. 

Note: When the report executes, a small window will appear to prompt the user to select a country name.

23. 

Create a second parameter that prompts the user for state names.

 

In the Report Inspector, right-click the Parameters tree item.

24. 

Click the Add Parameter menu item.

25. 

In the Properties panel, click in the Name field to select the default text.

26. 

Enter "state_list" into the Name field.

27. 

Click the Parameter Class list drop-down button.

28. 

Note: The input control allows the user to select multiple state names.

 

The Java type for multiple selections is Collection.

29. 

Click the java.util.Collection list item.

30. 

Note: The user is also prompted to enter state names, so leave the Use as a prompt option selected.

31. 

Note: Two parameters are configured.

 

The first accepts a country name, and the second accepts the names of states in that country.

32. 

Next, configure the query that retrieves data from the database.

 

Click the Query button, to the right of the Preview button.

33. 

Note: The Report query wizard appears. 

 

Enter a query manually, or use the Query designer to assist you.

34. 

Click the Query designer button.

35. 

Note: The query designer window appears.

 

The query designer interface lets you click and drag to create a query.

36. 

At the left of the Tables list, click the schema list to select the appropriate database schema.

37. 

The sample data is associated with the public schema.

 

Click the public list item.

38. 

Note: The public schema consists of dozens of tables, displayed in the lower-left pane.

39. 

Double-click the store table name to add the table to the query.

40. 

 Note: The table appears with all fields selected by default.

41. 

Note: The query is automatically written and appears in the upper-left pane.

42. 

This activity uses only five of the fields.

 

Click the store button near the top of the table.

43. 

Click the deselect all menu item.

44. 

Note: All fields are deselected, and the SELECT clause in the query in the upper-left pane is empty.

45. 

Select the five fields you need.

 

Click the store_name option.

46. 

Click four more options:

store_city, store_state, store_country, and store_manager.

47. 

Click the store_state option.

48. 

Click the store_country option.

49. 

Click the store_manager option.

50. 

Note: The five fields are referenced in the SELECT clause in the query.

51. 

Note: Configure WHERE clauses, GROUP BY clauses, and other query options in the query design window.

52. 

Click the OK button to save the query design and return to the Report query window.

53. 

Note: The query appears in the first pane.

 

The SELECT and FROM clauses are complete.

54. 

Note: Names of the parameters you configured appear in the Available parameters pane at the right.

 

Double-click to add them to the query, or enter their name manually into the query.

55. 

Note: The fields are represented in the bottom pane when the query contains no typos or syntax errors.

56. 

Next, enter a WHERE clause that references both parameters.

 

Enter "WHERE store_country = $P{country} AND $X{IN, store_state, state_list}" below the FROM clause.

57. 

Enter "WHERE store_country = $P{country} AND $X{IN, store_state, state_list}" into the field.

58. 

Note: In the WHERE clause, $P{country} is replaced by the country name selected by the report user.

59. 

Note: The second part of the WHERE clause includes the $X syntax.

 

$X consists of three values:

1. The operator IN

2. The database field name store_state

3. The parameter name state_list

 

The $X syntax completes the WHERE clause by specifying the store_state names that are IN the collection of state names passed in to the state_list parameter.

60. 

Next, add an ORDER BY clause.

 

Click in the query field to insert the cursor below the WHERE clause.

61. 

Enter "ORDER BY store_country, store_state, store_name" into the field.

62. 

Note: Records returned to the report are ordered first by country name.

 

Multiple records for a country are ordered by state name, and multiple records for a state are ordered by store name.

63. 

Note: The query is complete.

 

It retrieves five pieces of information for stores that are in the country and states specified by the report user, and orders those records in an organized manner.

64. 

Click the OK button to save the query and exit the query wizard.

65. 

Next, specify a default value for the country parameter.

 

Click the country parameter in the Report Inspector panel.

66. 

In the Properties panel, click the Default Value Expression button to open the expression editor.

67. 

Note: The expression editor helps you configure expressions for parameters, variables, text fields, and other kinds of objects.

68. 

The sample foodmart database includes records from three countries: Canada, Mexico, and the U.S.A.

 

Enter ""USA"" into the field, including double quotation marks.

69. 

Click the OK button to save the expression and close the editor.

70. 

Note: USA is the default selection for the country parameter. When the report runs, users are free to select Canada or Mexico.

71. 

Now, add content to the report template.

 

In the Report Inspector panel, view the Parameters node.

72. 

Collapse the Parameters node.

73. 

Note: The template in the design area is divided into horizontal sections called bands.

 

This report needs only three of them, so hide the unnecessary bands.

74. 

Hide all bands but Title, Column Header, and Detail.

 

In the Report Inspector panel, click to select the Page Header band.

75. 

Press the [Ctrl] key and click the Column Footer, Page Footer, Summary, and Background bands to select all of them.

76. 

Press the [Ctrl] key and click the Page Footer band.

77. 

Press the [Ctrl] key and click the Summary band.

78. 

Press the [Ctrl] key and click the Background band.

79. 

Note: The five bands are selected.

 

80. 

Right-click the Background band.

81. 

Click the Delete Band menu item to hide the five bands.

82. 

Note: The Title, Column Header, and Detail bands remain active.

83. 

Now, drag a Text Field from the Palette to the center-top of the Title band.

84. 

Note: A Text Field allows you to print text, a number, or a date created by a programmatic expression.

 

Expressions in iReport can be written in Java or Groovy. Both languages require you to wrap text in double quotation marks.

85. 

Double-click the Text Field to select it for editing.

86. 

Enter ""Store List Report"" into the field, including the double quotation marks.

87. 

Note: The title of the report appears as Store List Report.

88. 

Next, add the five fields to the template.

 

In the Report Inspector, expand the Fields node.

89. 

Click and drag the store_store_name field into the upper-left corner of the Detail band.

90. 

Note: The field is added to the Detail band and a column header (column title) text box is automatically included directly above in the Column Header band.

91. 

Drag the city, state, country, and manager fields into the template so all five text fields are aligned and evenly spaced across the top of the Detail band.

92. 

Release the mouse button.

93. 

Release the mouse button.

94. 

Release the mouse button.

95. 

Note: The five fields appear side by side in the Detail band.

 

 

Some field names may be visible because the names are short enough to display fully in the text box.

96. 

Note: Each field has a header in the Column Header band.

97. 

Now, edit the column headers to make their text more presentable.

 

Double-click the store_store_name header to select the text for editing.

98. 

Enter "Store" into the field.

99. 

Edit the remaining four headers to Manager, City, State, and Country.

100. 

Enter a valid value e.g. "Manager" into the  field.

101. 

Double-click the.

102. 

Enter a valid value e.g. "City" into the  field.

103. 

Double-click the.

104. 

Enter a valid value e.g. "State" into the  field.

105. 

Double-click the.

106. 

Enter a valid value e.g. "Country" into the  field.

107. 

Click the.

108. 

Note: The text of all five headers is modified for usability.

109. 

Now, preview the report to see how it looks.

 

Click the Preview button.

110. 

Note: The first of two Parameter prompt windows appears.

 

Specify Canada or Mexico and click OK, or click Use default to specify USA, which is the default value you configured earlier.

111. 

Click the Use default button to specify USA.

112. 

Note: The sample data includes records for three states in the USA: Washington, Oregon and California.

 

Specify state values in this window any of three ways:

1. Enter the value WA, OR, or CA to specify one state

2. Enter a comma-separated list of two or more values in any order

3. Click the Use default button to specify all states of the selected country

113. 

Click the Use default button to specify all states of the selected country.

114. 

Note: The report executes and displays in iReport.

115. 

Click the Designer button to return to design mode.

116. 

Note: Task 1, Create a report with two parameters in iReport, is complete.

117. 

Next, open the Repository Navigator panel and deploy the finished report template to the JasperReports Server repository.

 

Click the Window menu.

118. 

Click the JasperReports Server Repository menu item to open the Repository Navigator panel.

119. 

Configure a connection from iReport to the repository database.

 

Click the Add new server button.

120. 

The ID value appears in the Repository Navigator panel as the connection label or name.

 

Enter "LocalHost" into the ID field.

121. 

Enter "organization_1" into the Organization field.

122. 

Enter "jasperadmin" into the Username field.

123. 

Enter "jasperadmin" into the Password field.

124. 

Click the Save button to save the connection and display it in the panel.

125. 

Expand the LocalHost node.

126. 

Note: The folder tree mirrors that found in JasperReports Server.

127. 

Deploy the Store List Report to the repository Public folder.

 

Right-click the Public folder.

128. 

Click the Add > JasperServer Report menu item.

129. 

Note: The ReportUnit Wizard appears.

 

Specify the Resource ID and name of the report, identify the report template you want to deploy, and specify the report data source.

130. 

Note: ID is the value the system uses to manage the resource, and Name is the report file name that displays when you view the contents of the folder in which the report is stored.

131. 

Enter "store_report" into the ID field.

132. 

Enter "Store List Report" into the Name field.

133. 

Enter "example report with cascading input controls" into the Description field.

134. 

Click the Next button.

135. 

On this page, identify the report you want to deploy. The Store List Report is currently open.

 

Click the Get source from current opened report button.

136. 

Click the Next button.

137. 

The report data source is a resource in the repository.

 

Click the From the repository option.

138. 

The drop-down list automatically populates with repository data sources.

 

Click the Data Source list.

139. 

Click the FoodmartDataSourceJNDI list item.

140. 

Click the Finish button to deploy the report to the repository.

141. 

Now, view the contents of the Public folder to see that the report deployed properly.

 

Expand the Public folder.

142. 

Note: A folder displays in the Repository Navigator for each report deployed to the repository.

 

Task 2, Deploy the report to the JasperReports Server repository, is complete.

143. 

Next, log into JasperReports Server and create the cascading input controls.

 

Open the JasperReports Server login page.

144. 

Enter "jasperadmin" into the User ID field.

145. 

Enter "jasperadmin" into the Password field.

146. 

Click the Login button to enter JasperReports Server.

147. 

Retrieve the report you created.

 

Enter "Store List Report" into the Search field.

148. 

Click the Search button.

149. 

Execute the report to make sure it works properly in JasperReports Server.

 

Click the Store List Report link.

150. 

Note: The report displays records for USA because you specified USA as the default country in iReport.

 

The report executes properly and displays records for all USA states in the sample data.

151. 

Now, configure input controls for the report.

 

Click the Back button to return to the Search Results page.

152. 

Right-click the Store List Report link.

153. 

Click the Edit menu item.

154. 

Note: The Edit Report wizard appears.

155. 

Click the Controls & Resources tab.

156. 

Note: The Input Controls list is empty because no controls are configured yet for this report.

157. 

Configure the country input control.

 

Click the Add Input Control link.

158. 

Click the Define an Input Control option.

159. 

Click the Next button.

160. 

Click the Type drop-down list.

161. 

The country input control is query driven and lets users select one country name.

 

Click the Single-select Query list item.

162. 

Prompt Text serves as the control label.

 

Enter "Country" into the Prompt Text field.

163. 

The Parameter Name value must be spelled identically to the parameter you created in iReport. You named the parameter country.

 

Click in the Parameter Name field to delete the text

164. 

Note: The wizard reminds you that a Parameter Name value is required.

165. 

Enter "country" into the Parameter Name field.

166. 

Click the Mandatory option to require the user to select a country name in the input control.

167. 

Click the Next button.

168. 

Note: The required query does not exist in the repository, so you need to define it.

 

The default selection here is correct.

169. 

Click the Next button to configure the query.

170. 

Enter "country_query" into the Name field.

171. 

Click the Next button.

172. 

Click the Select data source option.

173. 

Click the Browse button to select a data source.

174. 

In the Select Data Source window, drill down to find the data source.

 

Expand the Analysis Components folder.

175. 

Expand the Analysis Data Sources folder.

176. 

Click the Foodmart Data Source JNDI list item.

177. 

Click the Select button.

178. 

Note: The query data source is identified.

179. 

Now, write the query.

 

Click the Next button.

180. 

Note: SQL is the correct query language.

181. 

Enter the query into the Query String field.

 

Enter "SELECT DISTINCT store_country FROM store ORDER BY store_country".

182. 

Note: The query retrieves one instance of each country name from the store table and orders them alphabetically.

183. 

Click the Save button to move to the parameters page.

184. 

Value Column is the field value passed to the report.

 

Enter "store_country" into the Value Column field.

185. 

Visible columns are the field values that appear in the input control.

 

Enter "store_country" into the Vislble Columns field.

186. 

The Visible Columns entry must be committed.

 

Click the Add link to commit the entry.

187. 

Click the Submit button to save the input control configuration and return to the Controls & Resources page.

188. 

Note: The Country input control is saved.

189. 

Now, configure the state input control.

 

Click the Add Input Control link.

190. 

Click the Define an Input Control option.

191. 

Click the Next button.

192. 

Click the Type drop-down list.

193. 

The state input control is query driven and lets the user select one or more states.

 

Click the Multi-select Query list item.

194. 

Enter "Select zero, one, or multiple states" into the Prompt Text field.

195. 

The Parameter Name value must match the spelling of the parameter you created in iReport.

 

Click to delete the text.

196. 

Enter "state_list" into the Parameter Name field.

197. 

Note: As you saw in iReport, when no state names are specified, the query returns records for all states of the selected country.

 

Leave the Mandatory option unchecked.

198. 

Click the Next button to configure the input control query.

199. 

Note: The required query does not exist in the repository, so define it. The default selection here is correct.

200. 

Click the Next button.

201. 

Enter "state_query" into the Name field.

202. 

Click the Next button to specify the data source.

203. 

You want the same JNDI data source assigned to the first control.

 

Click the Select data source option.

204. 

Click the Browse button to find the data source.

205. 

Expand the Analysis Components folder.

206. 

Expand the Analysis Data Sources folder.

207. 

Click the Foodmart Data Source JNDI list item.

208. 

Click the Select button.

209. 

Note: The data source is selected.

210. 

Click the Next button.

211. 

This query retrieves the names of states in the country selected in the first control and orders them alphabetically.

 

Enter "SELECT DISTINCT store_state FROM store WHERE store_country = $P{country} ORDER BY store_state".

212. 

Note: store_country = $P{country} identifies the country name specified by the user in the first input control.

213. 

Note: The name of each state in the specified country is retrieved by the query for display in the second input control.

214. 

Note: The state names are ordered alphabetically in the input control.

215. 

Click the Save button to move to the parameters page.

216. 

Enter "store_state" into the Value Column field.

217. 

Enter "store_state" into the Visible Columns field.

218. 

Click the Add link to commit the Visible Columns value.

219. 

Click the Submit button to save the input control configuration and return to the Controls & Resources page.

220. 

Note: The country and state controls are configured.

221. 

Click the Submit button to commit all changes to the report and exit the Edit Report wizard.

222. 

Task 3, Configure the cascading input controls in JasperReports Server, is complete.

 

Next, execute the report to review the input controls.

 

Click the Store List Report link.

223. 

Note: The Input Controls window appears.

 

Both controls are labeled as you specified.

224. 

Note: The asterisk indicates that selecting a value is mandatory.

225. 

Note: USA appears because you specified it as the default choice when you created the country parameter in iReport.

226. 

Now, select a different country.

 

Click the Country list.

227. 

Click the Mexico list item.

228. 

Note: The country input control passed the country value to the second control query and it returned the states of Mexico, ordered alphabetically as the query specifies.

229. 

Select multiple state names.

 

Click the DF list item.

230. 

Press the [Ctrl] key and click the Jalisco list item.

231. 

Press the [Ctrl] key and click the Zacatecas list item.

232. 

Note: Click the Apply button to execute the report and leave the Input Controls window open.

 

Click OK to execute the report and close the window.

233. 

Click the OK button.

234. 

Note: The input control values are passed to the report query you configured in iReport during Task 1, and the report displays records for the specified Mexican states.

 

Task 4, Execute the report and filter its display with the input controls, is complete.

235. 

Click the Log Out link to exit JasperReports Server and end the session.

236. 

Congratulations!

 

You completed the following four tasks:

 

1. Create a report with two parameters in iReport

2. Deploy the report to the JasperReports Server repository

3. Configure the report cascading input controls in JasperReports Server

4. Execute the report and filter its display with the input controls

End of Procedure.