API Reference - inputControls

The inputControls function prepares and displays input controls for reports your users interact with.

This chapter contains the following sections:

Input Control Properties
Input Control Functions
Input Control Structure
Fetching Input Control Data
Creating Input Control Widgets
Cascading Input Controls
Reusing Input Control Instances
Reusing Input Control Data

Input Control Properties

The properties structure passed to the inputControls function is defined as follows:

{
    "type": "object",
    "properties": {
        "server": {
            "type": "string",
            "description": "Url to JRS instance."
        },
        "resource": {
            "type": "string",
            "description": "URI of resource with input controls.",
            "pattern": "^/\\w*(/\\w+)*$"
        },
        "params": {
            "type": "object",
            "description": "Parameters for input controls.",
            "additionalProperties": {
                "type": "array"
            }
        }
    },
    "required": ["server", "resource"]
}

Input Control Functions

The InputControls function exposes the following functions:

define(function () {
 
    /**
     * Constructor. Takes properties as argument.
     * @param properties - map of properties.    
     */
    function InputControls(properties){};
 
    /**
     * Get/Set 'resource' property - URI of resource with input controls.
     * @param value - new value, optional
     * @returns this if 'value' sent to the method,
     *          otherwise returns current value of the parameter
     */
    InputControls.prototype.resource = function(value){};
 
    /**
     * Get/Set 'params' property - Parameters for input controls.
     * @param value - new value, optional
     * @returns this if 'value' sent to the method,
     *          otherwise returns current value of the parameter
     */
    InputControls.prototype.params = function(value){};  
 
    return InputControls;
});

Input Control Structure

InputControls data() is an array of InputControl objects, with the structure shown in this example:

[
  {
    "id":"Cascading_name_single_select",
    "label":"Cascading name single select",
    "mandatory":"true",
    "readOnly":"false",
    "type":"singleSelect",
    "uri":"repo:/reports/samples/Cascading_multi_select_report_files/Cascading_name_single_select",
    "visible":"true",
    "masterDependencies": {
      "controlId": [
        "Country_multi_select",
        "Cascading_state_multi_select"
      ]
    },
    "slaveDependencies":null,   
    "validationRules": [
      {
        "mandatoryValidationRule" : {
          "errorMessage" : "This field is mandatory so you must enter data."
        }
      }
    ],
    "state": {
      "uri": "/reports/samples/Cascading_multi_select_report_files/Cascading_name_single_select",
      "id": "Cascading_name_single_select",
      "value": null,
      "options": [
        {
          "selected": false,
          "label": "A & U Jaramillo Telecommunications, Inc",
          "value": "A & U Jaramillo Telecommunications, Inc"
        }
      ]
    }              
  },
  ....
]

Fetching Input Control Data

The data being output here has the input control structure shown in the previous section:

visualize(function(v){
    var ic = v.inputControls({
        resource: "/public/ReportWithControls",
        success: function(data) {
           console.log(data);
        }
    });
});

This example shows an alternate way of fetching input controls:

(new InputControls({
    server: "http://localhost:8080/jasperserver-pro",
    resource: "/public/my_report",
    params: {
        "Country_multi_select":["Mexico"],
        "Cascading_state_multi_select":["Guerrero", "Sinaloa"]
    }
})).run(function(inputControlsArray){
    // results here
})

Creating Input Control Widgets

This example retrieves the input controls of a report and parses the structure to create drop-down menus of values for each control:

visualize({   
    auth: {
        name: "superuser",
        password: "superuser"
    }
},function(v) {
 
    v.inputControls({
        resource: "/public/Samples/Reports/16g.InteractiveSalesReport",
        success: function (controls) {
            controls.forEach(buildControl);
        },
        error: function (err) {
            alert(err);
        }
    });
 
    function buildControl(control) {
 
        function buildOptions(options) {
            var template = "<option>{value}</option>";
            return options.reduce(function (memo, option) {
                return memo + template.replace("{value}", option.value);
            }, "")
        }
 
        var template = "<label>{label}</label><select>{options}</select><br>",
            content = template.replace("{label}", control.label)
                .replace("{options}", buildOptions(control.state.options));
 
        $("#container").append($(content));
    }
 
});

Cascading Input Controls

In order to implement cascading input controls, you must implement a change listener on the parent control and use it to trigger an update on the dependent control:

var reportUri = "/public/Samples/Reports/Cascading_Report_2_Updated";
 
visualize({
    auth: {
        name: "superuser",
        password: "superuser"
    }
}, function (v) {
    var inputControls = v.inputControls({
        resource: reportUri,
        success: renderInputControls
    });
 
    var report = v.report({ resource: reportUri, container: "#container" });
 
    $("#productFamilySelector").on("change", function() {
        report.params({ "Product_Family": [$(this).val()] }).run();
    });
});
function renderInputControls(data) {
    var productFamilyInputControl = _.findWhere(data, {id: "Product_Family"});
    var select = $("#productFamilySelector"); 
    _.each(productFamilyInputControl.state.options, function(option) {
        select.append("<option " + (option.selected ? "selected" : "") + " value='" +
                        option.value + "'>" + option.label + "</option>");
    });
}

Associated HTML:

<script src="http://code.jquery.com/jquery-2.1.0.js"></script>
<script src="http://underscorejs.org/underscore-min.js"></script>
<script src="http://bi.example.com:8080/jasperserver-pro/client/visualize.js"></script>
<select id="productFamilySelector"></select>
<div id="container"></div>

Reusing Input Control Instances

Input controls are meant to be dynamic and modified by users. By using the inputControls.params function, you can update the values of input controls and then update the corresponding report.

var inputControls = new InputControls({
    server: "http://localhost:8080/jasperserver-pro",
    resource: "/public/my_report"
});
 
// call 1
inputControls.params({ "Country_multi_select": ["Mexico"] }).run(doSomethingWithResultFunction);
...
// call 2 after some time
inputControls.params({ "Country_multi_select": ["USA"] }).run(doSomethingWithResultFunction);

Reusing Input Control Data

You can store the data from the inputControls function and access the data() structure at a later time:

var call = (new InputControls({
    server: "http://localhost:8080/jasperserver-pro",
    resource: "/public/my_report"
})).run(function(inputControlsArray){
    // data() available here
});
 
// at this point call.data() will return null until the run callback is called.  
call.data() === null // -> true 
...
// if some data was obtained earlier, it accessible via data()
var inputControlsArray = call.data();
Version: 
Feedback
randomness