diff --git a/_config.yml b/_config.yml index e910716079..ea478be8ce 100644 --- a/_config.yml +++ b/_config.yml @@ -374,6 +374,8 @@ navigation: title: "Popup" "*numerictextbox": title: "NumericTextBox" + "*pdfviewer": + title: "PDF Viewer" "*progressbar": title: "ProgressBar" "*qrcode": diff --git a/components/pdfviewer/events.md b/components/pdfviewer/events.md new file mode 100644 index 0000000000..5d40df3e70 --- /dev/null +++ b/components/pdfviewer/events.md @@ -0,0 +1,135 @@ +--- +title: Events +page_title: PdfViewer - Events +description: Events of the PDF Viewer for Blazor. How to handle events when users download, open or zoom PDF documents. +slug: pdfviewer-events +tags: telerik,blazor,pdf,pdfviewer +published: True +position: 20 +--- + +# PdfViewer Events + +This article describes the Blazor PDF Viewer events and provides a runnable example with sample event handler implementations. + +* [`OnDownload`](#ondownload) +* [`OnError`](#onerror) +* [`OnOpen`](#onopen) +* [`ZoomChanged`](#zoomchanged) + + +## OnDownload + +The `OnDownload` event fires when the user clicks on the Download button in the [PDF Viewer toolbar]({%slug pdfviewer-toolbar%}). + +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). + + +## OnError + +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. + +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). + + +## OnOpen + +The `OnOpen` event fires when the user selects a file to open from the [PDF Viewer toolbar]({%slug pdfviewer-toolbar%}). + +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). + +Using `OnOpen` is *not* required. Users can open local files from their devices without this handler. See the [example below](#example). + + +## ZoomChanged + +The `ZoomChanged` event fires when the user clicks on the zoom in/out buttons, or selects a new zoom level from the ComboBox. + +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. + + +## Example + +>caption Handle or cancel Blazor PDF Viewer Events + +````CSHTML +

Last event: @EventLog

+ +

+ + + + +@code { + private byte[] PdfSource { get; set; } + + private decimal PdfZoom { get; set; } = 1.25m; + + private bool AllowDownloads { get; set; } = true; + + private string EventLog { get; set; } = "..."; + + private async Task OnPdfDownload(PdfViewerDownloadEventArgs args) + { + if (AllowDownloads) + { + args.FileName = "PDF-Viewer-Download"; + EventLog = $"Download {args.FileName}.pdf"; + } + else + { + args.IsCancelled = true; + EventLog = $"Download cancelled"; + } + } + + private async Task OnPdfError(PdfViewerErrorEventArgs args) + { + // To trigger the event, rename a random file to error.pdf and try to open it. + EventLog = "Error: " + args.Message; + } + + private async Task OnPdfOpen(PdfViewerOpenEventArgs args) + { + var file = args.Files.FirstOrDefault(); + + if (file.Size > 1024 * 1024) + { + args.IsCancelled = true; + EventLog = $"Open cancelled conditionally. File {file.Name} ({file.Size} bytes) is larger than 1 MB."; + } + else + { + // Get the PDF file contents if necessary. + var buffer = new byte[file.Stream.Length]; + await file.Stream.ReadAsync(buffer); + + EventLog = $"Open {file.Name}, {file.Size} bytes"; + } + } + + private async Task OnPdfZoomChanged(decimal newZoom) + { + PdfZoom = newZoom; + + EventLog = "Zoom level changed."; + } +} +```` + + +## Next Steps + +* [Customize the PDF Viewer toolbar]({%slug pdfviewer-toolbar%}) + + +## See Also + +* [PdfViewer Events Demo](https://demos.telerik.com/blazor-ui/pdfviewer/events) +* [PdfViewer API](/blazor-ui/api/Telerik.Blazor.Components.TelerikPdfViewer) diff --git a/components/pdfviewer/overview.md b/components/pdfviewer/overview.md new file mode 100644 index 0000000000..d1d53ffdbf --- /dev/null +++ b/components/pdfviewer/overview.md @@ -0,0 +1,166 @@ +--- +title: Overview +page_title: PdfViewer - Overview +description: Overview of the PDF Viewer for Blazor. +slug: pdfviewer-overview +tags: telerik,blazor,pdf,pdfviewer +published: True +position: 0 +--- + +# Blazor PdfViewer Overview + +The Pdf Viewer for Blazor 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. + + +## Creating Blazor PdfViewer + +To use a Telerik PDF Viewer for Blazor: + +1. Add the `TelerikPdfViewer` tag. +1. Set the `Data` parameter to a byte array (`byte[]`) that holds the PDF file contents. +1. If you are developing a Blazor **Server** app, [increase the maximum SignalR message size](#large-file-support). +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. +1. (optional) Set [`Width` or `Height`](#pdfviewer-parameters) for the component. + +>caption Basic Blazor PDF Viewer + +````CSHTML + + + +@code { + private byte[] PdfSource { get; set; } + + private async Task OnPdfDownload(PdfViewerDownloadEventArgs args) + { + args.FileName = "PDF-Viewer-Download"; + } + + protected override void OnInitialized() + { + PdfSource = Convert.FromBase64String(PdfBase64); + + base.OnInitialized(); + } + + private const string PdfBase64 = "JVBERi0xLjEKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDEvTWVkaWFCb3ggWy00MCAtNjQgMjYwIDgwXSA+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9Gb250PDwvRjE8PC9UeXBlL0ZvbnQvU3VidHlwZS9UeXBlMS9CYXNlRm9udC9BcmlhbD4+ID4+ID4+L0NvbnRlbnRzIDQgMCBSPj5lbmRvYmoKNCAwIG9iajw8L0xlbmd0aCA1OT4+CnN0cmVhbQpCVAovRjEgMTggVGYKMCAwIFRkCihUZWxlcmlrIFBkZlZpZXdlciBmb3IgQmxhem9yKSBUagpFVAplbmRzdHJlYW0KZW5kb2JqCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZgowMDAwMDAwMDIxIDAwMDAwIG4KMDAwMDAwMDA4NiAwMDAwMCBuCjAwMDAwMDAxOTUgMDAwMDAgbgowMDAwMDAwNDkwIDAwMDAwIG4KdHJhaWxlciA8PCAgL1Jvb3QgMSAwIFIgL1NpemUgNSA+PgpzdGFydHhyZWYKNjA5CiUlRU9G"; +} +```` + + +## Toolbar + +The [PdfViewer toolbar can render built-in and custom tools]({%slug pdfviewer-toolbar%}). The default tools enable built-in features such as: + +* Page, zoom and pan documents +* Search and select text +* Print, download and open local PDF files + + +## Large File Support + +In Blazor **Server** apps, the PDF Viewer uses the **SignalR WebSocket** to: + +* Open PDF files from the server and send them to the browser. +* 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. + +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). + + +## PdfViewer Parameters + +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. + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type and Default Value | Description | +| --- | --- | --- | +| `Class` | `string` | An additional CSS class for the `
` element. Use it to [customize the component styles and override the theme]({%slug themes-override%}). | +| `Data` | `byte[]` | The source of the currently displayed PDF file. | +| `EnableLoaderContainer` | `bool`
(`true`) | Determines if the PDF Viewer will show a loading animation during opening, downloading or zooming a PDF file. | +| `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. | +| `MaxZoom` | `decimal`
(`4m`) | The largest possible zoom level. The default value allows zooming in 4 times (400%). | +| `MinZoom` | `decimal`
(`0.5m`) | The smallest possible zoom level. The default value allows zooming out to 50%. | +| `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. | +| `Zoom` | `decimal`
(`1.25m`) | The current zoom level. Use the parameter with two-way binding or with a [`ZoomChanged` event handler]({%slug pdfviewer-events%}#zoomchanged). | +| `ZoomRate` | `decimal`
(`0.25m`) | The zoom level change that is used by the zoom in and zoom out buttons. | + + +## PdfViewer Reference and Methods + +The PdfViewer exposes methods for programmatic operation. To use them, define a reference to the component instance with the `@ref` directive attribute. + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Method | Description | +| --- | --- | +| `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). | + + +>caption PDF Viewer reference and Rebind method usage + +````CSHTML + + + + Rebind PDF Viewer + + + + +@code { + private TelerikPdfViewer PdfViewerRef { get; set; } + + private async Task OnButtonClick() + { + PdfViewerRef.Rebind(); + } + + private byte[] PdfSource + { + get + { + return System.Text.Encoding.UTF8.GetBytes( + PdfSourceRaw.Replace("...", + PdfUpdateFlag ? "updated at " + DateTime.Now.ToLongTimeString() : "") + ); + } + } + + protected override async Task OnInitializedAsync() + { + PdfSourceRaw = System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(PdfBase64)); + + await Task.Delay(1000); + + // PdfUpdateFlag is used in the PdfSource getter to make the document change more obvious + PdfUpdateFlag = true; + + PdfViewerRef.Rebind(); + + await base.OnInitializedAsync(); + } + + private bool PdfUpdateFlag { get; set; } + + private string PdfSourceRaw { get; set; } + + private const string PdfBase64 = "JVBERi0xLjEKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDEvTWVkaWFCb3ggWy0zMCAtNjQgMjcwIDgwXSA+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9Gb250PDwvRjE8PC9UeXBlL0ZvbnQvU3VidHlwZS9UeXBlMS9CYXNlRm9udC9BcmlhbD4+ID4+ID4+L0NvbnRlbnRzIDQgMCBSPj5lbmRvYmoKNCAwIG9iajw8L0xlbmd0aCA1OT4+CnN0cmVhbQpCVAovRjEgMTggVGYKMCAwIFRkCihQREYgRmlsZSAuLi4pIFRqCkVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDUKMDAwMDAwMDAwMCA2NTUzNSBmCjAwMDAwMDAwMjEgMDAwMDAgbgowMDAwMDAwMDg2IDAwMDAwIG4KMDAwMDAwMDE5NSAwMDAwMCBuCjAwMDAwMDA0OTAgMDAwMDAgbgp0cmFpbGVyIDw8ICAvUm9vdCAxIDAgUiAvU2l6ZSA1ID4+CnN0YXJ0eHJlZgo2MDkKJSVFT0Y="; +} +```` + + +## Next Steps + +* [Customize the PDF Viewer toolbar]({%slug pdfviewer-toolbar%}) +* [Handle PDF Viewer events]({%slug pdfviewer-events%}) + + +## See Also + +* [PdfViewer Live Demo](https://demos.telerik.com/blazor-ui/pdfviewer/overview) +* [PdfViewer API](/blazor-ui/api/Telerik.Blazor.Components.TelerikPdfViewer) diff --git a/components/pdfviewer/toolbar.md b/components/pdfviewer/toolbar.md new file mode 100644 index 0000000000..3bdee10a43 --- /dev/null +++ b/components/pdfviewer/toolbar.md @@ -0,0 +1,94 @@ +--- +title: Toolbar +page_title: PdfViewer - Toolbar +description: Toolbar of the PDF Viewer for Blazor. List of all built-in tools. How to use custom PDF Viewer tools. +slug: pdfviewer-toolbar +tags: telerik,blazor,pdf,pdfviewer +published: True +position: 10 +--- + +# PdfViewer Toolbar + +The PDF Viewer toolbar can render built-in and custom tools. This article describes the built-in tools and shows how to add custom tools or customize the toolbar. + + +## Built-in Tools + +By default, the PDF Viewer displays all its built-in tools in the order below. Use the *tool tag* if you need to define a tool explicitly in a [custom toolbar configuration](#toolbar-configuration). + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Tool Name | Tool Tag | Description | +| --- | --- | --- | +| Pager | `PdfViewerToolBarPagerTool` | A pager to navigate the PDF document via automatic scrolling. Paging requires the [`Height` parameter]({%slug pdfviewer-overview%}#pdfviewer-parameters) to be set, otherwise the component expands and doesn't have its own scrollbar. | +| Zoom | `PdfViewerToolBarZoomTool` | Zoom in and zoom out buttons with an additional dropdown with common options (Fit to page, Fit to width, 100%, etc.) | +| Selection | `PdfViewerToolBarSelectionTool` | Two toggle buttons that enable either text selection or panning. | +| Search | `PdfViewerToolBarSearchTool` | A search button. It opens an additional search bar that contains a textbox and arrow buttons to navigate the search results. | +| Open | `PdfViewerToolBarOpenTool` | An open button. It fires the [`OnOpen` event]({%slug pdfviewer-events%}#onopen). | +| Download | `PdfViewerToolBarDownloadTool` | A download button. It fires the [`OnDownload` event]({%slug pdfviewer-events%}#ondownload). | +| Print | `PdfViewerToolBarPrintTool` | A print button. | + +By default, the toolbar also includes separators (``) and spacers (``). Separators render as a vertical line. Spacers consume the available empty space and push the rest of the tools next to one another. + + +## Custom Tools + +In addition to built-in tools, the PDF Viewer also supports custom tools. Use the `` tag, which is a standard Blazor `RenderFragment`. See the example below. + + +## Toolbar Configuration + +Add a `` tag inside `` to configure a custom toolbar, for example: + +* Arrange the PDF Viewer tools in a specific order; +* Remove some of the built-in tools; +* Add custom tools. + +>caption Customize the PDF Viewer toolbar + +````CSHTML + + + + Custom PDF Tool + + + + + + + + + + + + + + + + + + + + +@code { + private byte[] PdfSource { get; set; } + + private async Task OnPdfCustomClick() + { + Console.WriteLine("Custom PDF tool clicked"); + } +} +```` + + +## Next Steps + +* [Handle PDF Viewer events]({%slug pdfviewer-events%}) + + +## See Also + +* [PdfViewer Live Demo](https://demos.telerik.com/blazor-ui/pdfviewer/overview) +* [PdfViewer API](/blazor-ui/api/Telerik.Blazor.Components.TelerikPdfViewer)