Show compound patterns in the dropdown for citation key patterns #12580

priyanshu16095 · 2025-02-27T00:01:09Z

Follow-up for #12516

This PR enhances the citation key dropdown feature by adding a submenu for compound patterns.

Mandatory checks

I own the copyright of the code submitted and I licence it under the MIT license
[/ ] Change in CHANGELOG.md described in a way that is understandable for the average user (if change is visible to the user)
Tests created for changes (if applicable)
Manually tested changed features in running JabRef (always required)
Screenshots added in PR description (for UI changes)
Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
Checked 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 to the documentation repository.

Recording.2025-02-28.mp4

priyanshu16095 · 2025-02-27T00:24:20Z

src/main/java/org/jabref/gui/commonfxcontrols/CitationKeyPatternSuggestionCell.java

+        }
+
+        public List<String> generateCompoundPatterns(String enteredText) {
+            List<String> patterns = List.of("auth", "edtr", "year", "title", "date");


@subhramit I used this list as I don’t have much knowledge about the fields and can you explain more about compound patterns?

Please use the constants of org.jabref.model.entry.field.StandardField here.

The fields can be read about at BibLaTeX documentation at https://ctan.org/pkg/biblatex.

I think, the list should be manually crafted instead of just combinding all fields

The description at #12502 (comment) talks about auto completion

That would be nice.

If this is not possible, some pre-selected combinations should be doable.

I think, it needs to be a separate pop up then - even if multiple modals are not a good style ^^

Grammar: [{pattern}](_[{pattern}])*

A user can select a pattern.

Then, the user can select "+"

Then, JabRef adds "_" and offers another dropdown to select (the one selected before is NOT offered)

Reason: A user wants to use AuthEtAl together with year typically.

@priyanshu16095 Think of this as autogenerated (!) human-readable-primary-key in databases. MAybe this helps. -- Another thing: Either data of a BibEntry can be used directly or some processing of JabRef can be used. The former is ensured by CAPITAL LETTERS (first paragraph at https://docs.jabref.org/setup/citationkeypatterns#citation-key-patterns). The latter is described in the other text.

github-actions

JUnit tests are failing. In the area "Some checks were not successful", locate "Tests / Unit tests (pull_request)" and click on "Details". This brings you to the test output.
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.

priyanshu16095 · 2025-02-28T13:43:26Z

Recording.2025-02-28.mp4

@koppor Thanks for your insights! I’ve come up with a different solution that addresses the concerns and removes the overhead of an algorithm, maintaining it, and making it more efficient.
Instead, I used a UI-based solution (similar to your modal solution) that provides a much better approach, as the user doesn't have to type different keywords to find a pattern.
The UX is perfect, for a two-click process—it takes only two clicks.

priyanshu16095 · 2025-02-28T13:45:03Z

Another improvement in the code:
For better UX, the position of the sub-menu items under 'All patterns' and 'Create compound pattern' has been fixed, as it was not fixed before.

Before:

After:

github-actions

JUnit tests are failing. In the area "Some checks were not successful", locate "Tests / Unit tests (pull_request)" and click on "Details". This brings you to the test output.
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.

subhramit · 2025-03-03T13:01:46Z

Sorry, I am a little low on time to test this - What does the menu "Create compound pattern" do? Why is it needed if we can create compound patterns by taking patterns from the "All patterns" list? As far as I understand, only thing it does is add underscores in between patterns - the choice of that separator can be arbitrary for a user. @koppor do we wish to make underscore a default for this? Or is it a wider convention? This user, for example, was using colons (:) as a separator.

Also:

@priyanshu16095 Can you move the black arrows of the first menu (first two items having sublists) to the extreme right of the cell (like in the sublist menu)?

(Updated)

priyanshu16095 · 2025-03-03T15:16:09Z

Just like a dropdown that shows generated compound patterns, it allows the user to create any pattern on their own.
Regarding your concern about symbols, it could have a submenu displaying symbols that can be added or, by default - can be used.

priyanshu16095 · 2025-03-03T19:24:55Z

The width of the menu cannot be set in JavaFX, as it is managed by the system. However, I can change the width of the labels instead.

subhramit · 2025-03-04T13:56:39Z

Sorry, I am a little low on time to test this - What does the menu "Create compound pattern" do? Why is it needed if we can create compound patterns by taking patterns from the "All patterns" list? As far as I understand, only thing it does is add underscores in between patterns - the choice of that separator can be arbitrary for a user. @koppor do we wish to make underscore a default for this? Or is it a wider convention? This user, for example, was using colons (:) as a separator.

@koppor ping

koppor · 2025-03-07T17:20:59Z

Just like a dropdown that shows generated compound patterns, it allows the user to create any pattern on their own. Regarding your concern about symbols, it could have a submenu displaying symbols that can be added or, by default - can be used.

Good idea! _ can be the default.

ryan-carpenter · 2025-03-13T21:11:25Z

Just like a dropdown that shows generated compound patterns, it allows the user to create any pattern on their own. Regarding your concern about symbols, it could have a submenu displaying symbols that can be added or, by default - can be used.

The functionality is unclear because of the wording. The options need to be "parallel", like this:

Example 1

Choose pattern ⏵
Build pattern ⏵

Example 2

Basic pattern ⏵
Advanced pattern ⏵

Example 3

Simple pattern ⏵
Complex pattern ⏵

What about modifiers? These could be available after the first field or field marker has been selected, maybe like this.

Example 4

[title]
Add to pattern ⏵ ...
Add modifier ⏵ :abbr
               :lower
               :upper
               :titlecase

Another possibility for modifiers and even more detail would be to include an "expert" option linking to documentation or just add View documentation 🔗 to the list. I don't think JabRef already has a convention for context-sensitive help on menus, but I could be wrong.

priyanshu16095 · 2025-03-14T21:08:10Z

@ryan-carpenter I was unable to convey this properly. What I mean to say is that, without writing much additional code and by simply adding a few lines in the UI, it significantly improves the user experience. This is because there's no need to read any documentation or manually reopen the dropdown.
I will improve this based on the review.

priyanshu16095 · 2025-04-02T19:04:33Z

What is described in the comment is too complex to be implemented with context menu. If adding a submenu for other symbols and an expert linked to documentation is sufficient, or else I should use any other thing for UI.

priyanshu16095 · 2025-04-02T19:08:33Z

I am okay with doing what is described in the comment. Just want to know thoughts on this.

subhramit · 2025-04-02T19:14:22Z

I am okay with doing what is described in the comment. Just want to know thoughts on this.

Lets do a follow-up on that in a separate PR.
Is this otherwise ready? If it is, please resolve the merge conflicts and mark it ready for review.

priyanshu16095 · 2025-04-02T19:17:36Z

Done, resolved the conflicts, and it is ready.

priyanshu16095 · 2025-04-02T19:18:29Z

Does it also require a changelog.md entry?

jabref-machine · 2025-04-02T19:19:25Z

Note that your PR will not be reviewed/accepted until you have gone through the mandatory checks in the description and marked each of them them exactly in the format of [x] (done), [ ] (not done yet) or [/] (not applicable).

priyanshu16095 · 2025-04-02T19:21:22Z

Fixing the checks...

subhramit · 2025-04-02T19:25:36Z

Does it also require a changelog.md entry?

No, if the previous one mentions "dropdowns". Else, you can edit it.

CHANGELOG.md

trag-bot · 2025-04-03T11:06:33Z

src/main/java/org/jabref/gui/commonfxcontrols/CitationKeyPatternSuggestionCell.java

        private int heightOfMenuItem;
+        private final StringBuilder selectedPatterns = new StringBuilder();


StringBuilder is used for concatenating strings, which can be replaced with StringJoiner for better readability and maintainability.

trag-bot · 2025-04-03T11:06:36Z

src/main/java/org/jabref/gui/commonfxcontrols/CitationKeyPatternSuggestionCell.java

-                    CitationKeyPattern.Category.BIBENTRY_FIELDS, Localization.lang("Entry fields")
-            );
+            Map<CitationKeyPattern.Category, String> categoryNames = new LinkedHashMap<>();
+            categoryNames.put(CitationKeyPattern.Category.AUTHOR_RELATED, Localization.lang("Author related"));


The localization strings should be prefixed with % for proper localization handling in JabRef.

trag-bot · 2025-04-03T11:06:39Z

src/main/java/org/jabref/gui/commonfxcontrols/CitationKeyPatternSuggestionCell.java

@@ -131,7 +149,8 @@ private void populatePopup(List<String> searchResult) {
            }

            suggestionsList.getItems().clear();
-            suggestionsList.getItems().add(createPatternsSubMenu());
+            suggestionsList.getItems().add(ALL_PATTERNS_POSITION, createPatternsSubMenu());


The use of magic numbers like ALL_PATTERNS_POSITION should be avoided. Consider using a more descriptive constant or comment.

jabref-machine · 2025-04-03T11:10:02Z

You ticked that you modified CHANGELOG.md, but no new entry was found there.

If you made changes that are visible to the user, please add a brief description along with the issue number to the CHANGELOG.md file. If you did not, please replace the cross ([x]) by a slash ([/]) to indicate that no CHANGELOG.md entry is necessary. More details can be found in our Developer Documentation about the changelog.

priyanshu16095 · 2025-04-04T16:56:53Z

It's ready. Please take a look at the trag bot review and let me know what needs to be done in the follow-up.

trag-bot · 2025-04-04T17:07:48Z

src/main/java/org/jabref/gui/commonfxcontrols/CitationKeyPatternSuggestionCell.java

+                if (!newValue) {
+                    suggestionsList.hide();
+                }


The code should follow the fail-fast principle by immediately handling invalid states and returning early instead of nesting logic inside else branches.

priyanshu16095 · 2025-04-12T14:56:39Z

This is complete.

priyanshu16095 · 2025-04-18T21:41:34Z

@subhramit This is complete.

koppor

For any user-visible change, there should be a CHANGELOG.md entry.

Counter-Intuitive for me

context menu (right-click) does not show any suggestions:

When pressing a letter, the menu is shown.

Why empty?

--

The number of entries at compound-patterns is not limited, thus [author]_[title]_[year] is also valid

I think, more intuitive would be:

Show only "All patterns" during completion.
Show completion also after _
Show completion also at right click
Remove "Compound pattern"

Future work: context menu INSIDE a pattern shows the available modifiers.

koppor · 2025-04-19T12:35:01Z

src/main/java/org/jabref/gui/commonfxcontrols/CitationKeyPatternSuggestionCell.java

+                            positionCaret(selectedPatterns.length());
+                            suggestionsList.hide();
+                            selectionCount = 0;
+                            selectedPatterns.setLength(0);


Not understandable at first sight - comment needed.

koppor · 2025-04-19T12:35:46Z

src/main/java/org/jabref/gui/commonfxcontrols/CitationKeyPatternSuggestionCell.java

+                                suggestionsList.show(this, screenX, screenY);
+                            }
+                        } else if (selectionCount == 1) {
+                            selectedPatterns.append("_").append(pattern.stringRepresentation());


Not sure how this whole things works. Somewhere, it should be explained, how selectedPatterns is inteded to be sued.

koppor · 2025-04-19T12:45:24Z

@ryan-carpenter I was unable to convey this properly. What I mean to say is that, without writing much additional code and by simply adding a few lines in the UI, it significantly improves the user experience. This is because there's no need to read any documentation or manually reopen the dropdown.

I think, my review even improves usability more - and should not be much code, either.

What ryan also mentioned are the modifiers - which I also mentioned in my comment. On the one hand, this is really advanced JabRef usage - and could be done in a follow up. On the other hand, if you start implementing context menus, this could be "easily" doable maybe.

ryan-carpenter · 2025-05-24T02:24:03Z

@ryan-carpenter I was unable to convey this properly. What I mean to say is that, without writing much additional code and by simply adding a few lines in the UI, it significantly improves the user experience. This is because there's no need to read any documentation or manually reopen the dropdown.

I think, my review even improves usability more - and should not be much code, either.

What ryan also mentioned are the modifiers - which I also mentioned in my comment. On the one hand, this is really advanced JabRef usage - and could be done in a follow up. On the other hand, if you start implementing context menus, this could be "easily" doable maybe.

My main intent was to point out that the wording "All patterns" and "Create compound pattern" could be improved. The first is a noun phrase and the second is a verb phrase, which takes a little longer to process than if they are both the same. Example 1 is a suggestion that uses only verb-phrases while Examples 2 and 3 are alternatives that using only noun-phrases.

I also noticed that it might not be clear that "Create compound pattern" would need to be used repeatedly to create the pattern. If I recall correctly the phrase "Add to pattern" would not make sense because the user needs to first pick an initial pattern, then repeat the action to append to it.

Example 4 was an additional idea for potentially extending the proposal from priyanshu to become a "complete" pattern builder without requiring a dedicated window/form (because the proposal is already so close to providing this). I agree that if this is to be done, it can be a follow-up issue.

Edit: These ideas are also covered in a practical way by koppor's remarks in #12580 (review)

Show compound patterns

82b8e7d

priyanshu16095 commented Feb 27, 2025

View reviewed changes

priyanshu16095 added 2 commits February 27, 2025 10:53

Change the comment

7c0092c

Remove compound patterns menu item

7dc7da0

github-actions bot reviewed Feb 28, 2025

View reviewed changes

priyanshu16095 added 2 commits February 28, 2025 19:20

Implment feature

69d92d5

Merge branch 'main' into addCompoundPatterns

c0ff147

github-actions bot reviewed Mar 1, 2025

View reviewed changes

Fix the check

9ddcfa5

priyanshu16095 marked this pull request as ready for review March 3, 2025 10:24

Merge branch 'main' into addCompoundPatterns

4a90978

priyanshu16095 marked this pull request as draft March 20, 2025 01:52

Merge branch 'main' into addCompoundPatterns

8099176

Fix the check

437c9cd

Update CHANGELOG.md entry

c73970d

subhramit reviewed Apr 2, 2025

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

Revert CHANGELOG.md entry

0dffef6

trag-bot bot reviewed Apr 3, 2025

View reviewed changes

subhramit marked this pull request as ready for review April 4, 2025 17:05

trag-bot bot reviewed Apr 4, 2025

View reviewed changes

koppor requested changes Apr 19, 2025

View reviewed changes

		private int heightOfMenuItem;
		private final StringBuilder selectedPatterns = new StringBuilder();

Uh oh!

Show compound patterns in the dropdown for citation key patterns #12580

Are you sure you want to change the base?

Show compound patterns in the dropdown for citation key patterns #12580

Uh oh!

Conversation

priyanshu16095 commented Feb 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Follow-up for #12516

Mandatory checks

Uh oh!

priyanshu16095 Feb 27, 2025 • 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!

koppor Feb 27, 2025

Choose a reason for hiding this comment

Uh oh!

koppor Feb 27, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

priyanshu16095 commented Feb 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

priyanshu16095 commented Feb 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

subhramit commented Mar 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

priyanshu16095 commented Mar 3, 2025

Uh oh!

priyanshu16095 commented Mar 3, 2025

Uh oh!

subhramit commented Mar 4, 2025

Uh oh!

koppor commented Mar 7, 2025

Uh oh!

ryan-carpenter commented Mar 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

priyanshu16095 commented Mar 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

priyanshu16095 commented Apr 2, 2025

Uh oh!

priyanshu16095 commented Apr 2, 2025

Uh oh!

subhramit commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

priyanshu16095 commented Apr 2, 2025

Uh oh!

priyanshu16095 commented Apr 2, 2025 • edited by subhramit Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jabref-machine commented Apr 2, 2025

Uh oh!

priyanshu16095 commented Apr 2, 2025

Uh oh!

subhramit commented Apr 2, 2025

Uh oh!

Uh oh!

trag-bot bot Apr 3, 2025

Choose a reason for hiding this comment

Uh oh!

trag-bot bot Apr 3, 2025

Choose a reason for hiding this comment

Uh oh!

trag-bot bot Apr 3, 2025

Choose a reason for hiding this comment

Uh oh!

jabref-machine commented Apr 3, 2025

Uh oh!

priyanshu16095 commented Feb 27, 2025 •

edited

Loading

priyanshu16095 Feb 27, 2025 •

edited

Loading

priyanshu16095 commented Feb 28, 2025 •

edited

Loading

priyanshu16095 commented Feb 28, 2025 •

edited

Loading

subhramit commented Mar 3, 2025 •

edited

Loading

ryan-carpenter commented Mar 13, 2025 •

edited

Loading

priyanshu16095 commented Mar 14, 2025 •

edited

Loading

subhramit commented Apr 2, 2025 •

edited

Loading

priyanshu16095 commented Apr 2, 2025 •

edited by subhramit

Loading

ryan-carpenter commented May 24, 2025 •

edited

Loading