Add block: Document/PDF with Preview

[wpfangirl]

Is your feature request related to a problem? Please describe.
CF #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: #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

[matt-carboncoop]

Adding pdf embeds as proposed in #24233 doesn't solve the problem outlined here and there are already plugins for pdf embedding for those that require it. The problem is that embedding provides an inconsistent user experience (especially on mobile), slows browsing and that most pdfs are unreadable in context of block display. As WP is already generating thumbnails, displaying these linked to the pdf file would provide a more consistent experience all round.

[wpfangirl]

Wow, I didn't realize it had been more than a year since I first brought this up. @matt-carboncoop is quite right: embeds are awkward at the best of times, and depending on how they're created, may be less accessible than the actual PDF files. Plus there's the performance issue. I've used my ACF version of this block a lot since I built it, but it would be a lot smoother as a native block and I haven't yet figured out a way to use it for a gallery besides sticking the thumbnails in separate columns. (No, I still haven't learned React to attempt doing this as a native block.)

[paaljoachim]

Gary @pento opened a new PR here: #30857
Test it out and give feedback.

Here is a fairly easy way to test out the PR.
Follow this testing method to download a special version of the Gutenberg plugin: https://make.wordpress.org/design/2021/03/03/testing-a-gutenberg-pull-request-pr/

[idea--list]

Guys you seem to be somewhat stubborn...
By simply not understanding that only the minority of people need PDFs embedded into a designed layout/content.

Most people
EITHER want something like ISSUU.com's pdf viewer with pagination animation
OR they want a cover image that opens the PDF file when the user clicks on the thumbnail

There is absolutely NO change in your mindset despite several of us already gave you the same feedback over several years now.
However you still could not decide to merge the PR. Well...why do you ask us to test if you always insist to the original idea, but still do not merge that??!! While in the background WP still autogenerates a thumbnail for the PDF file based on its first page (in case imagick is active on the server)... but that thumbnail just sits on the server without people could take any advantage of it with GB.

All this makes no sense for me. This basic feature would be really easy&fast to implement finally in GB in case you just would not insist to keep forcing that embedder without any other choice.

[wpfangirl]

Gary @pento opened a new PR here: #30857
Test it out and give feedback.

Here is a fairly easy way to test out the PR.
Follow this testing method to download a special version of the Gutenberg plugin: https://make.wordpress.org/design/2021/03/03/testing-a-gutenberg-pull-request-pr/

First, that gutenberg.run thing is cool. Made it very easy to test.

Second, I'm afraid @idea--list is right: while there may be use for an embed version of PDFs and it looked and worked okay as such, what I was actually looking for was just an option to display the PDF thumbnail with a choice of thumbnail sizes.

This was dead easy to do in PHP using ACF Blocks:

$pdf = get_field( 'pdf_file');
$size = get_field( 'image_size');

echo '<div id="' . esc_attr($id) . '" class="' . esc_attr($className) . '">';
echo '<a class="link-to-pdf" title="' . $pdf['filename'] . '" href="' . $pdf['url'] . '">';
if( has_post_thumbnail( $pdf['ID'] ) ){
	echo get_the_post_thumbnail( $pdf['ID'], $size, array( 'alt' => $pdf['title'] ) );
}
else {
	echo wp_get_attachment_image( $pdf['ID'], $size, false, array( 'alt' => $pdf['title'] ) );
}
echo '</a>';
echo '</div>';

[SallyMoo]

I agree wholeheartedly with @idea--list.

To summarise what I'm looking for ... the ability to upload a pdf (using the Media button?), and it displays (or gives me the option of displaying) a thumbnail of the cover of the pdf as a link to open the actual pdf. Flaffing around with blocks, zoom tools, download buttons etc etc may be of interest to some people, but not me.

P.S. I don't even use Gutenberg - tried it once, that was enough. ;)

[paaljoachim]

Hey @idea--list Peter

The reason why I shared the PR here is to suggest adjustments to the PR that @pento Gary is creating.

Brainstorming here....
Let's say that one can extend additional options here:

I suggest adding a toggle to "Show first page"
When it is activated an Image size drop down is seen.

I also added under Text link settings a "Show text link" toggle. So one can hide the text link.

Thoughts?

[matt-carboncoop]

With those adjustments I'd say it would be perfect. Started working on yet another legacy site, where the NGO staff are taking and cropping screenshots to achieve just this, would really speed up workflow. What are your thoughts @pento?

…

On Sat, 17 Apr 2021, 11:07 Paal Joachim Romdahl, ***@***.***> wrote: Hey @idea--list <https://github.com/idea--list> Peter The reason why I shared the PR here is to suggest adjustments to the PR that @pento <https://github.com/pento> Gary is creating. Brainstorming here.... Let's say that one can extend additional options here: [image: Screen Shot 2021-04-17 at 11 08 04] <https://user-images.githubusercontent.com/5323259/115107774-3f77ce80-9f6d-11eb-9f84-c11cccebb6dd.png> I suggest adding a toggle to "Show first page" When it is activated an Image size drop down is seen. [image: Preview-PDF-file-show-first-page] <https://user-images.githubusercontent.com/5323259/115109295-3ee33600-9f75-11eb-979e-3be7821638fc.jpg> I also added under Text link settings a "Show text link" toggle. So one can hide the text link. [image: Show-text-link] <https://user-images.githubusercontent.com/5323259/115109282-1d824a00-9f75-11eb-91ab-99e03ee829a2.png> Thoughts? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#19077 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAXCNST3MUSORDEA3ZFNKPLTJFMVJANCNFSM4JZWJHHQ> .

[wpfangirl]

@paaljoachim That looks good. I would recommend setting up some means of adding an ALT tag, though, even if it's just coded to say "Screenshot of first page of <filename>."

[StaggerLeee]

For me it is fine with thumbnail extracted from PDF and click opens browser native PDF viewer (native fullscreen, most important).
But, if you want to extend it and make it with more options who I am to limit your creativity. :)

---

Please do not forget to make it able to have real Post Thumbnail from extracted PDF image, not only as simple Post image. There are many websites that use it for Archive / Blog template.
Mostly something as weekly or monthly (non-mail) newsletters.

[paaljoachim]

I added the Alt text field.
Here is version 2.

[wpfangirl]

Alt text looks good. What I can't tell from your screenshot is whether you see the full first page in its natural ratio.

[paaljoachim]

I "cut" the image to show the text link and button below.
It is supposed to be a large image. As that is what is selected in the Image Size setting. (It is though just a mockup made in Affinity Photo.) I am hoping that Pento will add these adjustments or something similar.

[idea--list]

@paaljoachim
The screenshot of version 2 begins to make sense.
The only thing i still miss is the possibility to override the cover image.
Why that? Because some PDF files have a really boring cover page.

[pento]

Thank you for the feedback, everyone! I've been experimenting with adding these additional options, I think they would be better handled in a separate PR, for two reasons:

There's quite a lot of additional complexity, both in implementation (this should likely be built as a child Image block, rather than partial re-implementation of the Image block features), and in UI (there are a lot of additional options here).

Besides the complexity, this is moving away from being a PDF-specific feature, to being a feature which I can easily imagine wanting to be used with any file type. I think it should be explored further in that context, rather than trying to implement it just in the PDF context.

This is not to say that these changes shouldn't happen, just that I think they'd be better done in a PR with that broader vision in mind.

[wpfangirl]

@paaljoachim
The screenshot of version 2 begins to make sense.
The only thing i still miss is the possibility to override the cover image.
Why that? Because some PDF files have a really boring cover page.

That sounds like a problem with the PDF, rather than the block.

[idea--list]

@wpfangirl
Until the same person/organization authors the PDF that manages the website you are right.
However that is not always the case. For sure adding such a possibility does not break any other functionality of the block.
So i do not see why that should not be part of an implementation.

[wpfangirl]

@idea--list Fair enough. In use cases I've encountered so far it hasn't mattered a lot if the PDF is boring to look at.

[paaljoachim]

The initial PR has been merged. A next step would be to focus on how the File block can use Inner/child blocks so we can get the features mentioned here in place. That would require a new issue. I will look into it.

[matt-carboncoop]

Hi @paaljoachim, did you get anywhere with this? The version now in Gutenberg works well, but doesn't meet any of my use cases. While I understand @pento's point that it might be useful to extend to other file types, I've not seen this being called for, where as it's a regular feature request on the many pdf embed blocks that already exist. I think what's confusing people is the wp is already generating the thumbnails and has been for some years, was there a plan for these when this feature was added?

[talldan]

Seems like the original request has been achieved in the file block.

Please could any additional feature requests be moved into new issues. Commenting them here makes them very hard for contributors to find.

[lifesbrain]

The original request doesn't seem complete at all, unless I'm missing something. Embedding the PDF is now part of the file block but I'm failing to find an option for a thumbnail. If you want to link to dozens or more PDFs then embedding them is incredibly clunky, not to mention not working on most mobile devices. Having the option of including the generated thumbnail, as you would when adding an image, would be incredibly useful. I feel that was the original request. One I've been hoping for, as well as the many users above.

[paaljoachim]

Hey @lifesbrain Michael and others.

It would be helpful to create a new issue and we can continue the discussion there. (I have not yet been able to look closer at what is needed here.) In the new issue we can add links to specific comments here (or just recreate them there).

[talldan]

@lifesbrain Good point. @paaljoachim had already opened an issue open for pdf thumbnails before this so I think that's still relevant - #15097.

[paaljoachim]

Ahhh yes. Thank you Dan!