Refined the "Select files to import" page in "Search for unlinked local files" dialog by ZiadAbdElFatah · Pull Request #15110 · JabRef/jabref

ZiadAbdElFatah · 2026-02-14T14:57:47Z

Related issues and pull requests

PR Description

Refined the "Select files to import" page in "Search for unlinked local files" dialog to give the users the choice of linking the file to a related entry or import it to a new entry.

Steps to test

First open test-support/src/manual-tests/issue-13689/issue-13689.bib library

Select Lookup - Search for unlinked local files

This dialog will pop up

Click Next

Now the dialog provides jumping to related entries for each unlinked file. If the file can be linked to one entry or more, the entries will be in a dropdown, if the file isn't linked to any entry, it will have a blank beside it.
On clicking Next, if there is a selected entry for a file, this file will be linked to the selected entry otherwise, it will be imported into a new entry.

Checklist

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 added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
I described the change in CHANGELOG.md in a way that can be understood by the average user (if change is visible to the user)
I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

ZiadAbdElFatah · 2026-02-14T15:03:14Z

+
+        relatedEntries.setAll(relatedEntriesList);
+        return relatedEntries;
+    }


This is the part I was asking about in this comment #13689 (comment).
This is the function that gets the related entries that the files can be linked with. I compare them with the citation key, with the different patterns of the file name, I can't find a specific way to parse the citation key from the file name.
I read the documentation you provided here #13689 (comment), but I still don't have a solution @koppor.

I don't know what the existing code does. Need to read the existing code.

I am continuing investigating the existing code also.

The UnlinkedFilesCrawler and the UnlinkedPDFFileFilter are your friends

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

Lines 27 to 37 in fb5a3e7

/// Creates an instance by passing a {@link org.jabref.model.database.BibDatabase} which will be used for the searches.

public DatabaseFileLookup(@NonNull BibDatabaseContext databaseContext, FilePreferences filePreferences) {

possibleFilePaths = Optional.ofNullable(databaseContext.getFileDirectories(filePreferences))

.orElse(new ArrayList<>());

for (BibEntry entry : databaseContext.getDatabase().getEntries()) {

fileCache.addAll(parseFileField(entry));

}

this.pathOfDatabase = databaseContext.getDatabasePath().orElse(Path.of(""));

}

Roughly speaking, we create a list of all values of the file field in the library from all entries.
Then the crawlers use the Filter to check if the current found file a.pdf is already in the list of the entries, and so on

I think @koppor is confusing the logic here with "Automatically set File Links" which tries to automatically find matching files AutoLinkFilesAction.

This is kind of inverse action - and should be properly designed.

The UnlinkedFilesCrawler and the UnlinkedPDFFileFilter are your friends

Thanks a lot for the guidance.

I think @koppor is confusing the logic here with "Automatically set File Links" which tries to automatically find matching files AutoLinkFilesAction.

Yeah I am really confused, is the refined dialog about only letting the user know that there are entries that are related to the file and the file will always be in new entry if it is imported or the user can link the files related to some entries without creating a new entry for them.

ZiadAbdElFatah · 2026-02-16T10:30:37Z

+        List<BibEntry> relatedEntriesList = new ArrayList<>();
+        List<BibEntry> allEntries = bibDatabase.getDatabase().getEntries();
+
+        AutoSetFileLinksUtil util = new AutoSetFileLinksUtil(


I found this method here

jabref/jabgui/src/main/java/org/jabref/gui/fieldeditors/LinkedFilesEditorViewModel.java

Lines 193 to 221 in fb5a3e7

private List<LinkedFileViewModel> findAssociatedNotLinkedFiles(BibEntry entry) {

List<LinkedFileViewModel> result = new ArrayList<>();

AutoSetFileLinksUtil util = new AutoSetFileLinksUtil(

databaseContext,

preferences.getExternalApplicationsPreferences(),

preferences.getFilePreferences(),

preferences.getAutoLinkPreferences());

try {

Collection<LinkedFile> linkedFiles = util.findAssociatedNotLinkedFiles(entry);

for (LinkedFile linkedFile : linkedFiles) {

LinkedFileViewModel newLinkedFile = new LinkedFileViewModel(

linkedFile,

entry,

databaseContext,

taskExecutor,

dialogService,

preferences);

newLinkedFile.markAsAutomaticallyFound();

result.add(newLinkedFile);

}

} catch (IOException e) {

dialogService.showErrorDialogAndWait("Error accessing the file system", e);

}

LOGGER.trace("Found {} associated files for entry {}", result.size(), entry.getCitationKey());

return result;

}

But I had to change the CliPreferences to GuiPreferences to be able to call getExternalApplicationsPreferences(). Is this ok?
This method gets the files that are found but not linked to each entry, so I think it's the best method for searching the related entries for each file.

this comment should have gone to line 79?

Since we are in the GUI, this change is OK.

ZiadAbdElFatah · 2026-02-16T11:01:22Z

Now, this PR, when the Find unlinked files is invoked by the user, it lets them know if there are existing entries that the files can be linked to already, instead of creating a new entry, but it doesn't handle file linking directly.
So, should we add the linking, or is the current implementation enough @koppor @Siedlerchr?
Here is how the dialog looks right now:

Single related entry:

2. Multiple related entries:

3. No related entries:

koppor

While reading #13689 (comment), I think, this PR goes in the right direction.

I wonder why so much is happing in the GUI. But this is PR #14710 - and neesd to be fixed seperately.

koppor · 2026-02-16T19:52:44Z

+                preferences.getFilePreferences(),
+                preferences.getAutoLinkPreferences());
+
+        for (BibEntry entry : allEntries) {


The algorithm should be explained.

koppor · 2026-02-16T19:54:40Z

+        List<BibEntry> relatedEntriesList = new ArrayList<>();
+        List<BibEntry> allEntries = bibDatabase.getDatabase().getEntries();
+
+        AutoSetFileLinksUtil util = new AutoSetFileLinksUtil(


this comment should have gone to line 79?

Since we are in the GUI, this change is OK.

koppor · 2026-02-16T20:00:53Z

+                if (empty || item == null) {
+                    setText(null);
+                    setGraphic(null);
+                } else {


When can entry or item be null? Is this a wrong call?

If you cannot avoid, please add a JavaDoc comment and also @Nulalble

Furthermore, return early. meaing: if, then return

and then no else branch.

When can entry or item be null? Is this a wrong call?

I found this doc for the updateItem method

So I think it's safer to check if empty or item is null.

koppor · 2026-02-16T20:01:07Z

+                } else {
+                    leftSide.getChildren().clear();
+                    CheckBox checkBox = (CheckBox) getGraphic();
+                    if (checkBox != null) {


When can checkbox be null?

I checked the normal scenarios where the checkbox can be null, and I think no one of them will happen in our case, so I think this check is dummy here.

koppor · 2026-02-16T20:01:22Z

+                    cellContent.getChildren().clear();
+                    cellContent.getChildren().add(leftSide);
+
+                    if (item.getPath().toFile().isFile()) {


can it be no -file? when?

exit early again.

can it be no -file? when?

exit early again.

We want to show blank space if it's a directory, not a file.

koppor · 2026-02-16T20:01:38Z

+                        }
+                    }
+                    setGraphic(cellContent);
+                    setText(null);


Why no next? Java comment

koppor · 2026-02-16T20:02:23Z

+                jumpToEntryButton.getStyleClass().add("icon-button");
+                jumpToEntryButton.setTooltip(new Tooltip(Localization.lang("Jump to entry")));
+                jumpToEntryButton.setOnAction(_ -> {
+                    BibEntry selectedEntry = relatedEntries.getValue();


When can it happen that there is no value? --> add java ocmment

koppor · 2026-02-16T20:07:06Z

-        new ViewModelTreeCellFactory<FileNodeViewModel>()
-                .withText(FileNodeViewModel::getDisplayTextWithEditDate)
-                .install(unlinkedFilesList);
+        unlinkedFilesList.setCellFactory(_ -> new CheckBoxTreeCell<>() {


Write a separate class - this is way too long for an anoymous class.

github-actions · 2026-02-17T03:53:14Z

Your pull request conflicts with the target branch.

Please merge with your code. For a step-by-step guide to resolve merge conflicts, see https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line.

ZiadAbdElFatah · 2026-02-17T05:20:43Z

I wonder why so much is happing in the GUI.

It's just because it's my first time working with GUI using JavaFX in this way.

Siedlerchr · 2026-02-28T15:57:25Z

pass StateManager via constructor parameter

Siedlerchr · 2026-02-28T15:57:47Z


        unlinkedFilesList = new CheckTreeView<>();
-        new ViewModelTreeCellFactory<FileNodeViewModel>().withText(FileNodeViewModel::getDisplayTextWithEditDate).install(unlinkedFilesList);
+        unlinkedFilesList.setCellFactory(_ -> new UnlinkedFilesCellFactory(this.viewModel.getStateManager(), viewModel));


Pas stateManager from constructor down

Siedlerchr

some UX improvements

…files dialog

testlens-app · 2026-02-28T23:05:53Z

✅ All tests passed ✅

🏷️ Commit: 76a24ba
▶️ Tests: 11252 executed
⚪️ Checks: 66/66 completed

Learn more about TestLens at testlens.app.

Siedlerchr

Looks good to me now!

addressed

…al files" dialog (JabRef#15110) * Refined the Find unlinked files dialog * Added search for entries by pdf names * Added search icon for the selected entry * Fix submodules * Refactored the searching process * Fix submodules * Enhanced some code * Added manual test * Fix submodules * Added CHANGELOG entry * Fix submodules * Fix submodules * Fix submodules * Fix submodules * Changed "new" to localized one * Fixed some typos * Moved the CHANGELOG entry under Unreleased * Changed the tree cell of the FileSelectionPage * Passed StateManager via constructor parameter * Added the dropdown for one entry * Added do not link to deselect the entry in the dropdown * Added linking the file to the selected entry from the dropdown * Refined the Select files to import page in Search for unlinked local files dialog * Removed unused expressions

…rg.openrewrite.recipe-rewrite-recipe-bom-3.25.0 * upstream/main: (35 commits) Chore: add dependency-management.md (#15278) Chore(deps): Bump dev.langchain4j:langchain4j-bom in /versions (#15277) New Crowdin updates (#15274) Chore(deps): Bump actions/upload-artifact from 6 to 7 (#15271) Chore(deps): Bump actions/download-artifact from 7 to 8 (#15270) Chore(deps): Bump docker/login-action from 3 to 4 (#15268) Fix threading issues in citations relations tab (#15233) Fix: Citavi XML importer now preserves citation keys (#14658) (#15257) Preserve no break spaces in Latex to Unicode conversion (#15174) Fix: open javafx.scene.control.skin to controlsfx (#15260) Reduce complexity in dependencies setup (restore) (#15194) New translations jabref_en.properties (French) (#15256) Fix: exception dialog shows up when moving sidepanel down/up (#15248) Implement reset for Name Display Preferences (#15136) Chore(deps): Bump net.bytebuddy:byte-buddy in /versions (#15252) Chore(deps): Bump io.zonky.test.postgres:embedded-postgres-binaries-bom (#15253) Chore(deps): Bump io.zonky.test:embedded-postgres in /versions (#15254) Chore(deps): Bump net.ltgt.errorprone from 5.0.0 to 5.1.0 in /jablib (#15251) New Crowdin updates (#15247) Refined the "Select files to import" page in "Search for unlinked local files" dialog (#15110) ...

ZiadAbdElFatah added 2 commits February 14, 2026 16:46

Refined the Find unlinked files dialog

44544d0

Fix submodules

b546a41

github-actions Bot added the good second issue Issues that involve a tour of two or three interweaved components in JabRef label Feb 14, 2026

ZiadAbdElFatah commented Feb 14, 2026

View reviewed changes

github-actions Bot added the status: changes-required Pull requests that are not yet complete label Feb 14, 2026

This comment has been minimized.

Sign in to view

github-actions Bot mentioned this pull request Feb 14, 2026

Refine "Find unlinked files" dialog #13689

Closed

Siedlerchr added the status: devcall label Feb 15, 2026

ZiadAbdElFatah added 6 commits February 16, 2026 07:55

Merge branch 'JabRef:main' into fix-for-issue-13689

7d1afec

Added search for entries by pdf names

7684974

Added search icon for the selected entry

b5c32cd

Fix submodules

7b29335

Refactored the searching process

05705eb

Fix submodules

3f68654

ZiadAbdElFatah commented Feb 16, 2026

View reviewed changes

ZiadAbdElFatah requested review from Siedlerchr and koppor February 16, 2026 11:02

koppor removed request for Siedlerchr and koppor February 16, 2026 11:02

koppor previously requested changes Feb 16, 2026

View reviewed changes

koppor reviewed Feb 16, 2026

View reviewed changes

koppor removed the status: devcall label Feb 16, 2026

ZiadAbdElFatah added 4 commits February 17, 2026 08:31

Enhanced some code

df2acb4

Fix submodules

d7fc09b

Added manual test

e91aa28

Fix submodules

2d4b35d

github-actions Bot added the good third issue label Feb 17, 2026

Changed the tree cell of the FileSelectionPage

33bc214

This comment has been minimized.

Sign in to view

ZiadAbdElFatah requested a review from Siedlerchr February 28, 2026 14:23

Siedlerchr reviewed Feb 28, 2026

View reviewed changes

Siedlerchr requested changes Feb 28, 2026

View reviewed changes

github-actions Bot added status: changes-required Pull requests that are not yet complete and removed status: no-bot-comments labels Feb 28, 2026

ZiadAbdElFatah added 5 commits February 28, 2026 23:02

Passed StateManager via constructor parameter

a882b5f

Added the dropdown for one entry

3a4cf8f

Added do not link to deselect the entry in the dropdown

1b295cd

Added linking the file to the selected entry from the dropdown

492baa8

Refined the Select files to import page in Search for unlinked local …

293af03

…files dialog

This comment has been minimized.

Sign in to view

ZiadAbdElFatah changed the title ~~Refined the "Search for unlinked local files" dialog~~ Refined the "Select files to import" page in "Search for unlinked local files" dialog Feb 28, 2026

Removed unused expressions

76a24ba

github-actions Bot added status: no-bot-comments and removed status: changes-required Pull requests that are not yet complete labels Feb 28, 2026

ZiadAbdElFatah requested a review from Siedlerchr February 28, 2026 23:26

Siedlerchr approved these changes Mar 1, 2026

View reviewed changes

Siedlerchr added this pull request to the merge queue Mar 1, 2026

github-actions Bot added the status: to-be-merged PRs which are accepted and should go into the merge-queue. label Mar 1, 2026

Merged via the queue into JabRef:main with commit 28759fe Mar 1, 2026
65 of 66 checks passed

ZiadAbdElFatah deleted the fix-for-issue-13689 branch March 1, 2026 22:36

ZiadAbdElFatah mentioned this pull request May 10, 2026

Refactored the comments for UnlinkedFilesCrawler #15709

Merged

2 tasks


	/// Creates an instance by passing a {@link org.jabref.model.database.BibDatabase} which will be used for the searches.
	public DatabaseFileLookup(@NonNull BibDatabaseContext databaseContext, FilePreferences filePreferences) {
	possibleFilePaths = Optional.ofNullable(databaseContext.getFileDirectories(filePreferences))
	.orElse(new ArrayList<>());

	for (BibEntry entry : databaseContext.getDatabase().getEntries()) {
	fileCache.addAll(parseFileField(entry));
	}
	this.pathOfDatabase = databaseContext.getDatabasePath().orElse(Path.of(""));
	}

	private List<LinkedFileViewModel> findAssociatedNotLinkedFiles(BibEntry entry) {
	List<LinkedFileViewModel> result = new ArrayList<>();

	AutoSetFileLinksUtil util = new AutoSetFileLinksUtil(
	databaseContext,
	preferences.getExternalApplicationsPreferences(),
	preferences.getFilePreferences(),
	preferences.getAutoLinkPreferences());
	try {
	Collection<LinkedFile> linkedFiles = util.findAssociatedNotLinkedFiles(entry);
	for (LinkedFile linkedFile : linkedFiles) {
	LinkedFileViewModel newLinkedFile = new LinkedFileViewModel(
	linkedFile,
	entry,
	databaseContext,
	taskExecutor,
	dialogService,
	preferences);
	newLinkedFile.markAsAutomaticallyFound();
	result.add(newLinkedFile);
	}
	} catch (IOException e) {
	dialogService.showErrorDialogAndWait("Error accessing the file system", e);
	}

	LOGGER.trace("Found {} associated files for entry {}", result.size(), entry.getCitationKey());
	return result;
	}

Uh oh!

Conversation

ZiadAbdElFatah commented Feb 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related issues and pull requests

PR Description

Steps to test

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

ZiadAbdElFatah Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZiadAbdElFatah commented Feb 16, 2026

Uh oh!

koppor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Feb 17, 2026

Uh oh!

ZiadAbdElFatah commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Siedlerchr left a comment

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

testlens-app Bot commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ All tests passed ✅

Uh oh!

Siedlerchr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

ZiadAbdElFatah commented Feb 14, 2026 •

edited

Loading

ZiadAbdElFatah Feb 16, 2026 •

edited

Loading

ZiadAbdElFatah commented Feb 17, 2026 •

edited

Loading

testlens-app Bot commented Feb 28, 2026 •

edited

Loading