Skip to content

Commit b44156c

Browse files
dimodidimodi
authored
[3.6.0] docs(pdfviewer): Initial PdfViewer Documentation (#1141)
* docs(pdfviewer): Add Overview and Events page * docs(pdfviewer): Add Toolbar page * chore(pdfviewer): Rename API members * docs(pdfviewer): Update, according to latest dev state * docs(pdfviewer): OnError event, Tool table and random polishing * docs(pdfviewer): Random polishing * docs(pdfviewer): Random polishing 2 * docs(pdfviewer): Random polishing 3 * docs(pdfviewer): Random polishing 4 * docs(pdfviewer): Remove Page parameter * minor polishing * zoom parameter rewording * docs(pdfviewer): Improve Rebind example * avoid passive voice * reduce PDF size, remove Timer * simplify PDF source in the basic example * simplify Rebind example * polishing * docs(pdfviewer): Add Zoom/ZoomChanged + polishing * Replace PDF source string with base64 string * polshing * smaller feature list in Overview * use consistent variable naming * use const * reword feature list * polishing and refactoring * switch form double to decimal * Update components/pdfviewer/overview.md * Update components/pdfviewer/overview.md * Revamp SignalR information * clarify OnOpen
1 parent 2214eee commit b44156c

File tree

4 files changed

+397
-0
lines changed

4 files changed

+397
-0
lines changed

‎_config.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -376,6 +376,8 @@ navigation:
376376
title: "Popup"
377377
"*numerictextbox":
378378
title: "NumericTextBox"
379+
"*pdfviewer":
380+
title: "PDF Viewer"
379381
"*progressbar":
380382
title: "ProgressBar"
381383
"*qrcode":

‎components/pdfviewer/events.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Events
3+
page_title: PdfViewer - Events
4+
description: Events of the PDF Viewer for Blazor. How to handle events when users download, open or zoom PDF documents.
5+
slug: pdfviewer-events
6+
tags: telerik,blazor,pdf,pdfviewer
7+
published: True
8+
position: 20
9+
---
10+
11+
# PdfViewer Events
12+
13+
This article describes the Blazor PDF Viewer events and provides a runnable example with sample event handler implementations.
14+
15+
* [`OnDownload`](#ondownload)
16+
* [`OnError`](#onerror)
17+
* [`OnOpen`](#onopen)
18+
* [`ZoomChanged`](#zoomchanged)
19+
20+
21+
## OnDownload
22+
23+
The `OnDownload` event fires when the user clicks on the Download button in the [PDF Viewer toolbar]({%slug pdfviewer-toolbar%}).
24+
25+
The event handler receives an argument of type [`PdfViewerDownloadEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.PdfViewerDownloadEventArgs). The event is cancellable and allows the application to set a name of the downloaded file. Do not add the `.pdf` file extension - the component will do that. The default name of the downloaded file is `Document.pdf`. See the [example below](#example).
26+
27+
28+
## OnError
29+
30+
The `OnError` event fires when a file error occurs. For example, the user tries to open a corrupt file or a file that is not in the correct format.
31+
32+
The event handler receives an argument of type [`PdfViewerErrorEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.PdfViewerErrorEventArgs), which exposes a `Message` property. See the [example below](#example).
33+
34+
35+
## OnOpen
36+
37+
The `OnOpen` event fires when the user selects a file to open from the [PDF Viewer toolbar]({%slug pdfviewer-toolbar%}).
38+
39+
The event handler receives an argument of type [`PdfViewerOpenEventArgs`](/blazor-ui/api/Telerik.Blazor.Components.PdfViewerOpenEventArgs). The event is cancellable and allows the application to obtain the PDF file name, size and contents as a `Stream`. To read the `Stream`, you may need to [increase the maximum SignalR message size]({%slug pdfviewer-overview%}#large-file-support).
40+
41+
Using `OnOpen` is *not* required. Users can open local files from their devices without this handler. See the [example below](#example).
42+
43+
44+
## ZoomChanged
45+
46+
The `ZoomChanged` event fires when the user clicks on the zoom in/out buttons, or selects a new zoom level from the ComboBox.
47+
48+
The event handler receives the new zoom level as an argument of type `decimal`. To apply the new zoom level, set it as a new `Zoom` parameter value. Not setting it will effectively cancel the event.
49+
50+
51+
## Example
52+
53+
>caption Handle or cancel Blazor PDF Viewer Events
54+
55+
````CSHTML
56+
<p> Last event: @EventLog </p>
57+
58+
<p><label> <TelerikCheckBox @bind-Value="@AllowDownloads" /> Allow Downloads </label></p>
59+
60+
<TelerikPdfViewer Data="@PdfSource"
61+
Height="600px"
62+
OnDownload="@OnPdfDownload"
63+
OnError="@OnPdfError"
64+
OnOpen="@OnPdfOpen"
65+
Zoom="@PdfZoom"
66+
ZoomChanged="@OnPdfZoomChanged">
67+
</TelerikPdfViewer>
68+
69+
@code {
70+
private byte[] PdfSource { get; set; }
71+
72+
private decimal PdfZoom { get; set; } = 1.25m;
73+
74+
private bool AllowDownloads { get; set; } = true;
75+
76+
private string EventLog { get; set; } = "...";
77+
78+
private async Task OnPdfDownload(PdfViewerDownloadEventArgs args)
79+
{
80+
if (AllowDownloads)
81+
{
82+
args.FileName = "PDF-Viewer-Download";
83+
EventLog = $"Download {args.FileName}.pdf";
84+
}
85+
else
86+
{
87+
args.IsCancelled = true;
88+
EventLog = $"Download cancelled";
89+
}
90+
}
91+
92+
private async Task OnPdfError(PdfViewerErrorEventArgs args)
93+
{
94+
// To trigger the event, rename a random file to error.pdf and try to open it.
95+
EventLog = "Error: " + args.Message;
96+
}
97+
98+
private async Task OnPdfOpen(PdfViewerOpenEventArgs args)
99+
{
100+
var file = args.Files.FirstOrDefault();
101+
102+
if (file.Size > 1024 * 1024)
103+
{
104+
args.IsCancelled = true;
105+
EventLog = $"Open cancelled conditionally. File {file.Name} ({file.Size} bytes) is larger than 1 MB.";
106+
}
107+
else
108+
{
109+
// Get the PDF file contents if necessary.
110+
var buffer = new byte[file.Stream.Length];
111+
await file.Stream.ReadAsync(buffer);
112+
113+
EventLog = $"Open {file.Name}, {file.Size} bytes";
114+
}
115+
}
116+
117+
private async Task OnPdfZoomChanged(decimal newZoom)
118+
{
119+
PdfZoom = newZoom;
120+
121+
EventLog = "Zoom level changed.";
122+
}
123+
}
124+
````
125+
126+
127+
## Next Steps
128+
129+
* [Customize the PDF Viewer toolbar]({%slug pdfviewer-toolbar%})
130+
131+
132+
## See Also
133+
134+
* [PdfViewer Events Demo](https://demos.telerik.com/blazor-ui/pdfviewer/events)
135+
* [PdfViewer API](/blazor-ui/api/Telerik.Blazor.Components.TelerikPdfViewer)

‎components/pdfviewer/overview.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: Overview
3+
page_title: PdfViewer - Overview
4+
description: Overview of the PDF Viewer for Blazor.
5+
slug: pdfviewer-overview
6+
tags: telerik,blazor,pdf,pdfviewer
7+
published: True
8+
position: 0
9+
---
10+
11+
# Blazor PdfViewer Overview
12+
13+
The <a href = "https://www.telerik.com/blazor-ui/pdf-viewer" target="_blank">Pdf Viewer for Blazor</a> allows users to open PDF files directly in the browser. The component provides features such as paging, zooming, printing, text selection and search. In addition, users can upload and display a PDF file from their local device, or download the currently open file.
14+
15+
16+
## Creating Blazor PdfViewer
17+
18+
To use a Telerik PDF Viewer for Blazor:
19+
20+
1. Add the `TelerikPdfViewer` tag.
21+
1. Set the `Data` parameter to a byte array (`byte[]`) that holds the PDF file contents.
22+
1. If you are developing a Blazor **Server** app, [increase the maximum SignalR message size](#large-file-support).
23+
1. (optional) Subscribe to the [PDF Viewer's events]({%slug pdfviewer-events%}). For example, use the `OnDownload` event to set the name of the downloaded file.
24+
1. (optional) Set [`Width` or `Height`](#pdfviewer-parameters) for the component.
25+
26+
>caption Basic Blazor PDF Viewer
27+
28+
````CSHTML
29+
<TelerikPdfViewer Data="@PdfSource"
30+
OnDownload="@OnPdfDownload"
31+
Height="600px">
32+
</TelerikPdfViewer>
33+
34+
@code {
35+
private byte[] PdfSource { get; set; }
36+
37+
private async Task OnPdfDownload(PdfViewerDownloadEventArgs args)
38+
{
39+
args.FileName = "PDF-Viewer-Download";
40+
}
41+
42+
protected override void OnInitialized()
43+
{
44+
PdfSource = Convert.FromBase64String(PdfBase64);
45+
46+
base.OnInitialized();
47+
}
48+
49+
private const string PdfBase64 = "JVBERi0xLjEKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDEvTWVkaWFCb3ggWy00MCAtNjQgMjYwIDgwXSA+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9Gb250PDwvRjE8PC9UeXBlL0ZvbnQvU3VidHlwZS9UeXBlMS9CYXNlRm9udC9BcmlhbD4+ID4+ID4+L0NvbnRlbnRzIDQgMCBSPj5lbmRvYmoKNCAwIG9iajw8L0xlbmd0aCA1OT4+CnN0cmVhbQpCVAovRjEgMTggVGYKMCAwIFRkCihUZWxlcmlrIFBkZlZpZXdlciBmb3IgQmxhem9yKSBUagpFVAplbmRzdHJlYW0KZW5kb2JqCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZgowMDAwMDAwMDIxIDAwMDAwIG4KMDAwMDAwMDA4NiAwMDAwMCBuCjAwMDAwMDAxOTUgMDAwMDAgbgowMDAwMDAwNDkwIDAwMDAwIG4KdHJhaWxlciA8PCAgL1Jvb3QgMSAwIFIgL1NpemUgNSA+PgpzdGFydHhyZWYKNjA5CiUlRU9G";
50+
}
51+
````
52+
53+
54+
## Toolbar
55+
56+
The [PdfViewer toolbar can render built-in and custom tools]({%slug pdfviewer-toolbar%}). The default tools enable built-in features such as:
57+
58+
* Page, zoom and pan documents
59+
* Search and select text
60+
* Print, download and open local PDF files
61+
62+
63+
## Large File Support
64+
65+
In Blazor **Server** apps, the PDF Viewer uses the **SignalR WebSocket** to:
66+
67+
* Open PDF files from the server and send them to the browser.
68+
* Read the PDF file `Stream` from the user device in the [`OnOpen` event handler]({%slug pdfviewer-events%}#onopen). The PDF Viewer uses internally a [FileSelect component]({%slug fileselect-overview%}) to get the user file.
69+
70+
The SignalR WebSocket has a default maximum message size of **32 KB**. To work with larger files in the above two scenarios, [increase the max WebSocket message size for the Blazor application]({%slug fileselect-overview%}#large-file-support).
71+
72+
73+
## PdfViewer Parameters
74+
75+
The table below lists the PDF Viewer parameters. Also check the [PDF Viewer API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikPdfViewer) for all parameters, methods and events.
76+
77+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
78+
79+
| Parameter | Type and Default&nbsp;Value | Description |
80+
| --- | --- | --- |
81+
| `Class` | `string` | An additional CSS class for the `<div class="k-pdf-viewer">` element. Use it to [customize the component styles and override the theme]({%slug themes-override%}). |
82+
| `Data` | `byte[]` | The source of the currently displayed PDF file. |
83+
| `EnableLoaderContainer` | `bool` <br /> (`true`) | Determines if the PDF Viewer will show a loading animation during opening, downloading or zooming a PDF file. |
84+
| `Height` | `string` | The PdfViewer height as a [CSS length value]({%slug common-features/dimensions%}). If not set, the component will expand vertically, based on the loaded file. `Height` is required for the component paging and scrolling to work. |
85+
| `MaxZoom` | `decimal` <br /> (`4m`) | The largest possible zoom level. The default value allows zooming in 4 times (400%). |
86+
| `MinZoom` | `decimal` <br /> (`0.5m`) | The smallest possible zoom level. The default value allows zooming out to 50%. |
87+
| `Width` | `string` | The PdfViewer width as a [CSS length value]({%slug common-features/dimensions%}). If not set, the component will expand horizontally to fill its parent. |
88+
| `Zoom` | `decimal` <br /> (`1.25m`) | The current zoom level. Use the parameter with two-way binding or with a [`ZoomChanged` event handler]({%slug pdfviewer-events%}#zoomchanged). |
89+
| `ZoomRate` | `decimal` <br /> (`0.25m`) | The zoom level change that is used by the zoom in and zoom out buttons. |
90+
91+
92+
## PdfViewer Reference and Methods
93+
94+
The PdfViewer exposes methods for programmatic operation. To use them, define a reference to the component instance with the `@ref` directive attribute.
95+
96+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
97+
98+
| Method | Description |
99+
| --- | --- |
100+
| `Rebind` | Refreshes the PDF Viewer and ensures it is displaying the latest file `Data`. [`Rebind` is necessary when the Blazor framework cannot re-render components automatically]({%slug common-features-data-binding-overview%}#refresh-data). |
101+
102+
103+
>caption PDF Viewer reference and Rebind method usage
104+
105+
````CSHTML
106+
<TelerikPdfViewer @ref="@PdfViewerRef"
107+
Data="@PdfSource">
108+
<PdfViewerToolBar>
109+
<PdfViewerToolBarCustomTool>
110+
<TelerikButton OnClick="@OnButtonClick" Icon="refresh">Rebind PDF Viewer</TelerikButton>
111+
</PdfViewerToolBarCustomTool>
112+
</PdfViewerToolBar>
113+
</TelerikPdfViewer>
114+
115+
@code {
116+
private TelerikPdfViewer PdfViewerRef { get; set; }
117+
118+
private async Task OnButtonClick()
119+
{
120+
PdfViewerRef.Rebind();
121+
}
122+
123+
private byte[] PdfSource
124+
{
125+
get
126+
{
127+
return System.Text.Encoding.UTF8.GetBytes(
128+
PdfSourceRaw.Replace("...",
129+
PdfUpdateFlag ? "updated at " + DateTime.Now.ToLongTimeString() : "")
130+
);
131+
}
132+
}
133+
134+
protected override async Task OnInitializedAsync()
135+
{
136+
PdfSourceRaw = System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(PdfBase64));
137+
138+
await Task.Delay(1000);
139+
140+
// PdfUpdateFlag is used in the PdfSource getter to make the document change more obvious
141+
PdfUpdateFlag = true;
142+
143+
PdfViewerRef.Rebind();
144+
145+
await base.OnInitializedAsync();
146+
}
147+
148+
private bool PdfUpdateFlag { get; set; }
149+
150+
private string PdfSourceRaw { get; set; }
151+
152+
private const string PdfBase64 = "JVBERi0xLjEKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDEvTWVkaWFCb3ggWy0zMCAtNjQgMjcwIDgwXSA+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9Gb250PDwvRjE8PC9UeXBlL0ZvbnQvU3VidHlwZS9UeXBlMS9CYXNlRm9udC9BcmlhbD4+ID4+ID4+L0NvbnRlbnRzIDQgMCBSPj5lbmRvYmoKNCAwIG9iajw8L0xlbmd0aCA1OT4+CnN0cmVhbQpCVAovRjEgMTggVGYKMCAwIFRkCihQREYgRmlsZSAuLi4pIFRqCkVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDUKMDAwMDAwMDAwMCA2NTUzNSBmCjAwMDAwMDAwMjEgMDAwMDAgbgowMDAwMDAwMDg2IDAwMDAwIG4KMDAwMDAwMDE5NSAwMDAwMCBuCjAwMDAwMDA0OTAgMDAwMDAgbgp0cmFpbGVyIDw8ICAvUm9vdCAxIDAgUiAvU2l6ZSA1ID4+CnN0YXJ0eHJlZgo2MDkKJSVFT0Y=";
153+
}
154+
````
155+
156+
157+
## Next Steps
158+
159+
* [Customize the PDF Viewer toolbar]({%slug pdfviewer-toolbar%})
160+
* [Handle PDF Viewer events]({%slug pdfviewer-events%})
161+
162+
163+
## See Also
164+
165+
* [PdfViewer Live Demo](https://demos.telerik.com/blazor-ui/pdfviewer/overview)
166+
* [PdfViewer API](/blazor-ui/api/Telerik.Blazor.Components.TelerikPdfViewer)

0 commit comments

Comments
 (0)