DOCSEARCHbyAlgolia
Submit Docs

PDFObject Documentation

repository·master·Indexed 25 days ago

https://github.com/pipwerks/pdfobject

A lightweight JavaScript utility (v2.3.1) for dynamically embedding PDF files into HTML documents using iframes. It provides a multi-layered detection strategy for browser PDF support, fallback mechanisms for mobile devices and unsupported browsers, and integration options for PDF.js. Key features include support for Base64 encoded PDFs, Adobe PDF Open Parameters via pdfOpenParams, and the PDFObject.supportsPDFs property for conditional logic.

Tokens
1.3K
Snippets
0
Records
12
Agent score
82%

What's inside PDFObject

  1. How PDFObject detects PDF support

    master

    PDFObject uses a multi-layered detection strategy to determine if a browser can render PDFs inline:

    1. Mobile Detection: PDFObject automatically assumes PDFs are not supported on mobile devices (Android, iOS), as mobile browsers generally do not support inline PDFs. It will display fallback content instead.
    2. navigator.pdfViewerEnabled: On non-mobile devices, PDFObject checks this property. If it is true, the PDF is embedded. If it is false (user-disabled), PDFObject treats it as unsupported.
    3. Fallback Logic: If navigator.pdfViewerEnabled is unavailable, PDFObject checks the user agent:
      • Native Support: Browsers like Chrome, Edge, Opera, macOS Safari, and Firefox are assumed to support inline PDFs.
      • Internet Explorer: PDFObject queries ActiveX for known PDF plugins like Adobe Acrobat or Foxit.

    Note: Since version 2.3, PDFObject uses <iframe> elements by default instead of <embed> for better universal support and consistency.

  3. Configure PDF Open Parameters

    master

    You can control how the PDF is opened (e.g., specific pages, views, or highlights) by passing an object to the pdfOpenParams option within embed(). PDFObject converts these into a URL fragment identifier (e.g., #page=2&view=FitH).

    Supported Parameters (via pdfOpenParams):

    • page: The page number to display. Note: If comment, viewrect, or highlight are used, a page must be specified (it defaults to 1 if not provided).
    • fdf: A path to an FDF file.
    • Other standard Adobe PDF Open Parameters can be passed as key-value pairs.

  4. Handle Base64 encoded PDFs

    master

    If the url passed to embed() is a Base64 data URI (e.g., data:application/pdf;base64,...), PDFObject will automatically attempt to convert it into a downloadable link if the browser does not support inline embedding.

    Options:

    • fallbackFileNameForBase64 (string): The filename used for the generated download link. If not provided, it attempts to extract the filename from the data URI metadata or defaults to file.pdf.

  5. Configure fallback filename for base64 PDFs

    master
    When using a base64 encoded PDF string and the browser does not support inline PDF embedding, PDFObject can provide a fallback download link. Use the fallbackFileNameForBase64 option to specify the filename for the downloaded PDF. If this option is not provided, the filename defaults to file.pdf.

  6. Use PDF.js as a fallback viewer

    master

    If the browser does not support native inline PDFs, you can provide a URL to a PDF.js viewer via the PDFJS_URL option. PDFObject will then attempt to load the PDF through that viewer.

    Options:

    • forcePDFJS (boolean): If true, PDFObject will skip native detection and immediately attempt to use the PDF.js viewer.
    • PDFJS_URL (string): The URL to the PDF.js viewer (e.g., https://your-server.com/pdfjs/web/viewer.html).

  8. Configure PDFObject to omit inline styles

    master
    If you are working in a strict environment where inline styles are not permitted, you can set the omitInlineStyles option to true. When this is enabled, you are responsible for applying the necessary styling for the PDF container via your own CSS.

  9. Deprecated PDFObject options

    master

    As of version 2.3, PDFObject has moved from using <embed> to <iframe> as the primary embedding method. Consequently, the following options are now obsolete. They are safe to keep in your code and will not throw errors, but they are no longer used:

    • assumptionMode
    • forceIframe
    • supportRedirect

  10. Embed a PDF using PDFObject.embed()

    master

    The embed() method is the primary way to insert a PDF into an HTML document. It attempts to embed the PDF using an <iframe> if the browser supports it. If support is unavailable, it can fall back to a PDF.js viewer (if configured) or display a fallback link for the user to download the file.

    Parameters:

    • url (string): The URL of the PDF file to embed.
    • targetSelector (string|jQuery|HTMLElement|boolean): The CSS selector, jQuery object, or HTML element where the PDF should be embedded. If omitted or false, it defaults to document.body.
    • options (object): Configuration options to customize the embedding behavior.

    Common Options:

    • page (number): The page number to start on.
    • pdfOpenParams (object): A set of Adobe PDF Open Parameters (e.g., view, zoom, highlight) passed as a fragment identifier.
    • fallbackLink (string|boolean): If true (default), a default fallback link is shown. If a string is provided, it is used as custom HTML, where [url] is replaced by the PDF URL. If false, no fallback is shown.
    • width (string): The width of the iframe (default: `

  12. Check PDF support with PDFObject.supportsPDFs

    master

    The supportsPDFs property is a boolean that indicates whether the current browser supports inline PDF embedding. This is useful for conditional logic in your application before attempting to call embed().

    Note: This property accounts for modern browser features like navigator.pdfViewerEnabled, Chromium-based browsers, Safari, Firefox, and legacy Internet Explorer ActiveX plugins, but it returns false for mobile devices as they generally do not support inline PDFs.