UI Elements - SAPUI5 Display PDF Viewer

Updated: February 21, 2023
Latest Version 1.128

PDF Viewer

sap.m.PDFViewer

Intro

The PDF viewer control displays PDF documents within your app. It can be embedded in your page layout, or you can set it to open in a popup dialog. In addition, this control allows you to print and download the PDF documents it displays.

Usage

Use the PDF viewer control if:

  • You want your app to display PDF files on all devices and platforms.
  • You want the users of your app to be able to preview their documents as PDF files right inside your app.
  • You need to ensure the consistent behavior of PDF files across all SAP Fiori apps.
  • You need to work with events (loaded, validation, error) provided by the PDF viewer.

Do not use the PDF viewer if:

  • You need to provide an interactive PDF file (such as a data input form).

Responsiveness

The PDF viewer control is fully responsive on large-screen devices (size L). The range of responsive behavior available on desktop devices depends on the display mode.

  • When the PDF viewer opens in a dialog popup:
    By default, the dialog supports two or more actions, such as Close and Download. On large-screen (desktop) devices, the action buttons are right-aligned. Use compact mode to ensure optimal padding and margins on desktop devices.
    If the content height is increased beyond the screen height, the dialog height cannot go beyond 4 rem from the top and bottom of the screen.
    The dialog popup must be resized automatically and cannot support dragging or custom resizing.

 

  • When the PDF viewer is embedded in a container on the app page:
    The dimensions of the frame in which the PDF file is displayed are defined by the PDF viewer properties.
    The control in which the PDF viewer is embedded must have at least 1 rem (16 px) padding to set it apart from the rest of the content.
    Only vertical scrolling is allowed. The behavior of desktop touch devices should follow the default behavior of the device or platform.

On mobile devices (smartphones and tablets), the PDF viewer control renders a toolbar with the title and a download icon, which behaves as a standard device/browser file link.

If required, you can customize the behavior for mobile devices and trigger the default device action for the file link from a different anchor in the application.

Size L - Popup mode
Size L - Popup mode
Size L - Embedded mode
Size L - Embedded mode
Size M - Tablet
Size M - Tablet
Size S - Mobile
Size S - Mobile

Layout

Displaying PDF Files in a Dialog

The dialog is positioned in the center of the screen. It opens in a modal window to attract the user’s attention when it displays emergency states. The dialog consists of:

  • A dialog header
  • A dialog PDF content
  • A dialog footer

Displaying Embedded PDF Files

The secondary mode of the PDF viewer displays PDF files directly on the page. The application owner, using the PDF viewer control, provides the dimensions of the frame in which the PDF file is embedded. The container should have at least 1 rem (16px) padding from the other content on the page to allow users to distinguish between the embedded PDF and the rest of the page’s content.

When the PDF viewer is embedded on the page, it comprises:

  • An overflow toolbar header
  • A container for rendering the PDF file (determined by the application owner)
Schematic visualization of popup mode
Schematic visualization of popup mode
Schematic visualization of embedded mode
Schematic visualization of embedded mode
Developer Hint
The footer can be extended by any desired buttons. However, both the Close and Download buttons must be displayed. This is to ensure that the accessibility requirements are fulfilled. Additional information about action placement and order can be found in the Action Placement article.

Components

The PDF viewer in popup mode is rendered within a Dialog and consists of:

Title(Header): The title text appears in the dialog header.

Content: This area contains the actual PDF file displayed within the content of the dialog.

Footer with actions: The footer contains two mandatory buttons: Close and Download. Other actions can be added to the footer as well.

 

The PDF viewer in embedded mode can be rendered in any container desired by the application.

The title is displayed within the Toolbar (Overflow Toolbar).

Developer Hint
Use a Flexbox container to wrap the embedded mode of the PDF viewer inside the application.

Behavior and Interaction

All the interactions for the PDF files themselves must remain the same across platforms and browsers: paging, scrolling, zooming, and print must all be available.

Download – For accessibility reasons, the PDF viewer always provides an additional download button for downloading the displayed PDF file and gives users the option to download the embedded PDF renderer on a specific device or system (not all PDF reader plugins have their own download button).

Popup mode interactions:

  • No custom resizing of the dialog
  • No dragging of the dialog

Guidelines

To avoid the risk of performance issues, do not embed more than three instances of the PDF viewer per page. You may embed more instances of the PDF viewer in one page if the number of PDFs does not affect performance. Carry out benchmark tests to ensure that performance will not be affected.

The PDF viewer can be used within other sap.m components, such as carousel and panel, respecting the specific guidelines of these components.

The embedded mode of the PDF viewer can be used on the Object Page if the container is as wide as the object page. If this is not the case, use the popup mode of the PDF viewer instead.

The PDF viewer can provide accessibility options when used with screen readers and other accessibility software. To ensure that all the accessibility options are supported, you need to have Adobe PDF Reader installed.

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation