How to: Use a Custom Editor for an XtraReport Parameter
- 6 minutes to read
This example demonstrates how to specify a custom control used to edit a report parameter value when a report is being previewed.
Note
Mobile applications do not support the report preview mechanism, so the approach described in this topic cannot be implemented in the Mobile platform.
In this topic, it is assumed that you have an XAF application that uses the Reports V2 Module, and you have created one or more reports (see Reports V2 Module Overview).
Register the Parameter Type
For instance, assume you have a report with the parameterTitle parameter of the TitleOfCourtesy type. Open the code of your report and specify the Parameter.Type value in the report’s constructor.
public partial class XtraReport1 : DevExpress.XtraReports.UI.XtraReport {
public XtraReport1() {
InitializeComponent();
this.parameterTitle.Type = typeof(TitleOfCourtesy);
}
// ...
}
If the registered type is not a standard .NET type (string, int, etc.) and is not used for business object properties, it is also necessary to register this type by using the approach shown in the How to: Register an Additional Type of XtraReport Parameter topic.
Specify a Custom Editor for Parameters of a Standard .NET Type in a WinForms Report Viewer
To provide a custom editor for parameters of a standard type in a Windows Forms application, handle the XtraReport.ParametersRequestBeforeShow event, and assign the custom editor to the ParameterInfo.Editor property of the ParameterInfo object stored in the ParametersRequestEventArgs.ParametersInformation collection. To get an XtraReport instance, handle the ReportDataSourceHelper.BeforeShowPreview event.
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.ReportsV2;
using DevExpress.XtraEditors;
using DevExpress.XtraReports.Parameters;
// ...
public class WinModule : ModuleBase {
public override void Setup(ApplicationModulesManager moduleManager) {
base.Setup(moduleManager);
ReportsModuleV2 module = ReportsModuleV2.FindReportsModule(moduleManager.Modules);
if(module != null) {
module.ReportsDataSourceHelper.BeforeShowPreview += ReportsDataSourceHelper_BeforeShowPreview;
}
}
private void ReportsDataSourceHelper_BeforeShowPreview(object sender, BeforeShowPreviewEventArgs e) {
e.Report.ParametersRequestBeforeShow += (s, arg) => {
foreach(ParameterInfo info in arg.ParametersInformation) {
if(info.Parameter.Name == "parameter1") {
LookUpEdit lookUpEdit = new LookUpEdit();
lookUpEdit.Properties.DataSource = new List<string>(new string[] { "One", "Two"});
info.Editor = lookUpEdit;
}
}
};
}
}
Specify a Custom Editor for Parameters of a Custom Type in a WinForms Report Viewer
Handle the static ReportsWindowsFormsModuleV2.CreateCustomReportDesignRepositoryItem event to specify a custom RepositoryItem used to edit a parameter value when a report is being previewed. Pass your repository item using the handler’s CreateCustomReportDesignRepositoryItemEventArgs.RepositoryItem parameter and set the Handled parameter to true. The specified control will be used for any report in the application.
As the CreateCustomReportDesignRepositoryItem is static, which means that you can access it anywhere in your WinForms project. For instance, you can subscribe to the CreateCustomReportDesignRepositoryItem in the overridden ModuleBase.Setup method of a WinForms module project (in the WinModule.cs (WinModule.vb) file).
using DevExpress.XtraEditors.Repository;
using DevExpress.ExpressApp.ReportsV2.Win;
// ...
public override void Setup(XafApplication application) {
base.Setup(application);
ReportsWindowsFormsModuleV2.CreateCustomReportDesignRepositoryItem +=
delegate(object sender, CreateCustomReportDesignRepositoryItemEventArgs e) {
if(e.Parameter.Name.Equals("parameterTitle")) {
RepositoryItemLookUpEdit item = new RepositoryItemLookUpEdit();
item.NullText = "[Select Title Of Courtesy]";
List<TitleOfCourtesy> st = new List<TitleOfCourtesy>();
st.Add(TitleOfCourtesy.Dr);
st.Add(TitleOfCourtesy.Mrs);
item.DataSource = st;
e.RepositoryItem = item;
e.Handled = true;
}
};
}
Specify a Custom Editor for the HTML5 Report Viewer
This approach is applicable when the HTML5 Document Viewer is used to preview reports (the ReportsAspNetModuleV2.ReportViewerType property is set to HTML5).
Define a custom template for a parameter editor in the Default.aspx file of an ASP.NET application project. (See Providing Custom Editors for Report Parameters)
<script type ="text/html" id="catId-custom-editor">
<div data-bind="dxNumberBox: { value: value, showSpinButtons: true, min: 1, max: 8 }"> </div>
</script>
Handle the ASPxClientWebDocumentViewer.CustomizeParameterEditors event of the Document Viewer’s client-side instance.
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.ReportsV2.Web;
// ...
public class CustomizeReportViewerController : ViewController<DetailView> {
public CustomizeReportViewerController() {
TargetViewId = ReportsAspNetModuleV2.ReportViewDetailViewWebName;
}
protected override void OnActivated() {
base.OnActivated();
ReportWebViewerDetailItem reportViewItem = View.GetItems<ReportWebViewerDetailItem>()[0] as ReportWebViewerDetailItem;
reportViewItem.ControlCreated += delegate (object sender, EventArgs e) {
reportViewItem.ReportViewer.ClientSideEvents.CustomizeParameterEditors =
@"function(s, e) {
if (e.parameter.name == 'parameter1') {
e.info.editor = { header: 'catId-custom-editor' };
}
}";
};
}
}
Specify a Custom Editor for the ASP.NET Report Viewer
This approach is applicable when the ASP.NET Document Viewer is used to preview reports (the ReportsAspNetModuleV2.ReportViewerType property is set to ASP).
Important
In v19.1, the ASP.NET Document Viewer has become deprecated. We recommend that you use the HTML5 Document Viewer in your applications. For this, set the ReportViewerType property to HTML5.
Create a View Controller in the ASP.NET module project. Override the Controller’s OnActivated method, access the WebReportServiceController using the Frame.GetController<ControllerType> method and subscribe to the WebReportServiceController.CustomizeParameterEditors event. Pass your custom control to the handler’s CustomizeParameterEditorsEventArgs.Editor parameter. The specified control will be used for any report in the application.
using DevExpress.Web.ASPxEditors;
using DevExpress.XtraReports.Web;
using DevExpress.ExpressApp;
using DevExpress.ExpressApp.ReportsV2.Web;
// ...
public class CustomReportParametersEditorController : ViewController{
private WebReportServiceController controller;
protected override void OnActivated() {
base.OnActivated();
controller = Frame.GetController<WebReportServiceController>();
if (controller != null) {
controller.CustomizeParameterEditors += delegate(object sender,
CustomizeParameterEditorsEventArgs e) {
if(e.Parameter.Name.Equals("parameterTitle")) {
ASPxComboBox comboBox = new ASPxComboBox();
comboBox.Items.Add("Dr",TitleOfCourtesy.Dr);
comboBox.Items.Add("Mr",TitleOfCourtesy.Mr);
e.Editor = comboBox;
}
};
}
}