ReportServer - ReportServer Admin Guide 4.6.1

7.3.8. Script Parameter

The script parameter is a very flexible parameter that basically allows you to write custom HTML and javascript. In order to communicate with ReportServer, ReportServer will call a special JavaScript method that you need to implement and hand over the currently stored value, selected configuration options as well as a callback which allows you to update the value.

When you create a scripting parameter you need to specify a ReportServer script which needs to return an HTML page. You can either create a groovy script or directly write HTML and tell ReportServer that the script is HTML by adding

#html

in the very first line. A script could hence look as follows

#html
<html>
  <head>
  </head>
  <body>
    <div>This is a Script Parameter. Click Me</div>
  </body>
</html>

What is missing from this script is the javascript method expected by ReportServer. For this we add a custom method called initParameter. The initParameter method takes two arguments

params	An object containing various configuration choices as well as the currently selected value.
callback	A callback to update the selected value

The params object contains the following information

editable	Reflects the option whether the parameter is supposed to be editable.
isDefault	true, if the parameter was not yet set.
name	The parameter's name.
mandatory	Whether or not the parameter is mandatory.
key	The parameter's key.
value	The currently selected value.
defaultValue	The specified default value.

The following is a fully functional example. If you click on the text the parameter value is updated. If you then create a variant of the report, you should be prompted with the updated value. Also note the validate method which is called once the user wants to close the parameter view.

#html
<html>
  <head>
    <script type="text/javascript">
			var callback;
			function initParameter(param, cb){
				callback = cb;
				alert("The current value is: " + param.value);
			}
	
			function setValue(value){
			      	alert("Updating the value to: " + value);
			        callback(value);
			}
			
			function validate(){
				return "The parameter is not valid!"
			}
    </script>
  </head>
  <body>
    <div onclick="val = prompt('set new value:', ''); setValue(val);">This is a Script Parameter. Click Me</div>
  </body>
</html>

As a further example, you can use a script parameter for installing a color picker which can be then used in the SQL query as any other parameter. For this purpose, download the latest jscolor javascript file from here: http://jscolor.com/. At the time of writing, the latest version was 2.0.5. Copy the downloaded jscolor.js file into this location: Fileserver Root/lib/jscolor/jscolor.js. Check in the ''Properties'' tab the URL of this file in your installation. It should be something similar to: http://localhost:8080/reportserver/reportserver/fileServerAccess?id=2189950.

Now you can create the script which will be the basis of your script parameter. We name this script PalettePicker.groovy:

#html
<html>
  <head>
    <script type="text/javascript" src="http://localhost:8080/reportserver/reportserver/fileServerAccess?id=2189950"></script>
    <script type="text/javascript">
			var callback;

			function initParameter(param, cb){
				callback = cb;
				//alert("The current value is: " + param.defaultValue);
				document.getElementById("mycolor").value = param.defaultValue;
				document.getElementById("mycolor").style.backgroundColor = '#' + param.defaultValue;
				setValue(param.defaultValue);
			}

			function setValue(value){
				//alert("Updating the value to: " + value);
				callback(value);
			}

    </script>
  </head>
  <body>
    <input id="mycolor" class="jscolor" onchange="setValue(this.value);">
  </body>
</html>

As you can see in the script, you install a color picker and use the default value for setting the initial value and background color of the input field. The URL mentioned previously must be adapted to your configuration:

<script type="text/javascript" src="http://localhost:8080/reportserver/reportserver/fileServerAccess?id=2189950"></script>

Finally, you can create the script parameter in your report and set the script field to point to your PalettePicker.groovy script in your parameter's ''Specific Properties'' dialog. Set your parameter's default value to e.g.: ''FF0000'' (without apostrophes). You can now use the color picker's value in your query as:

SELECT * FROM myTable where myField = ${mycolor}

Note that your parameter's name must be set to ''mycolor'' for using this query.

This approach works for virtually all javascript libraries. Script arguments are a powerful tool for extending ReportServer parameters to user-defined functionality.

Many thanks to Karolina Boboli for sending us this and allowing us to publish the script.

Setting Values

As described above, to set values from within the JavaScript code, you need to call the callback object with the value to be set. Note, that ReportServer expects this value to be of type String. Besides setting a basic string value, you can also return a JSON formatted string. For this, consider the following setValue function:

function setValue(){
        var json = JSON.stringify({
            valA : 'A',
            valInt: 15
      });
      callback(json);
}

Assume that the script parameter has key scriptParam. If the parameter returned a JSON string, then you can access each of the JSON properties via the replacement ParameterKey_PropertyName. That is, you can access the integer value in the above example via ${scriptParam_valInt} and the property valA via ${scriptParam_valInt}. The replacement ${scriptParam} would contain the entire JSON formatted string.