class sap.m.PDFViewer

Control sample: sap.m.PDFViewer
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/m/PDFViewer
Application Component: CA-UI5-SC

This control enables you to display PDF documents within your app. It can be embedded in your user interface layout, or you can set it to open in a popup dialog.

Please note that the PDF Viewer control can be fully displayed on desktop devices only. On mobile devices, only the toolbar with a download button is visible.


Constructor

Definition of PDFViewer control

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.PDFViewer(sId?, mSettings?)
Param Type Default Value Description
sId? string

id for the new control, generated automatically if no id is given

mSettings? object

initial settings for the new control


Properties

Name Type Default Value Description
displayType sap.m.PDFViewerDisplayType Auto

Defines how the PDF viewer should be displayed.

  • If set to Link, the PDF viewer appears as a toolbar with a download button that can be used to download the PDF file.
    When the #open method is called, the user can either open the PDF file in a new tab or download it.
  • If set to Embedded, the PDF viewer appears embedded in the parent container and displays either the PDF document or the message defined by the errorPlaceholderMessage property.
  • If set to Auto, the appearance of the PDF viewer depends on the device being used:
    • On mobile devices (phones, tablets), the PDF viewer appears as a toolbar with a download button.
    • On desktop devices, the PDF viewer is embedded in its parent container.

Visibility: public
errorMessage string

A custom error message that is displayed when the PDF file cannot be loaded.

Visibility: public
errorPlaceholderMessage string

A custom text that is displayed instead of the PDF file content when the PDF file cannot be loaded.

Visibility: public
height sap.ui.core.CSSSize 100%

Defines the height of the PDF viewer control, respective to the height of the parent container. Can be set to a percent, pixel, or em value.

Visibility: public
popupHeaderTitle string

A custom title for the PDF viewer popup dialog. Works only if the PDF viewer is set to open in a popup dialog.

Visibility: public
showDownloadButton boolean true

Shows or hides the download button.

Visibility: public
source sap.ui.core.URI

Specifies the path to the PDF file to display. Can be set to a relative or an absolute path.
Optionally, this property can also be set to a data URI path or a blob URL in all major web browsers except Internet Explorer and Microsoft Edge, provided that this data URI or blob URL is allowed in advance. For more information about URL filtering, see URLList Validator Filtering.

Visibility: public
title string

A custom title for the PDF viewer.

Visibility: public
width sap.ui.core.CSSSize 100%

Defines the width of the PDF viewer control, respective to the width of the parent container. Can be set to a percent, pixel, or em value.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
errorPlaceholder 0..1 sap.ui.core.Control

A custom control that can be used instead of the error message specified by the errorPlaceholderMessage property.

popupButtons 0..n sap.m.Button

A multiple aggregation for buttons that can be added to the footer of the popup dialog. Works only if the PDF viewer is set to open in a popup dialog.


Events Overview

Event Description
error

This event is fired when there is an error loading the PDF file.

loaded

This event is fired when a PDF file is loaded. If the PDF is loaded in smaller chunks, this event is fired as often as defined by the browser's plugin. This may happen after a couple chunks are processed.

sourceValidationFailed

This event is fired when the PDF viewer control cannot check the loaded content. For example, the default configuration of the Mozilla Firefox browser may not allow checking the loaded content. This may also happen when the source PDF file is stored in a different domain. If you want no error message to be displayed when this event is fired, call the preventDefault() method inside the event handler.

error

This event is fired when there is an error loading the PDF file.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
target any

The iframe element.

loaded

This event is fired when a PDF file is loaded. If the PDF is loaded in smaller chunks, this event is fired as often as defined by the browser's plugin. This may happen after a couple chunks are processed.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

sourceValidationFailed

This event is fired when the PDF viewer control cannot check the loaded content. For example, the default configuration of the Mozilla Firefox browser may not allow checking the loaded content. This may also happen when the source PDF file is stored in a different domain. If you want no error message to be displayed when this event is fired, call the preventDefault() method inside the event handler.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
addPopupButton

Adds some popupButton to the aggregation popupButtons.

attachError

Attaches event handler fnFunction to the error event of this sap.m.PDFViewer.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.PDFViewer itself.

This event is fired when there is an error loading the PDF file.

attachLoaded

Attaches event handler fnFunction to the loaded event of this sap.m.PDFViewer.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.PDFViewer itself.

This event is fired when a PDF file is loaded. If the PDF is loaded in smaller chunks, this event is fired as often as defined by the browser's plugin. This may happen after a couple chunks are processed.

attachSourceValidationFailed

Attaches event handler fnFunction to the sourceValidationFailed event of this sap.m.PDFViewer.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.PDFViewer itself.

This event is fired when the PDF viewer control cannot check the loaded content. For example, the default configuration of the Mozilla Firefox browser may not allow checking the loaded content. This may also happen when the source PDF file is stored in a different domain. If you want no error message to be displayed when this event is fired, call the preventDefault() method inside the event handler.

destroyErrorPlaceholder

Destroys the errorPlaceholder in the aggregation errorPlaceholder.

destroyPopupButtons

Destroys all the popupButtons in the aggregation popupButtons.

detachError

Detaches event handler fnFunction from the error event of this sap.m.PDFViewer.

The passed function and listener object must match the ones used for event registration.

detachLoaded

Detaches event handler fnFunction from the loaded event of this sap.m.PDFViewer.

The passed function and listener object must match the ones used for event registration.

detachSourceValidationFailed

Detaches event handler fnFunction from the sourceValidationFailed event of this sap.m.PDFViewer.

The passed function and listener object must match the ones used for event registration.

downloadPDF

Downloads the PDF file.

sap.m.PDFViewer.extend

Creates a new subclass of class sap.m.PDFViewer with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireError

Fires event error to attached listeners.

fireLoaded

Fires event loaded to attached listeners.

fireSourceValidationFailed

Fires event sourceValidationFailed to attached listeners.

getDisplayType

Gets current value of property displayType.

Defines how the PDF viewer should be displayed.

  • If set to Link, the PDF viewer appears as a toolbar with a download button that can be used to download the PDF file.
    When the #open method is called, the user can either open the PDF file in a new tab or download it.
  • If set to Embedded, the PDF viewer appears embedded in the parent container and displays either the PDF document or the message defined by the errorPlaceholderMessage property.
  • If set to Auto, the appearance of the PDF viewer depends on the device being used:
    • On mobile devices (phones, tablets), the PDF viewer appears as a toolbar with a download button.
    • On desktop devices, the PDF viewer is embedded in its parent container.

Default value is Auto.

getErrorMessage

Gets current value of property errorMessage.

A custom error message that is displayed when the PDF file cannot be loaded.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getErrorPlaceholderMessage}.
getErrorPlaceholder

Gets content of aggregation errorPlaceholder.

A custom control that can be used instead of the error message specified by the errorPlaceholderMessage property.

getErrorPlaceholderMessage

Gets current value of property errorPlaceholderMessage.

A custom text that is displayed instead of the PDF file content when the PDF file cannot be loaded.

getHeight

Gets current value of property height.

Defines the height of the PDF viewer control, respective to the height of the parent container. Can be set to a percent, pixel, or em value.

Default value is "100%".

sap.m.PDFViewer.getMetadata

Returns a metadata object for class sap.m.PDFViewer.

getPopupButtons

Gets content of aggregation popupButtons.

A multiple aggregation for buttons that can be added to the footer of the popup dialog. Works only if the PDF viewer is set to open in a popup dialog.

getPopupHeaderTitle

Gets current value of property popupHeaderTitle.

A custom title for the PDF viewer popup dialog. Works only if the PDF viewer is set to open in a popup dialog.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getTitle}.
getShowDownloadButton

Gets current value of property showDownloadButton.

Shows or hides the download button.

Default value is true.

getSource

Gets current value of property source.

Specifies the path to the PDF file to display. Can be set to a relative or an absolute path.
Optionally, this property can also be set to a data URI path or a blob URL in all major web browsers except Internet Explorer and Microsoft Edge, provided that this data URI or blob URL is allowed in advance. For more information about URL filtering, see URLList Validator Filtering.

getTitle

Gets current value of property title.

A custom title for the PDF viewer.

getWidth

Gets current value of property width.

Defines the width of the PDF viewer control, respective to the width of the parent container. Can be set to a percent, pixel, or em value.

Default value is "100%".

indexOfPopupButton

Checks for the provided sap.m.Button in the aggregation popupButtons. and returns its index if found or -1 otherwise.

insertPopupButton

Inserts a popupButton into the aggregation popupButtons.

invalidate

Triggers rerendering of this element and its children.

open

Opens the PDF viewer in a popup dialog.

removeAllPopupButtons

Removes all the controls from the aggregation popupButtons.

Additionally, it unregisters them from the hosting UIArea.

removePopupButton

Removes a popupButton from the aggregation popupButtons.

setDisplayType

Sets a new value for property displayType.

Defines how the PDF viewer should be displayed.

  • If set to Link, the PDF viewer appears as a toolbar with a download button that can be used to download the PDF file.
    When the #open method is called, the user can either open the PDF file in a new tab or download it.
  • If set to Embedded, the PDF viewer appears embedded in the parent container and displays either the PDF document or the message defined by the errorPlaceholderMessage property.
  • If set to Auto, the appearance of the PDF viewer depends on the device being used:
    • On mobile devices (phones, tablets), the PDF viewer appears as a toolbar with a download button.
    • On desktop devices, the PDF viewer is embedded in its parent container.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Auto.

setErrorMessage

Sets a new value for property errorMessage.

A custom error message that is displayed when the PDF file cannot be loaded.

When called with a value of null or undefined, the default value of the property will be restored.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getErrorPlaceholderMessage}.
setErrorPlaceholder

Sets the aggregated errorPlaceholder.

setErrorPlaceholderMessage

Sets a new value for property errorPlaceholderMessage.

A custom text that is displayed instead of the PDF file content when the PDF file cannot be loaded.

When called with a value of null or undefined, the default value of the property will be restored.

setHeight

Sets a new value for property height.

Defines the height of the PDF viewer control, respective to the height of the parent container. Can be set to a percent, pixel, or em value.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "100%".

setPopupHeaderTitle

Sets a new value for property popupHeaderTitle.

A custom title for the PDF viewer popup dialog. Works only if the PDF viewer is set to open in a popup dialog.

When called with a value of null or undefined, the default value of the property will be restored.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getTitle}.
setShowDownloadButton

Sets a new value for property showDownloadButton.

Shows or hides the download button.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setSource

Sets a new value for property source.

Specifies the path to the PDF file to display. Can be set to a relative or an absolute path.
Optionally, this property can also be set to a data URI path or a blob URL in all major web browsers except Internet Explorer and Microsoft Edge, provided that this data URI or blob URL is allowed in advance. For more information about URL filtering, see URLList Validator Filtering.

When called with a value of null or undefined, the default value of the property will be restored.

setTitle

Sets a new value for property title.

A custom title for the PDF viewer.

When called with a value of null or undefined, the default value of the property will be restored.

setWidth

Sets a new value for property width.

Defines the width of the PDF viewer control, respective to the width of the parent container. Can be set to a percent, pixel, or em value.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "100%".

addPopupButton

Adds some popupButton to the aggregation popupButtons.

Param Type DefaultValue Description
oPopupButton sap.m.Button

The popupButton to add; if empty, nothing is inserted

attachError

Attaches event handler fnFunction to the error event of this sap.m.PDFViewer.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.PDFViewer itself.

This event is fired when there is an error loading the PDF file.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.PDFViewer itself

attachLoaded

Attaches event handler fnFunction to the loaded event of this sap.m.PDFViewer.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.PDFViewer itself.

This event is fired when a PDF file is loaded. If the PDF is loaded in smaller chunks, this event is fired as often as defined by the browser's plugin. This may happen after a couple chunks are processed.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.PDFViewer itself

attachSourceValidationFailed

Attaches event handler fnFunction to the sourceValidationFailed event of this sap.m.PDFViewer.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.PDFViewer itself.

This event is fired when the PDF viewer control cannot check the loaded content. For example, the default configuration of the Mozilla Firefox browser may not allow checking the loaded content. This may also happen when the source PDF file is stored in a different domain. If you want no error message to be displayed when this event is fired, call the preventDefault() method inside the event handler.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.PDFViewer itself

destroyErrorPlaceholder

Destroys the errorPlaceholder in the aggregation errorPlaceholder.

destroyPopupButtons

Destroys all the popupButtons in the aggregation popupButtons.

detachError

Detaches event handler fnFunction from the error event of this sap.m.PDFViewer.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachLoaded

Detaches event handler fnFunction from the loaded event of this sap.m.PDFViewer.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachSourceValidationFailed

Detaches event handler fnFunction from the sourceValidationFailed event of this sap.m.PDFViewer.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

downloadPDF

Downloads the PDF file.

sap.m.PDFViewer.extend

Creates a new subclass of class sap.m.PDFViewer with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireError

Fires event error to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

target any

The iframe element.

fireLoaded

Fires event loaded to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireSourceValidationFailed

Fires event sourceValidationFailed to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getDisplayType

Gets current value of property displayType.

Defines how the PDF viewer should be displayed.

Default value is Auto.

getErrorMessage

Gets current value of property errorMessage.

A custom error message that is displayed when the PDF file cannot be loaded.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getErrorPlaceholderMessage}.

getErrorPlaceholder

Gets content of aggregation errorPlaceholder.

A custom control that can be used instead of the error message specified by the errorPlaceholderMessage property.

getErrorPlaceholderMessage

Gets current value of property errorPlaceholderMessage.

A custom text that is displayed instead of the PDF file content when the PDF file cannot be loaded.

getHeight

Gets current value of property height.

Defines the height of the PDF viewer control, respective to the height of the parent container. Can be set to a percent, pixel, or em value.

Default value is "100%".

sap.m.PDFViewer.getMetadata

Returns a metadata object for class sap.m.PDFViewer.

getPopupButtons

Gets content of aggregation popupButtons.

A multiple aggregation for buttons that can be added to the footer of the popup dialog. Works only if the PDF viewer is set to open in a popup dialog.

getPopupHeaderTitle

Gets current value of property popupHeaderTitle.

A custom title for the PDF viewer popup dialog. Works only if the PDF viewer is set to open in a popup dialog.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getTitle}.

getShowDownloadButton

Gets current value of property showDownloadButton.

Shows or hides the download button.

Default value is true.

getSource

Gets current value of property source.

Specifies the path to the PDF file to display. Can be set to a relative or an absolute path.
Optionally, this property can also be set to a data URI path or a blob URL in all major web browsers except Internet Explorer and Microsoft Edge, provided that this data URI or blob URL is allowed in advance. For more information about URL filtering, see URLList Validator Filtering.

getTitle

Gets current value of property title.

A custom title for the PDF viewer.

getWidth

Gets current value of property width.

Defines the width of the PDF viewer control, respective to the width of the parent container. Can be set to a percent, pixel, or em value.

Default value is "100%".

indexOfPopupButton

Checks for the provided sap.m.Button in the aggregation popupButtons. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oPopupButton sap.m.Button

The popupButton whose index is looked for

insertPopupButton

Inserts a popupButton into the aggregation popupButtons.

Param Type DefaultValue Description
oPopupButton sap.m.Button

The popupButton to insert; if empty, nothing is inserted

iIndex int

The 0-based index the popupButton should be inserted at; for a negative value of iIndex, the popupButton is inserted at position 0; for a value greater than the current size of the aggregation, the popupButton is inserted at the last position

invalidate

Triggers rerendering of this element and its children.

Param Type DefaultValue Description
oOrigin sap.ui.base.ManagedObject

Child control for which the method was called

open

Opens the PDF viewer in a popup dialog.

removeAllPopupButtons

Removes all the controls from the aggregation popupButtons.

Additionally, it unregisters them from the hosting UIArea.

removePopupButton

Removes a popupButton from the aggregation popupButtons.

Param Type DefaultValue Description
vPopupButton int string sap.m.Button

The popupButton to remove or its index or id

setDisplayType

Sets a new value for property displayType.

Defines how the PDF viewer should be displayed.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Auto.

Param Type DefaultValue Description
sDisplayType sap.m.PDFViewerDisplayType Auto

New value for property displayType

setErrorMessage

Sets a new value for property errorMessage.

A custom error message that is displayed when the PDF file cannot be loaded.

When called with a value of null or undefined, the default value of the property will be restored.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getErrorPlaceholderMessage}.
Param Type DefaultValue Description
sErrorMessage string

New value for property errorMessage

setErrorPlaceholder

Sets the aggregated errorPlaceholder.

Param Type DefaultValue Description
oErrorPlaceholder sap.ui.core.Control

The errorPlaceholder to set

setErrorPlaceholderMessage

Sets a new value for property errorPlaceholderMessage.

A custom text that is displayed instead of the PDF file content when the PDF file cannot be loaded.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sErrorPlaceholderMessage string

New value for property errorPlaceholderMessage

setHeight

Sets a new value for property height.

Defines the height of the PDF viewer control, respective to the height of the parent container. Can be set to a percent, pixel, or em value.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "100%".

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize "100%"

New value for property height

setPopupHeaderTitle

Sets a new value for property popupHeaderTitle.

A custom title for the PDF viewer popup dialog. Works only if the PDF viewer is set to open in a popup dialog.

When called with a value of null or undefined, the default value of the property will be restored.

Since 1.50.0 replaced by {@link sap.m.PDFViewer#getTitle}.
Param Type DefaultValue Description
sPopupHeaderTitle string

New value for property popupHeaderTitle

setShowDownloadButton

Sets a new value for property showDownloadButton.

Shows or hides the download button.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bShowDownloadButton boolean true

New value for property showDownloadButton

setSource

Sets a new value for property source.

Specifies the path to the PDF file to display. Can be set to a relative or an absolute path.
Optionally, this property can also be set to a data URI path or a blob URL in all major web browsers except Internet Explorer and Microsoft Edge, provided that this data URI or blob URL is allowed in advance. For more information about URL filtering, see URLList Validator Filtering.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sSource sap.ui.core.URI

New value for property source

setTitle

Sets a new value for property title.

A custom title for the PDF viewer.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sTitle string

New value for property title

setWidth

Sets a new value for property width.

Defines the width of the PDF viewer control, respective to the width of the parent container. Can be set to a percent, pixel, or em value.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "100%".

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize "100%"

New value for property width