New to Telerik UI for ASP.NET AJAX? Download free 30-day trial

Export Infrastructure

Basics

The Export Infrastructure is designed to be a middle tier structure that sits between an export library and server control. Currently there are three renderers - for binary XLS (BIFF) files, for XLSX files and for DOCX files. Note that XLSX and DOCX renderers are supported since Q3 2014 version of UI for ASP.NET AJAX. Although it has been used internally for RadGrid, it is in fact independent and could be used in a wide range of scenarios. For example:

  • for generating a binary XLS/XLSX/DOCX file on-the-fly

  • for implementing XLS/XLSX/DOCX export for your own custom controls and/or Telerik controls that doesn't support export to Excel out-of-the-box

  • for direct manipulation of the output generated by controls that uses it internally (RadGrid)

Structure

The core structure is very simple and easy to use. Due to the fact that its building blocks are familiar elements like Table, Column, Row, Cell, etc everyone can take advantage of its features without reading bulky documentations and most importantly, the developer doesn't need to know how the endpoint (the export library) actually works and therefore he also doesn't need to think of its peculiarities and limitations.

Cell, Column, and Row indices start from 1.

Cell

Name Description
Table Reference to the Table object
RowIndex Index of the parent row
ColIndex Index of the parent column
Index The index of the cell (Point). Note that the cell indices start from 1, not from 0.
Style Container for the cell styles
Value Get/set the value of the given cell
Colspan The column span of the cell
Rowspan The row span of the current cell
Text The value of the cell converted to text
Format Get/set the numeric format of the cell value

Column

Name Description
Table Reference to the Table object
Style Container for the Column styles
Width The width of the current Column
Cells Returns a collection containing the cells belonging to this Column
Index The index of the current Column. Note that the column indices start from 1, not from 0.

Row

Name Description
Table Reference to the Table object
Style Container for the Row styles
Height The height of the current Row
Cells Returns a collection containing the cells belonging to this Row
Index The index of the current Row. Note that the row indices start from 1, not from 0.

Table

Name Description
Index The index of the current Table in the ExportStructure
Title The title (name) of the Table
Cells Returns a collection containing the Cells belonging to this Table
Rows Returns a collection containing the Rows belonging to this Table
Columns Returns a collection containing the Columns belonging to this Table
Style Container for the Table styles

ExportStructure

Name Description
Tables Returns a collection containing the Rows belonging to this ExportStructure

ExportStyle

Name Description
BackColor Background color
BorderBottomColor Color of the bottom border
BorderLeftColor Color of the left border
BorderRightColor Color of the right border
BorderTopColor Color of the top border
BorderBottomStyle Style of the bottom border
BorderLeftStyle Style of the left border
BorderRightStyle Style of the right border
BorderTopStyle Style of the top border
Font FontInfo object. Contains the font information for the given instance.
ForeColor Foreground color
HorizontalAlign Horizontal text alignment
VerticalAlign Vertical text alignment
IsEmpty Determines whether the current Style is empty
HasBorderStyles Returns true, if the current Style has at least one border

Basic Operations

Below, you can find some examples demonstrating how you could use the export infrastructure. Note that there is no need to create Row and Column objects except if you need to set row/column-specific properties like width/height for example.

Using the Export Infrastructure - Example 1

Telerik.Web.UI.ExportInfrastructure.ExportStructure structure = new Telerik.Web.UI.ExportInfrastructure.ExportStructure();
Telerik.Web.UI.ExportInfrastructure.Table table = new Telerik.Web.UI.ExportInfrastructure.Table("Sheet1");
table.Rows[1].Height = 20;
table.Cells[1, 1].Value = 1.2;
structure.Tables.Add(table);
Dim [structure] As New Telerik.Web.UI.ExportInfrastructure.ExportStructure()
Dim table As New Telerik.Web.UI.ExportInfrastructure.Table("Sheet1")
table.Rows(1).Height = 20
table.Cells(1, 1).Value = 1.2
[structure].Tables.Add(table)

Using the Export Infrastructure - Example 2

Telerik.Web.UI.ExportInfrastructure.ExportStructure structure2 = new Telerik.Web.UI.ExportInfrastructure.ExportStructure();
Telerik.Web.UI.ExportInfrastructure.Table table2 = new Telerik.Web.UI.ExportInfrastructure.Table("S1");
table2.Cells["A5"].Value = "Wine";
Telerik.Web.UI.ExportInfrastructure.Cell b2Cell = table2.Cells["B2"];
b2Cell.Value = "White";
b2Cell.Style.BackColor = System.Drawing.Color.Blue;
structure2.Tables.Add(table2);
Dim structure2 As New Telerik.Web.UI.ExportInfrastructure.ExportStructure()
Dim table2 As New Telerik.Web.UI.ExportInfrastructure.Table("S1")
table2.Cells("A5").Value = "Wine"
Dim b2Cell As Telerik.Web.UI.ExportInfrastructure.Cell = table2.Cells("B2")
b2Cell.Value = "White"
b2Cell.Style.BackColor = System.Drawing.Color.Blue
structure2.Tables.Add(table2)

ShiftRowsDown method gives you the opportunity to insert new rows at the chosen position.The first argument of the method is the start row index, and the second argument is the number of the new rows which would be inserted.A possible use case is when the user wants to insert a custom header above the exported RadGrid,the customer could use this method to shift the rows down, up to the desired point.Although it is a part of the Export Infrastructure API, it is mostly suitable when exporting from RadGrid.

Telerik.Web.UI.ExportInfrastructure.Table tbl = e.ExportStructure.Tables[0];
tbl.ShiftRowsDown(2, 5);
Dim tbl As Telerik.Web.UI.ExportInfrastructure.Table = e.ExportStructure.Tables(0)
tbl.ShiftRowsDown(2, 5)

Rendering

As mentioned in the beginning of this topic, at this point there are three renderers available. Note that XLSX and DOCX renderers are supported since Q3 2014 version of UI for ASP.NET AJAX. You could use them to generate the appropriate file from a given structure. Simply create an instance of the XlsBiffRenderer, XlsxRenderer orDocxRenderer class, provide a reference to the ExportStructure object and then invoke the Render method. When executed, it will return a byte array that could be either saved in a file or sent to the client via the Response object.

Using the different renderers

//Renders XLS file
XlsBiffRenderer renderer = new XlsBiffRenderer(structure);
byte[] renderedBytes = renderer.Render();

//Renders XLSX file
XlsxRenderer renderer = new XlsxRenderer(structure);
byte[] renderedBytes = renderer.Render();

//Renders DOCX file
DocxRenderer renderer = new DocxRenderer(structure);
byte[] renderedBytes = renderer.Render();
'Renders XLS file
Dim renderer As New XlsBiffRenderer([structure])
Dim renderedBytes As Byte() = renderer.Render()

'Renders XLSX file
Dim renderer As New XlsxRenderer([structure])
Dim renderedBytes As Byte() = renderer.Render()

'Renders DOCX file
Dim renderer As New DocxRenderer([structure])
Dim renderedBytes As Byte() = renderer.Render()

Image Support

From Q3 2012 we provide Image support when using the Export Infrastructure. You just need instantiate the ExportStructure class,and then insert the image in a cell of your choice inside the table.

In the InsertImage method you should pass the cell or range of cells where the image will be located and the image path. Both relative and absolute paths are supported. It is also possible to create a new Image object directly and then add it to the Images collection of the Table object. You can specify a third boolean argument, indicating whether the image should be auto-sized to fit the cell(s) which hold it.

The method has the following overloads:

  • void InsertImage(Range range, string imageUrl)

  • void InsertImage(Range range, byte[] imageData)

  • void InsertImage(Cell cell, string imageUrl)

  • void InsertImage(Cell cell, string imageUrl, bool autoSize)

  • void InsertImage(Cell cell, byte[] imageData)

  • void InsertImage(Cell cell, byte[] imageData, bool autoSize)

ExportStructure exportStructure = new ExportStructure();
Telerik.Web.UI.ExportInfrastructure.Table table = new Telerik.Web.UI.ExportInfrastructure.Table("Table1");
table.InsertImage(new Range("A1", "B2"), "Image.png");
exportStructure.Tables.Add(table);
Dim exportStructure As New ExportStructure()
Dim table As New Telerik.Web.UI.ExportInfrastructure.Table("Table1")
table.InsertImage(New Range("A1", "B2"), "Image.png")
exportStructure.Tables.Add(table)

Automatic resizing is supported only when the image is inserted within a single cell (range is not supported).

Text Wrapping

Since Q3 2014 SP1 you are able to wrap a text (carried onto the next line) when using the ExportInfrastructure. For this purpose you you should set TextWrap to true to the desired cell, plus you have to insert the newline character ('\n') wherever you want the text to be wrapped. The example below demonstrates how to wrap a text.

ExportStructure structure = new ExportStructure();
Table tbl = new Table();
structure.Tables.Add(tbl);

var cell1 = tbl.Cells[1, 1];
cell1.Value = "First line text.\nSecond line text.";
cell1.TextWrap = true;


XlsBiffRenderer renderer = new XlsBiffRenderer(structure);

byte[] output = renderer.Render();
Dim [structure] As New ExportStructure()
Dim tbl As New Table()
[structure].Tables.Add(tbl)

Dim cell1 = tbl.Cells(1, 1)
cell1.Value = "First line text." & vbLf & "Second line text."
cell1.TextWrap = True


Dim renderer As New XlsBiffRenderer([structure])

Dim output As Byte() = renderer.Render()

Limitations

  • No hierarchy support

  • No grouping support

  • No automatic column/row resizing

In this article