Spreadsheet Document API, Spreadsheet Controls (Win and WPF) — Import Chart Setting from CRTX Template Files (v23.2)

In our v23.2 release cycle, we've introduced a series of Spreadsheet Chart control enhancements. We've already described error bars, rotated axis labels, and rich text formatting for Chart titles and Axis titles in a previous blog post: Spreadsheet Document API, Spreadsheet Controls (Win and WPF) — Chart Enhancements (v23.2). In this post, I’ll explain how to apply an existing Excel chart template (.crtx file) for a generated chart object.

As you may know, CRTX is a special file format that describes chart content. It is a package of XML files that store colors, axes, series, gridlines, categories, legends, text, and other chart settings/options. You can save a customized chart layout as a chart template file (.crtx) in Microsoft Excel, Outlook, PowerPoint, or Word. Select the Save as Template command when you click on a chart and specify a name/location for your chart template file. Once saved, you can share the template among different machines/applications to apply the chart appearance you designed.

We extended our Spreadsheet Document API with new methods that allow you to import and apply chart settings from chart template files. The AddFromTemplate method creates a chart from a template. The LoadTemplate method applies template settings to an existing chart. This new functionality allows you to use the chart (saved as a template) as the basis for other similar charts or apply predefined chart styles to all charts within a document.

The following examples create two charts and apply settings stored in a template with both LoadTemplate and AddFromTemplate methods.

// ...
spreadsheetControl1.LoadDocument("Document.xlsx");
IWorkbook workbook = spreadsheetControl1.Document;
workbook.Worksheets.ActiveWorksheet = workbook.Worksheets["Sheet2"];

// Create a chart, bind it to data, and locate in a Worksheet.
DevExpress.Spreadsheet.Charts.Chart chartProductSales = spreadsheetControl1.ActiveWorksheet.Charts.Add(ChartType.ColumnClustered);
chartProductSales.TopLeftCell = spreadsheetControl1.ActiveWorksheet.Cells["F1"];
chartProductSales.BottomRightCell = spreadsheetControl1.ActiveWorksheet.Cells["K12"];
chartProductSales.Series.Add(spreadsheetControl1.ActiveWorksheet["A1:A4"], spreadsheetControl1.ActiveWorksheet["B1:B4"]);
    
// Specify title settings.
chartProductSales.Title.SetValue("Sales by Products");
chartProductSales.Title.Font.Italic = true;

// Create a chart, bind it to data, and locate in a Worksheet.
DevExpress.Spreadsheet.Charts.Chart chartSalesbyRegion = spreadsheetControl1.ActiveWorksheet.Charts.Add(ChartType.ColumnClustered);
chartSalesbyRegion.TopLeftCell = spreadsheetControl1.ActiveWorksheet.Cells["F14"];
chartSalesbyRegion.BottomRightCell = spreadsheetControl1.ActiveWorksheet.Cells["K26"];
chartSalesbyRegion.Series.Add(spreadsheetControl1.ActiveWorksheet["C1:C10"], spreadsheetControl1.ActiveWorksheet["D1:D10"]);
    
// Specify title settings.
chartSalesbyRegion.Title.SetValue("Sales by Region");
chartSalesbyRegion.Title.Font.Italic = true; 

The generated charts will render as follows:

Call the LoadTemplate() method to apply chart template settings to generated charts:

using (FileStream stream = new FileStream("Chart1.crtx", FileMode.Open)) {
	foreach (var chart in spreadsheetControl1.ActiveWorksheet.Charts) {
    	stream.Position = 0;
        	chart.LoadTemplate(stream);
    }
}

Output will be as follows:

To achieve the same result with AddFromTemplate(), execute the following code snippet. In this instance, you do not need to create chart objects before applying settings from a template:

// ...
spreadsheetControl1.LoadDocument("Document.xlsx");
IWorkbook workbook = spreadsheetControl1.Document;
workbook.Worksheets.ActiveWorksheet = workbook.Worksheets["Sheet2"];

using (FileStream stream = new FileStream("Chart1.crtx", FileMode.Open)){
    stream.Position = 0;
    // Create a new chart object, bind it to data, and apply template setitngs.
    var chartProductSales = spreadsheetControl1.ActiveWorksheet.Charts.AddFromTemplate(stream, spreadsheetControl1.ActiveWorksheet["A1:B4"]);
    
    // Locate the chart in a Worksheet.
    spreadsheetControl1.ActiveWorksheet.Charts[0].TopLeftCell = spreadsheetControl1.ActiveWorksheet.Cells["F1"];
    spreadsheetControl1.ActiveWorksheet.Charts[0].BottomRightCell = spreadsheetControl1.ActiveWorksheet.Cells["K12"];
        
    // Specify title settings.
    spreadsheetControl1.ActiveWorksheet.Charts[0].Title.SetValue("Sales by Product");
    spreadsheetControl1.ActiveWorksheet.Charts[0].Title.Font.Italic = true;
    stream.Position = 0;
    
    // Create a new chart object, bind it to data, and apply template setitngs.
    var chartSalesbyRegion = spreadsheetControl1.ActiveWorksheet.Charts.AddFromTemplate(stream,
    spreadsheetControl1.ActiveWorksheet["C1:D10"]);
    
    // Locate the chart in a Worksheet.
    spreadsheetControl1.ActiveWorksheet.Charts[1].TopLeftCell = spreadsheetControl1.ActiveWorksheet.Cells["F14"];
    spreadsheetControl1.ActiveWorksheet.Charts[1].BottomRightCell = spreadsheetControl1.ActiveWorksheet.Cells["K26"];
        
    // Specify title settings.
    spreadsheetControl1.ActiveWorksheet.Charts[1].Title.SetValue("Sales by Region");
    spreadsheetControl1.ActiveWorksheet.Charts[1].Title.Font.Italic = true;
}

Note: Our new APIs ship with limitations related to chart types and data. Refer to the method description for more information: