Web Report Designer Initialization

The Telerik Web Report Designer is a jQuery plugin - jQuery.fn.telerik_WebReportDesigner(options). Below is a list of all options available during initialization.

Options

Parameter	Description
id	string, optional; Sets the unique identifier of the WebReportDesigner instance;
serviceUrl	string, required; Sets the URL (relative or absolute) which will provide the service for the web report designer client;
report	string, required; Sets the report that will be initially opened when the web report designer is started;
reportViewerOptions	json, optional; Sets the options of the embedded Report Viewer used when previewing the reports. Here are the currently available options: templateUrl scaleMode scale pageMode viewMode reportSourceParameters Additional information about how these options affect the embedded Report Viewer can be found at the HTML5 Report Viewer Initialization documentation article.
persistSession	boolean, optional; Sets a value indicating whether the designer's client state will be persisted between the page refreshes/postbacks. The state is stored in the browser's sessionStorage and is available for the duration of the page session.
keepClientAlive	boolean, optional; Sets a value indicating whether the client will be kept alive. When set to true a request will be sent to the server to stop the client from expiring, determined by the ClientSessionTimeout server configuration. When set to false, the client will be left to expire;
promptOnDiscardingModifiedReport	boolean, optional; Sets a value indicating whether a browser prompt will be displayed when a report is modified and the user attempts to leave the page.
toolboxArea	json, optional; Sets the Toolbox area options.
propertiesArea	json, optional; Sets the Properties area options.
skipOnboarding	boolean, optional; Sets a value indicating whether the Onboarding Guide should be skipped on startup. If not set or set to false, the Onboarding Guide will check whether it has been run before and if not, it will start after the designer surface has loaded. If the guide has been run before, nothing will happen.
startMode	string, optional; Determines whether the widget will start in design or preview mode.

Events

error Event

The error event will be fired when an error occurs while using design mode in the Web Report Designer. The event was introduced with the R3 2023 release.

$(document).ready(function () {
    $("#webReportDesigner").telerik_WebReportDesigner({
        persistSession: false,
        toolboxArea: {
            layout: "list"
        },
        serviceUrl: "api/reportdesigner/",
        report: "Dashboard.trdp",
        // design/preview
        startMode: "design",
        error: onError
    }).data("telerik_WebReportDesigner");
});

function onError(e, args) {
    // e: jQuery event;
    // args: IErrorEventArgs ->
        // message: error message, string;
        // error: JS's Error instance.

    if (args.error) {
        console.log(`An error occurred! Message: ${args.message}; Error type: ${args.error.constructor.name}`);
    } else {
        console.log(`An error occurred! Message: ${args.message};`);
    }
}

notificationShowing Event

The notificationShowing event will be fired when the user should be notified of an error, warning, etc. while using design mode in the Web Report Designer. The event was introduced with the R3 2023 release.The event may be used to disable the notification pop-up or even display a custom message in the console.

$(document).ready(function () {
    $("#webReportDesigner").telerik_WebReportDesigner({
        persistSession: false,
        toolboxArea: {
            layout: "list"
        },
        serviceUrl: "api/reportdesigner/",
        report: "Dashboard.trdp",
        // design/preview
        startMode: "design",
        notificationShowing: onNotificationShowing
    }).data("telerik_WebReportDesigner");
});

function onNotificationShowing(e, args) {
    // e: jQuery event
    // args: INotificationErrorEventArgs ->
        // type: string, obtained from NotificationTypes. Available values: info, warning, error, success
        // message: notification message, string.
        // error: JS's Error instance
        // cancel: boolean, determines if showing the notification will be canceled.
    switch (args.type) {
        case "success":
        case "info":
        case "warning":
            console.log(`Message: ${args.message}`);
            // disable the notification pop-up.
            args.cancel = true;
            break;

        case "error":
            if (args.error) {
                console.log(`Error message: ${args.message}; Error type: ${args.error.constructor.name}`);
            } else {
                console.log(`Error message: ${args.message};`);
            }
            break;
    }
}

viewerInitializing Event

The viewerInitializing event will be fired when the Web Report Designer widget is first initialized on the page. The event may be used to furthet modify the viewer options and attach event handlers to the events of the report viewer.

$(document).ready(function () {
    $("#webReportDesigner").telerik_WebReportDesigner({
        persistSession: false,
        toolboxArea: {
            layout: "list"
        },
        serviceUrl: "api/reportdesigner/",
        report: "Dashboard.trdp",
        // design/preview
        startMode: "design",
        viewerInitializing: onViewerInitializing
    }).data("telerik_WebReportDesigner");
});

function onViewerInitializing(e, args) {
    // e: jQuery event;
    // args: IViewerPreInitEventArgs ->
    //      reportViewerOptions: report viewer's options. All viewer's options available.

    args.reportViewerOptions.parameters = {
        editors: {
            singleSelect: telerikReportViewer.ParameterEditorTypes.COMBO_BOX,
            multiSelect: telerikReportViewer.ParameterEditorTypes.COMBO_BOX
        }
    };
    args.reportViewerOptions.renderingBegin = onViewerRenderingBegin;
    args.reportViewerOptions.renderingEnd = onViewerRenderingEnd;
}

function onViewerRenderingBegin(e) {
    console.log('TRV rendering begin.');
}

function onViewerRenderingEnd(e) {
    console.log('TRV rendering end');
}

viewerLoading Event

The viewerLoading event will be fired whenever the Web Report Designer widget switches to preview mode and the internal report viewer widget starts loading the current report. The event may be used to set specific viewer options/parameters for a given report, etc.

$(document).ready(function () {
    $("#webReportDesigner").telerik_WebReportDesigner({
        persistSession: false,
        toolboxArea: {
            layout: "list"
        },
        serviceUrl: "api/reportdesigner/",
        report: "Dashboard.trdp",
        // design/preview
        startMode: "design",
        viewerLoading: onViewerLoading
    }).data("telerik_WebReportDesigner");
});

function onViewerLoading(e, args) {
    // e: jQuery event;
    // args: IViewerPreLoadEventArgs ->
    //      reportViewerOptions: report viewer's options. Available options:
    //          reportSource: report viewer's report source.
    //          viewMode: report viewer's view mode.
    //          pageMode: report viewer's page mode.
    setReportParameters(args.reportViewerOptions.reportSource);
    setReportOptions(args.reportViewerOptions);
}

function setReportParameters(reportSource) {
    if (reportSource.report === "Dashboard.trdp") {
        reportSource.parameters = { ReportYear: 2003 };
    }
}

function setReportOptions(reportViewerOptions) {
    const report = reportViewerOptions.reportSource.report;
    if (report === "Product Tag Report.trdp") {
        reportViewerOptions.pageMode = telerikReportViewer.PageModes.CONTINUOUS_SCROLL;
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.PRINT_PREVIEW;
    } else if (report === "Product Catalog.trdp") {
        reportViewerOptions.pageMode = telerikReportViewer.PageModes.SINGLE_PAGE;
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.INTERACTIVE;
    } else if (report === "Dashboard.trdp") {
        reportViewerOptions.pageMode = telerikReportViewer.PageModes.CONTINUOUS_SCROLL;
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.PRINT_PREVIEW;
    } else if (report === "Report1.trdp") {
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.PRINT_PREVIEW;
    }
}

Initialization Example with Full Settings

$(document).ready(function () {
    window.TelerikWebReportDesignerDebugMode = true;
    $("#webReportDesigner").telerik_WebReportDesigner({
        persistSession: false,
        toolboxArea: {
            layout: "list"
        },
        serviceUrl: "api/reportdesigner/",
        report: "Dashboard.trdp",
        // design/preview
        startMode: "design",
        reportViewerOptions: {
            reportSourceParameters: {
                ReportYear: 2002
            },
            scaleMode: "SPECIFIC",
            scale: 1.5,
            viewMode: "INTERACTIVE",
            pageMode: "CONTINUOUS_SCROLL"
        },
        error: onError,
        notificationShowing: onNotificationShowing,
        viewerInitializing: onViewerInitializing,
        viewerLoading: onViewerLoading
    }).data("telerik_WebReportDesigner");
});

function onError(e, args) {
    // e: jQuery event;
    // args: IErrorEventArgs ->
        // message: error message, string;
        // error: JS's Error instance.

    if (args.error) {
        console.log(`An error occurred! Message: ${args.message}; Error type: ${args.error.constructor.name}`);
    } else {
        console.log(`An error occurred! Message: ${args.message};`);
    }
}

function onNotificationShowing(e, args) {
    // e: jQuery event
    // args: INotificationErrorEventArgs ->
        // type: string, obtained from NotificationTypes. Available values: info, warning, error, success
        // message: notification message, string.
        // error: JS's Error instance
        // cancel: boolean, determines if showing the notification will be canceled.
    switch (args.type) {
        case "success":
        case "info":
        case "warning":                    
            console.log(`Message: ${args.message}`);
            // disable the notification pop-up.
            args.cancel = true;
            break;

        case "error":
            if (args.error) {
                console.log(`Error message: ${args.message}; Error type: ${args.error.constructor.name}`);
            } else {
                console.log(`Error message: ${args.message};`);
            }
            break;

    }
}

function onViewerInitializing(e, args) {
    // e: jQuery event;
    // args: IViewerPreInitEventArgs ->
    //      reportViewerOptions: report viewer's options. All viewer's options available.

    args.reportViewerOptions.parameters = {
        editors: {
            singleSelect: telerikReportViewer.ParameterEditorTypes.COMBO_BOX,
            multiSelect: telerikReportViewer.ParameterEditorTypes.COMBO_BOX
        }
    };
    args.reportViewerOptions.renderingBegin = onViewerRenderingBegin;
    args.reportViewerOptions.renderingEnd = onViewerRenderingEnd;
}

function onViewerLoading(e, args) {
    // e: jQuery event;
    // args: IViewerPreLoadEventArgs ->
    //      reportViewerOptions: report viewer's options. Available options:
    //          reportSource: report viewer's report source.
    //          viewMode: report viewer's view mode.
    //          pageMode: report viewer's page mode.
    setReportParameters(args.reportViewerOptions.reportSource);
    setReportOptions(args.reportViewerOptions);
}

function setReportParameters(reportSource) {
    if (reportSource.report === "Dashboard.trdp") {
        reportSource.parameters = { ReportYear: 2003 };
    }
}

function setReportOptions(reportViewerOptions) {
    const report = reportViewerOptions.reportSource.report;
    if (report === "Product Tag Report.trdp") {
        reportViewerOptions.pageMode = telerikReportViewer.PageModes.CONTINUOUS_SCROLL;
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.PRINT_PREVIEW;
    } else if (report === "Product Catalog.trdp") {
        reportViewerOptions.pageMode = telerikReportViewer.PageModes.SINGLE_PAGE;
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.INTERACTIVE;
    } else if (report === "Dashboard.trdp") {
        reportViewerOptions.pageMode = telerikReportViewer.PageModes.CONTINUOUS_SCROLL;
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.PRINT_PREVIEW;
    } else if (report === "Report1.trdp") {
        reportViewerOptions.viewMode = telerikReportViewer.ViewModes.PRINT_PREVIEW;
    }
}

function onViewerRenderingBegin(e) {
    console.log('TRV rendering begin.');
}

function onViewerRenderingEnd(e) {
    console.log('TRV rendering end');
}