Skip to content

Commit 63cb656

Browse files
ntachevantacheva
committed
chore(grid): refactor export notes
1 parent 5226e67 commit 63cb656

File tree

5 files changed

+87
-49
lines changed

5 files changed

+87
-49
lines changed

‎_contentTemplates/grid/export.md‎

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,8 @@
11
#export-common-notes
2-
* `bool` fields are exported as `TRUE` or `FALSE` strings, because there is no native boolean data type in exported format and these string values are the most common ones used in data and macros.
32

4-
* Date and number formats are exported with the following format: `mm/dd/yyyy hh:mm:ss` plus the current app culture AM/PM specifier for dates, and `Convert.ToDouble(value)` for numbers (which uses the current thread culture). The Excel date formats are different than .NET date formats and Excel may not always recognize the column as dates, for example, if the entire date format from the .NET culture is used.
53

6-
* The Grid exports only `<GridColumn>` instances. Other types of columns are not exported, for example command, checkbox, hierarchy, group and row-drag columns.
74

8-
* If the Grid is using `OnRead` and is exporting all pages, it will fire an additional `OnRead` event at the time of exporting, with a request `PageSize` of `0`. This will enable the component to obtain all data.
95

10-
* With Server-side Blazor, the file may become larger than the default SignalR connection limit, and this can disconnect the client and result in an error. Generally, this requires quite a lot of data to happen, but you may need to increase the size limit of the connection in the `ConfigureServices` method of your `Startup.cs` file, for example:
11-
12-
````C#.skip-repl
13-
services.AddServerSideBlazor().AddHubOptions(o =>
14-
{
15-
o.MaximumReceiveMessageSize = 1024 * 1024; // 1MB
16-
});
17-
````
186

197
* With Client-side Blazor (WebAssembly), all the code runs in the browser and, at the time of writing, is considerably slower than server-side Blazor, and it only has one actual thread. This means that while the file is being generated, the UI will be unresponsive, so you may want to show a loading sign to the user through the `OnClick` handler of the command button, something like:
208

@@ -76,3 +64,4 @@ services.AddServerSideBlazor().AddHubOptions(o =>
7664
}
7765
````
7866
#end
67+

‎components/grid/export/csv.md‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Export to CSV the Grid for Blazor.
55
slug: grid-export-csv
66
tags: telerik,blazor,grid,export,csv
77
published: True
8-
position: 1
8+
position: 3
99
---
1010

1111
# Grid CSV Export
@@ -17,6 +17,7 @@ When you click the Export button, your browser will receive the resulting file.
1717
#### In This Article
1818

1919
- [Basics](#basics)
20+
- [Limitations](#limitations)
2021
- [Programmatic Export](#programmatic-export)
2122
- [Customization](#customization)
2223
- [Notes](#notes)
@@ -41,6 +42,8 @@ Optionally, you can also set the `GridCsvExport` tag settings under the `GridExp
4142
| `FileName` | `string` | The name of the file. The grid will add the `.csv` extension for you. |
4243
| `AllPages` | `bool` | Whether to export the current page only, or the entire data from the data source. |
4344

45+
> Before enabling the export feature, ensure you are familiar with [its specifics](slug:grid-export-overview#how-it-works).
46+
4447
>caption Export the Grid to CSV - Example
4548
4649
````RAZOR
@@ -99,6 +102,10 @@ Optionally, you can also set the `GridCsvExport` tag settings under the `GridExp
99102
}
100103
````
101104

105+
## Limitations
106+
107+
* Column widths are not applied because a CSV document does not have such a concept. You can use any units in the grid itself, they will not be reflected in the exported document. If you need to add such structure, consider [exporting to an Excel file](slug:grid-export-excel).
108+
102109
## Programmatic Export
103110

104111
You can programmatically invoke the export feature of the Grid, by using the following methods exposed on the `@ref` of the Grid:
@@ -198,14 +205,6 @@ For more advanced customizations (such as coloring the headers, bolding the titl
198205

199206
[Read more about how to customize the exported file...](slug:grid-export-events)
200207

201-
## Notes
202-
203-
The CSV export has the following specifics:
204-
205-
* Column widths are not applied because a CSV document does not have such a concept. You can use any units in the grid itself, they will not be reflected in the exported document. If you need to add such structure, consider [exporting to an Excel file](slug:grid-export-excel).
206-
* Templates are not exported, because there is no provision in the framework for getting them at runtime. If a column, header or group header/footer has a template or aggregates, it will be ignored. The headers will be the `Title` of the column, the data is the data from the `Field`. If you need additional information, see if you can add it in a Field in the model, or create your own Excel file. Find a <a href="https://feedback.telerik.com/blazor/1485764-customize-the-excel-file-before-it-gets-to-the-client" target="_blank">project example on how to generate your own exported file</a>.
207-
208-
@[template](/_contentTemplates/grid/export.md#export-common-notes)
209208

210209
## See Also
211210

‎components/grid/export/excel.md‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Export to Excel the Grid for Blazor.
55
slug: grid-export-excel
66
tags: telerik,blazor,grid,export,excel
77
published: True
8-
position: 1
8+
position: 5
99
---
1010

1111
# Grid Excel Export
@@ -18,9 +18,9 @@ When you click the Export button, your browser will receive the resulting file.
1818
#### In This Article
1919

2020
- [Basics](#basics)
21+
- [Requirements](#requirements)
2122
- [Programmatic Export](#programmatic-export)
2223
- [Customization](#customization)
23-
- [Notes](#notes)
2424

2525
## Basics
2626

@@ -41,6 +41,8 @@ Optionally, you can also set the `GridExcelExport` tag settings under the `GridE
4141
| `FileName` | `string` | The name of the file. The grid will add the `.xslx` extension for you. |
4242
| `AllPages` | `bool` | Whether to export the current page only, or the entire data from the data source. |
4343

44+
> Before enabling the export feature, ensure you are familiar with [its specifics](slug:grid-export-overview#how-it-works).
45+
4446
>caption Export the Grid to Excel - Example
4547
4648
````RAZOR
@@ -99,6 +101,11 @@ Optionally, you can also set the `GridExcelExport` tag settings under the `GridE
99101
}
100102
````
101103

104+
105+
## Requirements
106+
107+
* If you are setting `Width` to the columns, use only `px`. Excel does not understand units different than `px` and if you use them (such as `rem` or `%`), it will fail to parse them and will render a collapsed (hidden) column with zero width.
108+
102109
## Programmatic Export
103110

104111
You can programmatically invoke the export feature of the Grid, by using the following methods exposed on the `@ref` of the Grid:
@@ -199,16 +206,6 @@ For more advanced customization (such as coloring the headers or bolding the tit
199206

200207
Read more about how to [customize the exported file](slug:grid-export-events).
201208

202-
## Notes
203-
204-
The Excel export has the following specifics:
205-
206-
* Excel does not understand units different than `px` for the column `Width`, and if you use them (such as `rem` or `%`), it will fail to parse them and will render a collapsed (hidden) column with zero width.
207-
* Templates are not exported, because there is no provision in the framework for getting them at runtime. If a column, header or group header/footer has a template or aggregates, it will be ignored. The headers will be the `Title` of the column, the data is the data from the `Field`. If you need additional information, see if you can add it in a Field in the model, or create your own Excel file. Find a <a href="https://feedback.telerik.com/blazor/1485764-customize-the-excel-file-before-it-gets-to-the-client" target="_blank">project example on how to generate your own exported file</a>. Find additional information on how to [export an image that is rendered in a Grid column template](slug:grid-export-image-column-excel).
208-
209-
@[template](/_contentTemplates/grid/export.md#export-common-notes)
210-
211-
212209
## See Also
213210

214211
* [Live Demo: Grid Export](https://demos.telerik.com/blazor-ui/grid/export)

‎components/grid/export/overview.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Overview
3+
page_title: Grid - Export Overview
4+
description: Export basics for the Grid for Blazor.
5+
slug: grid-export-overview
6+
tags: telerik, blazor, grid, export
7+
published: True
8+
position: 1
9+
---
10+
11+
# Blazor Grid Export
12+
13+
The Grid for Blazor provides a built-in functionality to export the data to:
14+
* [CSV](slug:grid-export-csv)
15+
* [Excel](slug:grid-export-excel)
16+
* [PDF](slug:grid-export-pdf)
17+
18+
Before proceeding to the dedicated export articles, ensure you are familiar with the following specifics:
19+
20+
<!-- @[template](/_contentTemplates/grid/export.md#export-common-notes) -->
21+
22+
## How It Works
23+
24+
* If the Grid is using `OnRead` and is exporting all pages, it will fire an additional `OnRead` event at the time of exporting, with a request `PageSize` of `0`. This will enable the component to obtain all data.
25+
26+
## Requirements
27+
28+
* With Server-side Blazor, the file may become larger than the default SignalR connection limit, and this can disconnect the client and result in an error. Generally, this requires quite a lot of data to happen, but you may need to increase the size limit of the connection in the `ConfigureServices` method of your `Startup.cs` file, for example:
29+
30+
````C#.skip-repl
31+
services.AddServerSideBlazor().AddHubOptions(o =>
32+
{
33+
o.MaximumReceiveMessageSize = 1024 * 1024; // 1MB
34+
});
35+
````
36+
37+
## Limitations
38+
39+
* Templates are not exported, because there is no provision in the framework for getting them at runtime. If a column, header or group header/footer has a template or aggregates, it will be ignored. The headers will be the `Title` of the column, the data is the data from the `Field`. If you need additional information, see if you can add it in a Field in the model, or create your own PDF file. Find a <a href="https://feedback.telerik.com/blazor/1485764-customize-the-Pdf-file-before-it-gets-to-the-client" target="_blank">project example on how to generate your own exported file</a>. Find additional information on how to [export an image that is rendered in a Grid column template](slug:grid-export-image-column-excel).
40+
41+
* `bool` fields are exported as `TRUE` or `FALSE` strings, because there is no native boolean data type in exported format and these string values are the most common ones used in data and macros.
42+
43+
* Date and number formats are exported with the following format: `mm/dd/yyyy hh:mm:ss` plus the current app culture AM/PM specifier for dates, and `Convert.ToDouble(value)` for numbers (which uses the current thread culture). The Excel date formats are different than .NET date formats and Excel may not always recognize the column as dates, for example, if the entire date format from the .NET culture is used. To customize the date and number formats, use the [Export Events](slug: grid-export-events).
44+
45+
* The Grid exports only `<GridColumn>` instances. Other types of columns are not exported, for example command, checkbox, hierarchy, group and row-drag columns.
46+
47+
## Customization
48+
49+
The Grid allows customizing the exported files - determine the desired data to be exported, changing the number/date formats and more. For such customizations, [handle the export events](slug: grid-export-events)

‎components/grid/export/pdf.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: Export to PDF the Grid for Blazor.
55
slug: grid-export-pdf
66
tags: telerik,blazor,grid,export,pdf
77
published: True
8-
position: 1
8+
position: 7
99
---
1010

1111
# Grid PDF Export
@@ -17,9 +17,11 @@ When you click the Export button, your browser will receive the resulting file.
1717
#### In This Article
1818

1919
- [Basics](#basics)
20+
- [How It Works](#how-it-works)
21+
- [Requirements](#requirements)
22+
- [Limitations](#limitations)
2023
- [Programmatic Export](#programmatic-export)
2124
- [Customization](#customization)
22-
- [Notes](#notes)
2325
- [Custom Export](#custom-export)
2426

2527
## Basics
@@ -43,6 +45,8 @@ Optionally, you can also set the `GridPdfExport` tag settings under the `GridExp
4345
| `PaperSize` | `GridPdfExportPaperSize` enum <br/> (`A4`) | The size of the paper for the exported file. |
4446
| `PageOrientation` | `GridPdfExportPageOrientation` enum <br/> (`Portrait`)| The orientation of the page&mdash;portrait or landscape. |
4547

48+
> Before enabling the export feature, ensure you are familiar with [its specifics](slug:grid-export-overview#how-it-works).
49+
4650
>caption Export the Grid to PDF
4751
4852
````RAZOR
@@ -103,6 +107,20 @@ Optionally, you can also set the `GridPdfExport` tag settings under the `GridExp
103107
}
104108
````
105109

110+
## How It Works
111+
112+
* For performance reasons, the PDF export mechanism draws each cell value on a single line. Any content that does not fit in the available space will be clipped. Text wrapping and PDF column resizing is not supported.
113+
* Exporting to PDF in UI for Blazor is different from exporting in Kendo jQuery, where the full HTML is exported. The Blazor export to PDF will export the Grid to a table, similar to an Excel table. If you want [to export to PDF as HTML, you can use a custom approach](#custom-export).
114+
115+
## Requirements
116+
117+
* PDF export requires pixel widths for all columns. Widths in other units such as `%` or `em` cannot be translated correctly and the respective columns will collapse in the exported PDF file. The column widths for the PDF export can differ from the ones in the Grid configuration for the web browser. To set column widths for the PDF file only, use the `Width` property of the [`OnBeforeExportEventArgs.Columns`](slug:grid-export-events#for-pdf-export) members.
118+
* Provide appropriate `PaperSize` and `PageOrientation` properties. For example, if you want to render 20 columns (100px each) in an A4 sheet, then this will yield unexpected results. The column dimensions in a PDF file are fixed, thus they cannot be resized as in Excel, which requires the developer to ensure proper export dimensions.
119+
120+
## Limitations
121+
122+
* Some PDF fonts do not include Cyrillic or other non-Latin characters. In such cases, [load a compatible font explicitly](https://docs.telerik.com/devtools/document-processing/knowledge-base/pdfprocessing-implement-fontsprovider).
123+
106124
## Programmatic Export
107125

108126
You can programmatically invoke the export feature of the Grid, by using the following methods exposed on the `@ref` of the Grid:
@@ -200,20 +218,6 @@ For more advanced customization the Grid lets you get the `MemoryStream` of the
200218

201219
Read more about how to [customize the exported file](slug:grid-export-events).
202220

203-
## Notes
204-
205-
The PDF export has the following specifics:
206-
207-
* PDF export requires pixel widths for all columns. Widths in other units such as `%` or `em` cannot be translated correctly and the respective columns will collapse in the exported PDF file. The column widths for the PDF export can differ from the ones in the Grid configuration for the web browser. To set column widths for the PDF file only, use the `Width` property of the [`OnBeforeExportEventArgs.Columns`](slug:grid-export-events#for-pdf-export) members.
208-
* For performance reasons, the PDF export mechanism draws each cell value on a single line. Any content that does not fit in the available space will be clipped. Text wrapping and PDF column resizing is not supported.
209-
* Provide appropriate `PaperSize` and `PageOrientation` properties. For example, if you want to render 20 columns (100px each) in an A4 sheet, then this will yield unexpected results. The column dimensions in a PDF file are fixed, thus they cannot be resized as in Excel, which requires the developer to ensure proper export dimensions.
210-
* Exporting to PDF in UI for Blazor is different from exporting in Kendo jQuery, where the full HTML is exported. The Blazor export to PDF will export the Grid to a table, similar to an Excel table. If you want [to export to PDF as HTML, you can use a custom approach](#custom-export).
211-
* Some PDF fonts do not include Cyrillic or other non-Latin characters. In such cases, [load a compatible font explicitly](https://docs.telerik.com/devtools/document-processing/knowledge-base/pdfprocessing-implement-fontsprovider).
212-
* Templates are not exported, because there is no provision in the framework for getting them at runtime. If a column, header or group header/footer has a template or aggregates, it will be ignored. The headers will be the `Title` of the column, the data is the data from the `Field`. If you need additional information, see if you can add it in a Field in the model, or create your own PDF file. Find a <a href="https://feedback.telerik.com/blazor/1485764-customize-the-Pdf-file-before-it-gets-to-the-client" target="_blank">project example on how to generate your own exported file</a>. Find additional information on how to [export an image that is rendered in a Grid column template](slug:grid-export-image-column-excel).
213-
214-
@[template](/_contentTemplates/grid/export.md#export-common-notes)
215-
216-
217221
## Custom Export
218222

219223
If you want to have full control over the PDF export, you can perform it with a custom approach.

0 commit comments

Comments
 (0)