Add "Direct Embed (Google Viewer fallback)" display method — browser <object> with Google Docs Viewer fallback

Problem/Motivation

The existing Google Viewer display type routes all PDFs through docs.google.com/viewer. This is unreliable in practice:

• Google throttles or refuses requests for large files, frequently updated files, or sites with high traffic
• PDFs hosted on private or authenticated file systems cannot be passed to Google's external service
• It introduces an unnecessary third-party dependency for a task modern browsers handle natively
• Users on restricted networks (corporate firewalls, government environments) may be blocked from docs.google.com entirely

Modern browsers — Chrome 90+, Firefox 87+, Edge 90+, Safari 16.4+ — all include a native PDF renderer accessible via

. No plugin, no external service, no JavaScript required to trigger it. The existing Direct Embed option also uses but has no graceful fallback when native rendering is unavailable (e.g. older Android browsers, or Chrome with "Download PDFs" enabled in settings).

Proposed resolution

Add a new display method: "Direct Embed (Google Viewer fallback)" (machine key: native).

This renderer:

1. Uses for browsers with native PDF support — detected client-side via the standardised navigator.pdfViewerEnabled API (Chrome 90+, Firefox 87+, Edge 90+,
2. Safari 16.4+).
3. Falls back to the Google Docs Viewer for browsers that cannot render PDFs natively.
4. Shows a visible "PDF not displaying?" hint — with a reload button and download link — only when the Google Docs fallback is active.
5. Respects the existing embed_view_fit and embed_hide_toolbar formatter settings (appended as PDF open-parameter fragments to the URL).
6. Uses data-pdf-url / data-pdf-viewer-url data attributes instead of directly populating / in HTML, so raw file URLs are not present in the page source at load time (reduces search engine crawlability of the underlying file path).
7. Optional integration with media_entity_download: When the field is attached to a Media entity and the media_entity_download module is enabled, the source uses /media/{id}/download?inline=1 instead of the raw file URI. This keeps the file system path out of the HTML entirely, and access control is enforced by Drupal rather than relying on security-by-obscurity.
8. Displays accessible title attributes on both and using the Media entity label (when available) or filename as a fallback — no hard dependency on the Media module.

All existing display types are unchanged. The native option is a non-breaking addition.

Changes

Modified files:

• pdf_reader.module — registers pdf_reader_native theme hook with variables: service, file_url, viewer_url, file_name, width, height, download_link, top, bottom
• pdf_reader.libraries.yml — adds native library (depends on core/drupal and core/once, no jQuery)
• src/Plugin/Field/FieldFormatter/FieldPdfReaderField.php — adds native option to getPdfDisplayOptions() and corresponding case 'native': in viewElements()

New files:

• js/native.js — Drupal.behaviors.pdfReaderNative: detects navigator.pdfViewerEnabled, injects URLs from data attributes at runtime, handles reload button
• templates/pdf-reader-native.html.twig — wrapping wrapping

  fallback chain; accessible titles; hidden hint paragraph with aria-live="polite"

• tests/src/Unit/Plugin/Field/FieldFormatter/FieldPdfReaderFieldTest.php — unit tests (no container): display options, default settings, regression guard for existing options
• tests/src/Kernel/Plugin/Field/FieldFormatter/NativePdfFormatterTest.php — kernel tests: render array structure, template output (, , hint markup, aria-live, library attachment), regression guard for google display type

Browser support

• │ Browser │ navigator.pdfViewerEnabled │ Result │
• │ Chrome 90+ │ true │ Native │
• │ Firefox 87+ │ true │ Native │
• │ Edge 90+ │ true │ Native │
• │ Safari 16.4+ │ true │ Native │
• │ Chrome (Download PDFs enabled) │ false │ Google Docs │
• │ Older Android browsers │ false or undefined │ Google Docs │

Steps to test

1. Apply the patch and run drush cr
2. Edit a file field display → confirm "Direct Embed (Google Viewer fallback)" appears in the Renderer dropdown
3. Set renderer to "Direct Embed (Google Viewer fallback)", save, view a node with a PDF file attached
4. In Chrome/Firefox/Safari: inspect DOM — confirm has its data attribute set by JavaScript (not present in page source)
5. Confirm no request to docs.google.com in the Network tab
6. Simulate fallback: in Chrome, go to Settings → Privacy and security → Site settings → PDF documents → enable "Download PDFs". Reload — the Google Docs should load and the "PDF not displaying?" hint should appear.
7. Run vendor/bin/phpunit web/modules/contrib/pdf_reader/tests/ --group pdf_reader

AI assisted planning and coding

• Claude.ai and Claude code assisted in the planning and creation of this code
• Manual verification of code and testing of features and fallbacks scenarios