Skip to main content

Custom PDF Viewer

Yoko Core ships with a custom in-page PDF viewer that is an implementation of the Mozilla PDF reader project. Using a custom in-page PDF viewer has a few advantages:

  1. PDF Gating - It allows us to gate PDFs in a way we couldn't before because when a user accesses the PDF, we actually load a page template with the JS PDF viewer embedded on the page instead of making the user just download the document and letting the browser open it. This means that we can run logic upstream from the page template that determines whether the current user should have access to this page or not the same way we do with other WordPress posts.
  2. PDF Search Deeplinking - We can actually deep link to a search in the PDF to make it easier for the user to find the content they were looking for.
  3. Extensibility - This viewer is extensible and configurable, so we can add other functionality in the future including the ability to edit the PDF.
YOU MUST USE THE ATTACHMENT PERMALINK!

In order for the PDF viewer to render, you must link to the attachment post permalink, NOT the PDF file link. To make this easier, most function that would normally render the PDF file link has been filtered to return the attachment permalink instead, but it is still possible to accidentally copy and PDF file link.

How to Activate Custom PDF Viewer​

The PDF viewer can be activated in two different places:

  1. Settings -> Media - The native WordPress Media page now has options to turn on and manage this feature for all PDF media types.
  2. "PDF Viewer Options" Metabox - Each PDF media item has a PDF Viewer Options metabox that lets you use this viewer ad-hoc, on a case-by-case basis instead of turning it on for all PDF media posts on the site.

"PDF Viewer Options" Metabox​

The PDF Viewer Options metabox allows using the PDF Viewer functionality ad-hoc on a case-by-case basis instead of across the entire website.

alt text

  1. Use Yoko PDF viewer for this PDF - Choosing this option activates the PDF viewer for just this PDF media item. Turning this option on will also reveal the Content Protection metabox so that the PDF can be gated.
  2. Allow PDF download from permalink - Choosing this option will allow for the PDF to be downloaded from the permalink of the attachment post. This option is only available if #1 is not checked.
  3. Allow search engines to index PDF - This option adds the PDF content to the JSONLD of the "Access Denied" page so that search engines can index the content while still blocking the PDF from public access.
  4. Force PDF download (does not render in browser) - When enabled, the PDF will be forced to download to the user's computer instead of rendering in the browser. This ensures users work from a local file copy rather than filling out forms in the browser viewer. This option is only available when the PDF viewer is enabled (#1 is checked) and respects all content gating restrictions.
  5. "Preview PDF in Viewer" Button - This will allow you to preview what the PDF will look like in the in-page PDF viewer.

There are several ways to get the attachment post permalink.

Getting the Attachment Post Permalink from the Media Library​

  1. The permalink under the attachment post title.

Permalink under the Attachment Post Title

  1. The "Copy URL to Clipboard" button in the "Save" meta box.

Permalink from Copy URL to Clipboard button

  1. "Copy URL" or "View" quick link on the Media Library page.

Permalink from Media posts quicklinks

  1. The Gutenberg File Block Link To setting.

Permalink in File Block settings

The PDF Viewer search can be prepopulated by adding #search=[SEARCH QUERY] to the end of the PDF attachment media post's permalink.

Force Download Feature​

The Force Download feature allows you to configure PDFs to automatically download to the user's computer instead of rendering in the browser. This is particularly useful when:

  • Users need to fill out PDF forms locally rather than in the browser
  • You want to ensure users work from a saved copy of the document
  • Forms or interactive elements in the PDF work better in desktop PDF readers

How Force Download Works​

When enabled, the Force Download option:

  1. Respects Content Gating - All content protection and access restrictions are checked first, before the download is initiated
  2. Uses the Attachment Permalink - The download is triggered when accessing the PDF's attachment post permalink (not the direct file URL)
  3. Prevents Browser Rendering - The PDF file is sent with headers that force the browser to download rather than display the file
  4. Preserves Original Filename - The downloaded file retains its original filename

Enabling Force Download​

To enable Force Download for a specific PDF:

  1. Navigate to Media Library and edit the PDF attachment
  2. In the PDF Viewer Options metabox, check "Use Yoko PDF viewer for this PDF"
  3. Check "Force PDF download (does not render in browser)"
  4. Click Update to save your changes

Once enabled, any user accessing the PDF's attachment permalink will automatically receive a download prompt instead of seeing the PDF rendered in their browser.

Content Gating Integration

Force Download works seamlessly with content gating. If a PDF is gated and a user doesn't have access, they will see the access denied page. Only users with proper access will receive the download.

When linking to the PDF from a block theme, it is extremely important that the "File Block" is configured to link to the Attachment page and not the Media file.

Permalink in File Block settings