Add support for book front covers #14330

bblhd · 2025-11-16T16:20:28Z

This pull request adds support for cover images which can display in the preview of entries. It also allows new entries to automatically download cover images from either "https://bookcover.longitood.com" or "https://covers.openlibrary.org", and preferences to control downloading behaviour. Key changes are:

The ability for PreviewViewer to display images
A new BookCoverFetcher class to download cover images
Hooks in NewEntryViewModel to do cover fetching
New options in FilePreferences and LinkedFilesTab

Steps to test

Add a new entry using the ISBN "978-1449310509", if you open the preview for the new entry, the cover image should be visible.
Under File > Preferences, in the Linked Files tab, disable the "Automatically download cover images" setting.
Add a new entry using the ISBN "978-1449373320", there should be no cover image if you open the preview.

Mandatory checks

I own the copyright of the code submitted and I license it under the MIT license
I manually tested my changes in running JabRef (always required)
I added JUnit tests for changes (if applicable)
I added screenshots in the PR description (if change is visible to the user)
I described the change in CHANGELOG.md in a way that is understandable for the average user (if change is visible to the user)
I checked the user documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request updating file(s) in https://github.com/JabRef/user-documentation/tree/main/en.

Images

…book-front-cover-10120

…ded experimental "covers" subfolder

github-actions · 2025-11-16T16:20:38Z

Hey @bblhd!

Thank you for contributing to JabRef! Your help is truly appreciated ❤️.

We have automatic checks in place, based on which you will soon get automated feedback if any of them are failing. We also use TragBot with custom rules that scans your changes and provides some preliminary comments, before a maintainer takes a look. TragBot is still learning, and may not always be accurate. In the "Files changed" tab, you can go through its comments and just click on "Resolve conversation" if you are sure that it is incorrect, or comment on the conversation if you are doubtful.

Please re-check our contribution guide in case of any other doubts related to our contribution workflow.

jabgui/src/main/java/org/jabref/gui/importer/BookCoverFetcher.java

jablib/src/main/java/org/jabref/logic/util/URLUtil.java

bblhd · 2025-11-17T11:48:27Z

I have attempted to unmodify submodules without success, both in the past and currently, though I was unaware how much of a problem it was.

I've tried all suggested fixes unsuccessfully, either commit ids are not found or the commands have no effect at all. It seems to be something wrong with my version of git or my repository. For context, I'm using git version 2.51.2_1, on linux, with a basic command line and no IDE.

In theory, this could be fixed by creating a new branch and pull request, but the contributors guide specifically requests not to.

Does anyone know how to solve this?

Commit: bb58664
Diffs: csl-locales, csl-styles

bblhd · 2025-11-17T13:52:12Z

I have attempted to unmodify submodules without success, both in the past and currently, though I was unaware how much of a problem it was.

I've tried all suggested fixes unsuccessfully, either commit ids are not found or the commands have no effect at all. It seems to be something wrong with my version of git or my repository. For context, I'm using git version 2.51.2_1, on linux, with a basic command line and no IDE.

In theory, this could be fixed by creating a new branch and pull request, but the contributors guide specifically requests not to.

Does anyone know how to solve this?

Commit: bb58664 Diffs: csl-locales, csl-styles

Fixed this by doing submodule checkout in IntelliJ IDEA, unsure what exactly the issue was, but submodules are now unmodified from main.

bblhd · 2025-11-17T13:59:50Z

I apologise for force pushing, the only difference was a single incorrect author email in the previous commit I pushed.

InAnYan · 2025-11-17T15:57:34Z

Hi, bblhd! Thank you for looking into this feature. This is a very good issue for the first contribution!

jabgui/src/main/java/org/jabref/gui/importer/BookCoverFetcher.java

koppor

I understood:

The approach only supports isbn-based pictures (which is OK)
All files are named isbn-xyz
Covers are only downloaded for new entries
Covers are attached to an entry - and thus displayed as attached file in the main table
Existing covers are not re-used across different libraries (unless the configured directories match)

I think step 4 is a really big issue and hampering usability of JabRef. I cannot open an attached PDF any more with a single click.

For this PR, I propose a radical different approach:

Add method getCoverDirectory to org.jabref.logic.util.Directories
Store all covers there
Lookup covers there

No storing in BibEntry any more.

Just using ISBN and that directory for lookup

No re-download if cover already exists.

Reasons:

ISBN and DOIs are unique identifiers of papers. The links are implicit and do not need to be written down explicitly. (Because these are more technical things and a user seldomly interacts with the covers; in comparison to PDF files, which also could be stored using the DOI as name, but users tend to use more self-descriptive names).
Collecting all cover images in a single directory allows for seamless use across multiple bib files and I want to have the images displayed in all .bib files without the need to modify it. It should be "knob-less"
I as researcher have 100+ different bib files. I do not want to swamp colleague's libraries with images

Alternatives

One could introduce another field coverimage with a link. But then, we are back in the old days with pdf, ps fields, which we migrated away
One could add explicit handling in the main table to NOT show #cover links... This seems to be too much code there

Moreover, there should be a button next to the ISBN field to download the cover image if it does not exist. (This can be done in a follow-up, but we should be aware)

jablib/src/test/java/org/jabref/logic/util/io/FileUtilTest.java

jablib/src/test/java/org/jabref/logic/externalfiles/LinkedFileHandlerTest.java

koppor · 2025-11-20T09:56:38Z

jablib/src/test/java/org/jabref/logic/externalfiles/LinkedFileHandlerTest.java

-        if (link.isEmpty()) {
-            when(filePreferences.getFileNamePattern()).thenReturn("[bibtexkey]");
-        } else {
-            when(filePreferences.getFileNamePattern()).thenReturn("[bibtexkey] - [title]");


This is lost. I don't know the intention written here, but there is a test of an empty link - and then [title] is expected -- maybe, this is very strange and can really be removed, but we need to think :)

To my understanding, in the previous version, when the test was successful the pattern was only used if the link was empty, so "[bibtexkey] - [title]", the default filename pattern, was used otherwise.

koppor · 2025-11-20T10:02:34Z

jablib/src/main/java/org/jabref/logic/util/io/FileUtil.java

+        if ("default".equals(fileNamePattern.trim())) {
+            return Optional.empty();
+        }


I think, there is a misunderstanding of the existing code. If there is NO target name generated and NO citation key generated THEN Optional.empty is returned.

Please keep this behavior and do not change it without reason! There is NEVER passed default as fileNamePattern...

Revert the changes in this method.

There is a specific test that when "default" is passed as pattern, then it should return Optional.empty. I thought this might've an over-fitted test case, but I wasn't sure, should I remove it as well?

jablib/src/main/java/org/jabref/model/entry/LinkedFile.java

koppor · 2025-11-20T10:25:08Z

jabgui/src/main/java/org/jabref/gui/preview/PreviewViewer.java

-                """.formatted(text);
+                    <html>
+                        <body id="previewBody">
+                            %s <div id="content"> %s </div>


This is OK for a quick hack.

One should introduce a LayoutFormatter here. And then use \begin{file}\format[CoverImage}\end{file}.

The default preview style needs to be adapted accordingly.

Not sure whether we should make exceptions of the general preview handling for this because of images. @InAnYan

koppor · 2025-11-20T10:25:45Z

jabgui/src/main/java/org/jabref/gui/preview/PreviewViewer.java

+                // matches images that are either named according to the preferred file name format
+                // or images with case-insensitive "[cover]" in their description, to allow using any image regardless of name
+
+                if (file.getDescription().toLowerCase().contains("[cover]") || isFileTypeAValidCoverImage(file.getFileType()) && (FileUtil.getBaseName(file.getFileName()).equals(nameFromFormat))) {


Tags are normally starting with #. I would prefer #cover. WDYT @InAnYan ?

jabgui/src/main/java/org/jabref/gui/preview/PreviewViewer.java

bblhd · 2025-11-20T11:05:41Z

I understood:
1. The approach only supports isbn-based pictures (which is OK)

2. All files are named `isbn-xyz`

3. Covers are only downloaded for new entries

4. **Covers are attached to an entry - and thus displayed as attached file in the main table**

5. Existing covers are not re-used across different libraries (unless the configured directories match)
I think step 4 is a really big issue and hampering usability of JabRef. I cannot open an attached PDF any more with a single click.

For this PR, I propose a radical different approach:
1. Add method `getCoverDirectory` to org.jabref.logic.util.Directories

2. Store all covers there

3. Lookup covers there
No storing in BibEntry any more.

Just using ISBN and that directory for lookup

No re-download if cover already exists.

Thank you for the thorough review, it is very much appreciated.

Seperating book covers from attached files is a good idea, my current method was based off of previous attempts and what I understood of the codebase at the time, but its flaws became more obvious as I worked on it and understood more of the way that JabRef is actually used. I was considering this type of approach, so confirmation and details is helpful, I will be implementing seperate covers going forward.

…java Co-authored-by: Oliver Kopp <kopp.dev@gmail.com>

koppor · 2025-11-20T14:05:52Z

Seperating book covers from attached files is a good idea, my current method was based off of previous attempts and what I understood of the codebase at the time, but its flaws became more obvious as I worked on it and understood more of the way that JabRef is actually used. I was considering this type of approach, so confirmation and details is helpful, I will be implementing seperate covers going forward.

Nice! - Yeah, we are hitting the trade-off between 100% crisp requirements (causing much time) and implementing a solution and needed to change based on feedback. -- Its always easier to see something when it is "tangible" than when it is written somehow vaguely.

Thank you for the endurance!

If you want, you can write down an ADR (docs/decisions), because you know have material for both options.

…ier to debug

koppor · 2025-11-20T15:59:43Z

jabgui/src/main/java/org/jabref/gui/importer/BookCoverFetcher.java

        if (isbn.isPresent()) {
-            final String name = "isbn-" + isbn.asString();
+            final String name = "isbn-" + isbn.get().asString();
            if (findExistingImage(name, directory).isEmpty()) {
-                final String url = getSourceForIsbn(isbn);
+                final String url = getSourceForIsbn(isbn.get());
                Optional<LinkedFile> file = downloadCoverImage(url, name, directory);
            }


Please get used to .map for optionals. At the end, you can do forEach as you don't need the resulting downloaded file at this place.

…lt" clause

jabref-machine · 2025-11-20T17:41:39Z

JUnit tests of jablib are failing. You can see which checks are failing by locating the box "Some checks were not successful" on the pull request page. To see the test output, locate "Source Code Tests / Unit tests (pull_request)" and click on it.

You can then run these tests in IntelliJ to reproduce the failing tests locally. We offer a quick test running howto in the section Final build system checks in our setup guide.

bblhd added 14 commits October 17, 2025 03:43

Added initial work to get basic image covers working properly

d29ab3b

Merge branch 'JabRef:main' into feature/book-front-cover-10120

7b33850

Merge branch 'main' of https://github.com/JabRef/jabref into feature/…

05d21d4

…book-front-cover-10120

fixed order of cover images, refactored some of the cover code

2865553

rudimentary cover fetching

7842c6e

changed tabs to spaces

3f91954

merged with upstream

bb58664

fixed problems and changed cover tag parenthesis for display

112a095

fixed small issues, re-re-factoring

56475f3

incorrect name, now getCoverImageFileFromStringOfISBN

68e55c6

merged with upstream

a9e8120

fixed pattern naming somewhat, improved handling of edge cases and ad…

71fba83

…ded experimental "covers" subfolder

Added preferences for cover images

0d97ac5

merge from upstream

25b996c

github-actions bot added the first contrib label Nov 16, 2025

Siedlerchr reviewed Nov 16, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/importer/BookCoverFetcher.java Outdated Show resolved Hide resolved

Siedlerchr reviewed Nov 16, 2025

View reviewed changes

jablib/src/main/java/org/jabref/logic/util/URLUtil.java Show resolved Hide resolved

Merge branch 'main' into feature/book-front-cover-10120

f4946cd

Fix submodule changes

2c61ef3

bblhd force-pushed the feature/book-front-cover-10120 branch from 0b644fd to 2c61ef3 Compare November 17, 2025 13:55

style changes

dc614c4

bblhd added 4 commits November 18, 2025 04:31

fixes to getSuggestedFileName and added localization for new text

5e9b8af

Merge branch 'main' into feature/book-front-cover-10120

2d9abbc

fixed problem in getSuggestedFileName

b56b664

further fixes

45ff913

bblhd added 3 commits November 20, 2025 18:52

fixed import order

4124d98

Merge branch 'main' into feature/book-front-cover-10120

4f6607f

missing semicolon

99fe001

Siedlerchr reviewed Nov 20, 2025

View reviewed changes

jabgui/src/main/java/org/jabref/gui/importer/BookCoverFetcher.java Outdated Show resolved Hide resolved

bblhd added 2 commits November 20, 2025 19:29

fixed new variable and removed superfluous check

777ad41

missing argument somehow

9fc23be

koppor requested changes Nov 20, 2025

View reviewed changes

github-actions bot added the status: changes-required Pull requests that are not yet complete label Nov 20, 2025

Update jabgui/src/main/java/org/jabref/gui/importer/BookCoverFetcher.…

966fd67

…java Co-authored-by: Oliver Kopp <kopp.dev@gmail.com>

github-actions bot removed the status: changes-required Pull requests that are not yet complete label Nov 20, 2025

bblhd added 10 commits November 21, 2025 01:45

initial rework of covers, away from using attached files

c68ef91

Merge branch 'main' into feature/book-front-cover-10120

bc9f0b4

replaced findFileByNameWithAnyExtension with simpler code that is eas…

622838b

…ier to debug

removed LinkedFile#getURI/getURL due to lack of use

ca67eb3

improved test sources

3ebdc55

fixed test formating

f2d7a1a

fixed name of getValidFileName

7f17cd9

fixed missing .get() for Optional

477d845

fixed missing import

6824940

fixed things missed in book cover changes

b0be871

koppor reviewed Nov 20, 2025

View reviewed changes

bblhd added 5 commits November 21, 2025 04:05

better use of map

609371a

fixed syntax

5813bcc

corrected bad definition and removed createFileNameFromPattern "defau…

11b3570

…lt" clause

Merge branch 'main' into feature/book-front-cover-10120

fb1deab

minor BookCoverFetcher fixes

2cb5c99

koppor added the status: changes-required Pull requests that are not yet complete label Nov 21, 2025

Uh oh!

Add support for book front covers #14330

Are you sure you want to change the base?

Add support for book front covers #14330

Conversation

bblhd commented Nov 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Steps to test

Mandatory checks

Images

Uh oh!

github-actions bot commented Nov 16, 2025

Hey @bblhd!

Uh oh!

Uh oh!

Uh oh!

bblhd commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bblhd commented Nov 17, 2025

Uh oh!

bblhd commented Nov 17, 2025

Uh oh!

InAnYan commented Nov 17, 2025

Uh oh!

Uh oh!

koppor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

koppor Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

bblhd Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

bblhd Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

koppor Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bblhd commented Nov 20, 2025

Uh oh!

koppor commented Nov 20, 2025

Uh oh!

koppor Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

jabref-machine commented Nov 20, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bblhd commented Nov 16, 2025 •

edited

Loading

bblhd commented Nov 17, 2025 •

edited

Loading