Cascading Input Controls and Visualize.js

Cascading Input Controls

In the JasperReports Server, cascading input controls allow a hierarchical selection of parameters for a report, like country -> state -> city. These are usually backed by queries, where selections from parameters higher in the hierarchy are passed to parameters lower in the hierarchy - hence the "cascading". An individual cascading parameter can be either a multi-select or single select. When the JasperReports Server displays cascading input controls, it shows drop down lists for single selects, and a multi-select widget for multiple selects. As cascading values are selected in the UI, the related input controls are refreshed and displayed for selection.

The Visualize.js API allows a developer to interact with the input controls of a report without running a report to get lists of valid values. With a cascading set of controls, you pass in sets of values to get the results for the next level down. For example:

With a set of country/state/city input controls, the first Visualize call to get the input control metadata will get the list of cities.

var inputControls = visualizeObj.inputControls({
        resource: reportUri,
        success: getCityInputControlValues
    });

function getCityInputControlValues(data) {
    // Find the City input control
    var countryInputControl = _.findWhere(data, {
        id: "Country"
    });
    // Extract data from the input control
    _.each(countryInputControl.state.options, function (option) {
      // option.value - what will be returned to the report and other input controls
      // option.label - display value for the user
      // option.selected - is this option selected, based on prior operations
    });
}

Now you have selected some Countries, and you want to get the States for the selection. You can reuse the visualize inputControls variable.

// If you have a multi-select parameter, you can pass an array...
var paramObj = { "City": ["Canada", "USA"] };
inputControls.params(paramObj).run(
				function(data) {
          var stateInputControl = _.findWhere(data, {
              id: "State"
          });
          // Extract data from the input control
          _.each(stateInputControl.state.options, function (option) {
            ...
          });
				}
);

After selecting States, you can get the Cities the same way.

// If you have a multi-select parameter, you can pass an array...
var paramObj = { "City": ["Canada", "USA"], "State": ["CA", "Ontario"] };
inputControls.params(paramObj).run(
				function(data) {
          var cityInputControl = _.findWhere(data, {
              id: "City"
          });
          // Extract data from the input control
          _.each(cityInputControl.state.options, function (option) {
            ...
          });
				}
);

To run reports and dashboards, you can pass in parameters with the same structure as the "params" for input controls. The values you send to reports and dashboards do not have to come from the input controls related to the report/dashboard.