Save a Dashboard in the WinForms Designer

  • 5 minutes to read

A dashboard allows you to save a dashboard definition (dashboard items, data source, data binding and layout settings, etc.) to an XML file or to a stream, and restore the dashboard from an XML file or a stream.

Save a Dashboard

Once a dashboard is designed, you can save its definition to the required data store. In the Dashboard Designer, this can be accomplished in the following ways.

  • You can save the dashboard definition by clicking the Save or Save As button in the File group on the Designer ribbon tab.

    SaveButtons

    This invokes the Save As dialog, which allows you to locate the folder in which you wish to store your file.

    Note

    You can handle the DashboardDesigner.DashboardSaving event to implement a custom saving procedure when an end-user clicks one of these buttons, or tries to save the dashboard using a save confirmation dialog.

    Use the Dashboard.SaveToXml method to save the dashboard to an XML file or a stream.

  • The dashboard definition can be saved when the currently opened dashboard is closed (for instance, the window containing the DashboardDesigner is closed, a new dashboard is created or a different dashboard is opened). By default, a save confirmation dialog will be invoked.

    SaveConfirmationDialog

    Use the following methods and properties to manage dialog behavior.

    DashboardDesigner.ActionOnClose

    Gets or sets the required action when the currently opened dashboard is being closed.

    DashboardDesigner.HandleDashboardClosing

    Handles the dashboard close process.

The DashboardDesigner.IsDashboardModified property indicates whether the dashboard has been modified since the last save.

Load a Dashboard

A dashboard definition previously saved to an XML file or a stream can be loaded to the Dashboard Designer.

You can open the dashboard definition by clicking the Open button in the Ribbon menu of the Designer.

OpenButton

This invokes the Open File dialog, which allows you to locate the dashboard XML file.

To load the dashboard in code, use the following members:

DashboardDesigner.LoadDashboard

Loads a dashboard from an XML file.

Dashboard.LoadFromXml

Loads a dashboard from the specified XML file.

After the dashboard is opened, the DashboardDesigner.DashboardFileName property is initialized.

Load Dashboards in the Dashboard Viewer

Use the following members to load a dashboard definition with the Dashboard Viewer:

DashboardViewer.LoadDashboard

Loads a dashboard from a stream.

DashboardViewer.DashboardSource

Gets or sets a dashboard supplier for the DashboardViewer.

See the following topic foe details: Load a Dashboard in the WinForms Viewer.

Implement Custom Saving and Opening Procedures

The following example demonstrates how to implement custom saving and opening procedures in Dashboard Designer.

The Dashboard Designer allows you to override default opening and saving procedures in the following cases:

  • When a user clicks the Open, Save, or Save As buttons in the Ribbon:

    StoringDashboards_FileGroupButtons

  • When a user tries to save the dashboard using the Save Confirmation dialog when the window with the DashboardDesigner is closed.

    SaveConfirmationDialog

To implement custom saving and opening procedures, you need to handle the DashboardDesigner.DashboardSaving and DashboardDesigner.DashboardOpening events.

In this example, the dashboard XML definition can be saved (opened) only to (from) the specified default location.

A custom saving routine is implemented in the DashboardDesigner.DashboardSaving event handler. Its e.Command event parameter allows determining what user action raises the event. The Dashboard.SaveToXml method is used to save the dashboard to the specified XML file. Then, the e.Handled event parameter is used to specify that the dashboard has been saved and no default actions are required.

Clicking the Save As button invokes a message box that allows saving the dashboard to the default location or cancel the saving procedure. The e.Saved event parameter is used to notify whether the custom saving routine has succeeded.

The DashboardDesigner.DashboardOpening event handler implements a custom opening procedure. The DashboardDesigner.LoadDashboard method is called to load the dashboard from the default location. The e.Handled event parameter allows specifying that no default actions are required to open the dashboard.

View Example

using DevExpress.LookAndFeel;
using DevExpress.XtraEditors;
using System.Windows.Forms;

namespace Dashboard_LoadingAndSaving {
    public partial class Form1 : DevExpress.XtraEditors.XtraForm {
        string filePath = @"..\..\Data\DashboardDefinition.xml";

        public Form1() {
            InitializeComponent();
            dashboardDesigner1.CreateRibbon();
        }
        private void dashboardDesigner1_DashboardSaving(object sender, 
            DevExpress.DashboardWin.DashboardSavingEventArgs e) {
            if (e.Command == DevExpress.DashboardWin.DashboardSaveCommand.Save) {
                dashboardDesigner1.Dashboard.SaveToXml(filePath);
                e.Handled = true;
            }
            if (e.Command == DevExpress.DashboardWin.DashboardSaveCommand.SaveAs) {
                DialogResult result = InvokeMessageBox();
                if (result == DialogResult.OK) {
                    dashboardDesigner1.Dashboard.SaveToXml(filePath);
                    e.Handled = true;
                    e.Saved = true;
                }
                if (result == DialogResult.Cancel) {
                    e.Handled = true;
                    e.Saved = false;
                }
            }
        }
        private void dashboardDesigner1_DashboardOpening(object sender, 
            DevExpress.DashboardWin.DashboardOpeningEventArgs e) {
            dashboardDesigner1.LoadDashboard(filePath);
            e.Handled = true;
        }
        public DialogResult InvokeMessageBox() {
            return XtraMessageBox.Show(new UserLookAndFeel(dashboardDesigner1),
                                       "Do you want to save the dashboard to the default location?",
                                       "Save As",
                                       MessageBoxButtons.OKCancel);
        }
    }
}