New to Telerik Reporting? Start a free 30-day trial

Custom Parameter Editors in the HTML5 Report Viewer

The article elaborates on how to change the default editors for visible parameters in the HTML5 Viewer's Parameters Area.

Custom parameter editors are defined through the parameterEditors (Report Viewer Initialization) array passed as an option when creating the report viewer widget. Each object represents a parameter editor factory for creating editors suitable to edit a specific report parameter configuration.

Each editor is an object which contains two methods: match and createEditor.

The match method accepts a report parameter to be edited as an argument and returns a boolean value which indicates whether the parameter editor is suitable for this parameter. The parameter variable exposes the properties of the report parameter like name, allowNull, availableValues, multiValue, type, etc.

The main work for creating and utilizing the parameter editor is done in the createEditor method. Its purpose is to create the parameter editor UI and wire it to the parameterChanged callback when a new value is selected. The return result is a new object containing the following methods:

beginEdit(param) - (Required) The entry point for creating the editor. Receives the report parameter object and should initialize the editor UI with the parameter's current value and available values.
addAccessibility(param) - (Required when enableAccessibility is true) Called after beginEdit to configure accessibility attributes (e.g., aria-label) on the editor element. The param argument is the report parameter. If this method is missing and accessibility is enabled, the parameters area will fail to render.
setAccessibilityErrorState(param) - (Required when enableAccessibility is true) Called when the parameter value changes to update the accessibility error state on the editor element. The param argument is the report parameter and its Error property contains the validation error (if any). If this method is missing and accessibility is enabled, changing parameter values will produce console errors.

The following example illustrates how to use the Kendo DropDownList widget for a single parameter value parameter editor which also has available values:

JavaScript

{
	match: function (parameter) {
		// Here you can use all of the parameter properties to
		// create a more specific editor
		return Boolean(parameter.availableValues) && !parameter.multivalue;
	},
	createEditor: function (placeholder, options) {
		var dropDownElement = $(placeholder).html('<div></div>');
		var parameter,
			valueChangedCallback = options.parameterChanged,
			dropDownList;
		function onChange() {
			var val = dropDownList.value();
			valueChangedCallback(parameter, val);
		}
		return {
			beginEdit: function (param) {
				parameter = param;
				$(dropDownElement).kendoDropDownList({
					dataTextField: "name",
					dataValueField: "value",
					value: parameter.value,
					dataSource: parameter.availableValues,
					change: onChange
				});
				dropDownList = $(dropDownElement).data("kendoDropDownList");
			},
			addAccessibility: function (param) {
				if (dropDownList) {
					dropDownList.wrapper.attr("aria-label", param.text + ". Drop-down list parameter.");
				}
			},
			setAccessibilityErrorState: function (param) {
				if (dropDownList) {
					if (param.Error) {
						dropDownList.wrapper.attr("aria-invalid", "true");
					} else {
						dropDownList.wrapper.removeAttr("aria-invalid");
					}
				}
			}
		};
	}
}

Passing the parameter editor to the viewer:

JavaScript

<script type="text/javascript">
	$("#reportViewer1").telerik_ReportViewer({
		parameterEditors: [{
			match: function (parameter) {
				return Boolean(parameter.availableValues) && !parameter.multivalue;
			},
			createEditor: function (placeholder, options) {
				var dropDownElement = $(placeholder).html('<div></div>'),
					parameter,
					valueChangedCallback = options.parameterChanged,
					dropDownList;
				function onChange() {
					var val = dropDownList.value();
					valueChangedCallback(parameter, val);
				}
				return {
					beginEdit: function (param) {
						parameter = param;
						$(dropDownElement).kendoDropDownList({
							dataTextField: "name",
							dataValueField: "value",
							value: parameter.value,
							dataSource: parameter.availableValues,
							change: onChange
						});
						dropDownList = $(dropDownElement).data("kendoDropDownList");
					},
					addAccessibility: function (param) {
						if (dropDownList) {
							dropDownList.wrapper.attr("aria-label", param.text + ". Drop-down list parameter.");
						}
					},
					setAccessibilityErrorState: function (param) {
						if (dropDownList) {
							if (param.Error) {
								dropDownList.wrapper.attr("aria-invalid", "true");
							} else {
								dropDownList.wrapper.removeAttr("aria-invalid");
							}
						}
					}
				};
			}
		}]
	});
</script>

You can use any other custom UI covering the requirements of the createEditor method.

Custom Parameter Editors in the HTML5 Report Viewer

See Also