Gutenberg: Add block: Document/PDF with Preview

[wpfangirl]

Is your feature request related to a problem? Please describe.
CF https://github.com/WordPress/gutenberg/issues/15097

PDF thumbnails (preview images) were introduced in WordPress 4.7. Displaying PDF thumbnails works exactly the same as displaying image thumbnails, via wp_get_attachment_image(), as long as $icon is set to false. This is how the attachment single page displays PDFs and (I assume) how the Media Library itself displays the PDF thumbnails.

These thumbnail images don't show up for the image block or for galleries because the attachment itself isn't an image. If you know the direct URL to the thumbnails (which can be exposed using something like the Display All Image Sizes plugin), you can insert them via link and connect them to the PDF, but this is a clumsy process.

If my clients are any example, many users of WordPress produce a LOT of PDF files, and they want to display them with something more than a link. There's a reason that the Document Gallery plugin still has 20,000 active installations even though it hasn't been updated since WordPress 4.9 and the PDF Embedder plugin has 200,000 active installations.

Describe the solution you'd like
I want a PDF preview block that automatically inserts the chosen thumbnail size and links it to the PDF file--or even a document block that would insert an icon for a Word doc or PowerPoint or text file. The Media Library does this automatically, so the functionality is obviously in core.

A gallery block for documents would be a nice bonus.

Describe alternatives you've considered
I have created a custom block via ACF to use on client sites for now. It has a file upload field and a selector for the image size. Unfortunately, I don't have the JS skills to convert that into a real block and submit it to the repository as a block plugin. But given the number of PDF files I have to deal with, I didn't want to spend a lot of time inserting the thumbnails via URL and linking them ditto.

[melchoyce]

Hey @wpfangirl! The design team chatted about this in our weekly triage, and we agree providing document previews would be super useful.

We think it would make the most sense to enhance the existing File block to handle this scenario:

Some additional options for consideration:

• Preview size
• Potentially make the preview option on by default
• Embed the file itself into the page as an iframe or something, rather than using a static preview

A gallery block for documents would be a nice bonus.

This could be a great enhancement to file block – allow uploading of multiple files, then display an option to display as a list or a grid. (h/t @paaljoachim for the idea)

[wpfangirl]

I'd envisioned the download button below the text title, as titles can get pretty long pretty quickly. Picture that thumbnail with something like "FY 2018-2019 Audited Financial Report" for a title. Does the title wrap? Where does the button end up?

I think the interface mockup looks good, though. It's about what I'd imagined.

Regarding preview image size, that's probably something to leave up to the user, because everyone will have a different use case. I usually set the height for the WP-generated sizes to "0" and turn off force-cropping for thumbnails.

The thing about documents is that they could be portrait or landscape, letter or legal or broadsheet or A4 or A3... You might even have people who are happy to show square thumbnails of documents, though that would definitely not be me.

Maybe add a tip somewhere about how document previews will look better at sizes that aren't force cropped? (Probably the wrong phrasing to use for beginners.)

Thanks so much for taking this on!

[melchoyce]

I'd envisioned the download button below the text title, as titles can get pretty long pretty quickly. Picture that thumbnail with something like "FY 2018-2019 Audited Financial Report" for a title. Does the title wrap? Where does the button end up?

This is how the file block currently works. Looks like it does wrap (kind of poorly):

Regarding preview image size, that's probably something to leave up to the user, because everyone will have a different use case.

Yeah, was thinking we could do what the image block does and provide some default sizes with the option to override and resize.

Maybe add a tip somewhere about how document previews will look better at sizes that aren't force cropped? (Probably the wrong phrasing to use for beginners.)

I didn't think we'd do any cropping, we'd should the full preview of the first page of the document. Do you think there should be a crop feature to the preview?

[wpfangirl]

I think we should show the full first page, but I did imagine a typical image size selector dropdown. (Which I only now noticed isn't in the mockup.) Won't we otherwise end up with a responsive images problem? (You know, "image resized in CSS blah blah" from the performance scans.)

[melchoyce]

Yeah, if we included a size setting, it would be this:

[wpfangirl]

Yes, that's what I was imagining. I don't see any reason to make it different from what's used for the image block.

[thune]

This would solve a problem that has annoyed me since I started in this web business back in 1996. Are we finally getting there? How about raising that priority to high :-)

[idea--list]

Like all what i read here, just one more idea:
Some PDFs have a really boring 1st page that just will not work as a preview image.
For such cases it would be great to add an option to the UI that enables the user to select the preview image from the media library.

[wpfangirl]

Choosing an alternative image would be a nice add-on, but I don't think it's necessary for V1. (I confess I have created nice cover pages for client PDFs because of exactly the issue that @idea--list mentions.)

[SallyMoo]

I have a client with exactly the same requirement (ie to be able to show a thumbnail of the front page of hundreds of pdf magazines uploaded, with a link to the pdf file).

Following for futher updates. :)

[StaggerLeee]

It works well if you upload PDF via featured image option (featured image on Archive template shows right). But later it is gone, nowhere to find in modal box.
Strange, everything is already there and just little is missing to make it work.

[nickhamze]

A gallery block for documents would be a nice bonus.

It's not exactly what you are looking for I recently released a plugin that could be described as a gallery for documents:
https://wordpress.org/plugins/card-catalog/

[SallyMoo]

It's not exactly what you are looking for I recently released a plugin that could be described as a gallery for documents:
https://wordpress.org/plugins/card-catalog/

nickhamze - If this could be developed to show a preview image of the first page of each pdf, rather than the same default pdf icon for all, that would be great.

[wpfangirl]

The old Document Gallery plugin managed to do this, but it's not been maintained and isn't particularly Gutenberg-friendly.

[monikaevers]

I am with wpfangirl....Businesses need a list of pdfs identified by title, thumb nail, separated by fine line. Options to VIEW at full size on screen or DOWNLOAD and to be able to upload from media gallery.

[paaljoachim]

@pento has created a PR here: https://github.com/WordPress/gutenberg/pull/24233
(I am posting this so that everyone who has posted here gets an e-mail about it.)

[idea--list]

The ability to add pdf _embeds_ with #24233 sounds good.
However most of the time i find my clients rather prefer inserting a thumbnail image (usually that of the cover page of the pdf) and link the URL of the PDF-file to that thumbnail.

IMHO this has the benefits over embedding:

• There is no embedded PDF-viewer, which would ruin the design of the page without any control
• No matter which browser the user has, they will be able to read the PDF by clicking on the thumbnail image