Add toggle functionality for journal abbreviation lists #12912

zikunz · 2025-04-08T14:58:23Z

Toggle Functionality for Journal Abbreviation Lists

Documentation repo's issue is JabRef/user-documentation#560

What

This feature is comprehensive and solves more than what is asked in #12468.

Specifially, this PR adds the ability to enable/disable any journal abbreviation lists in JabRef, including both the built-in list and external CSV files. Users can now toggle all types of journal abbreviation lists on/off to make them enabled/disabled.

We can disable and re-enable the built-in list:

If the built-in list is disabled, journal names found in the built-in list will not be abbreviated or unabbreviated:

In addition, external CSV files can be disabled or enabled. Likewise, if an external CSV file is disabled, journal names found in the external CSV file will not be abbreviated or unabbreviated too.

Why

In the original codebase, all journal abbreviation lists were always active once loaded. Users had no way to temporarily disable specific abbreviation sources without completely removing them. This was particularly problematic with the built-in list, which could not be removed at all. Detailed reasons about why we want to disable built-in list sometimes can be found in #12468.

This feature improves workflow flexibility by allowing users to:

Temporarily enable/disable specific sources during editing sessions
Control which lists are active without removing them

How

The implementation follows JabRef's existing architecture patterns

Key Features

Filtering Logic

Only enabled abbreviation sources will apply changes during operations
Disabled abbreviation sources have no effect on journal name processing
The repository dynamically filters abbreviations based on source enabled state

Persistence

Toggle states are stored in preferences only upon clicking "Save"
If the user clicks "Cancel" or closes the dialog (X), previous states are restored
States persist between application restarts

UI Feedback

Visual indicators show enabled/disabled state for each list
Toggle button provides easy access to state change
Dropdown shows current state with clear visual indicators

Design Considerations

Performance Considerations

The implementation reloads the journal repository before each abbreviation operation to ensure it uses the latest toggle states. This approach has minimal performance impact because:

Repository loading is very efficient as it only builds active abbreviation sets
Abbreviation operations are typically infrequent user actions
The benefits of having accurate, up-to-date toggle states outweigh the small overhead of reloading

I have also tested with fairly large abbreviation lists and observed no noticeable performance degradation.

Design Alternatives Considered

Event-based updates: I considered using an event system to update the repository when toggle states change. While potentially more efficient, this approach would be more complex and error-prone, requiring careful synchronization between preference changes and repository state.
Runtime filtering: Another approach was to keep all abbreviations loaded and filter at runtime during abbreviation operations. This would be slightly faster but would require more memory and complicate the core lookup methods.
Separate repositories: I also considered maintaining separate repositories for each source, but this would diverge significantly from JabRef's existing architecture and complicate cross-source operations.

The chosen approach of reloading the repository provides the best balance of reliability, maintainability, and adherence to existing architecture patterns.

Proposed Code Changes

Frontend Changes (GUI)

JournalAbbreviationsTab.java
- Purpose: User interface tab for managing journal abbreviations
- Changes:
  - Added toggle button next to journal list dropdown
  - Created custom ListCell displaying checkmarks (✓) or circles (○) to indicate enabled state
  - Implemented real-time UI refresh when toggling lists
- Why: Provides the visual interface for users to see and change enabled states
AbbreviationsFileViewModel.java
- Purpose: View model for a single abbreviation file
- Changes:
  - Added enabledProperty to track and bind state
  - Implemented getter/setter methods for state access
  - Added path handling for consistent preference storage
- Why: Provides the model binding for UI components to reflect enabled state changes
JournalAbbreviationsTabViewModel.java
- Purpose: Manages the journal abbreviation tab's business logic
- Changes:
  - Implemented state tracking with proper model update notification
  - Added event handling for toggle button click
  - Added methods to build file list with correct initial states
  - Connected UI state to persistence layer
- Why: Connects the UI actions to the model and ensures proper state synchronization
MainMenu.java
- Purpose: Builds the application's main menu
- Changes:
  - Updated constructor calls to accommodate new repository loading mechanism
- Why: Required to accommodate the new repository loading approach in AbbreviateAction

Backend Changes (Logic)

JournalAbbreviationRepository.java
- Purpose: Central repository that stores and retrieves abbreviations
- Changes:
  - Added source tracking with sourceToAbbreviations map to associate abbreviations with their sources
  - Added enabledSources map to track enabled/disabled state of each source
  - Modified core lookup methods to filter based on enabled state
  - Implemented proper updating of active abbreviations when toggling
- Why: This is the core component where abbreviation filtering happens. When a source is disabled, its abbreviations shouldn't be used in operations
JournalAbbreviationLoader.java
- Purpose: Loads abbreviations from various sources into the repository
- Changes:
  - Modified to respect enabled states from preferences
  - Implemented consistent key naming for external list identification
  - Added robust error handling for missing files
- Why: The loader needed to initialize the repository with the correct enabled states and ensure proper source identification
AbbreviateAction.java
- Purpose: Handles abbreviation/unabbreviation commands from menu
- Changes:
  - Implemented repository reload before abbreviation operations
  - Ensured operations use the latest toggle states
- Why: Without reloading the repository, toggle state changes wouldn't affect already-running abbreviation operations
JournalAbbreviationPreferences.java
- Purpose: Stores user preferences for journal abbreviations
- Changes:
  - Added enabledExternalLists map to store enabled/disabled states
  - Added methods to check if a specific source has an explicit enabled setting
  - Enhanced preference retrieval with multiple lookup strategies
- Why: Provides the persistence mechanism for toggle states between application sessions
JabRefCliPreferences.java
- Purpose: Handles preference loading/saving at application level
- Changes:
  - Added settings for journal abbreviation toggle states
  - Integrated with the overall preference system
- Why: Ensures toggle states are properly saved/loaded at application level

Testing Strategy

Test Files and Coverage

JournalAbbreviationRepositoryTest.java
- Purpose: Tests the core backend functionality for source tracking and toggle behavior
- Test Cases:
  - multipleSourcesCanBeToggled: Verifies that multiple sources can be independently enabled/disabled
  - disabledSourcesAreFilteredFromLookup: Ensures abbreviations from disabled sources aren't returned in lookups
  - builtInListCanBeToggled: Confirms the built-in list can be toggled like external sources
  - toggleStateAffectsAbbreviationSets: Tests that abbreviation sets are properly filtered by source state
JournalAbbreviationsViewModelTabTest.java
- Purpose: Tests the UI view model for toggle functionality
- Test Cases:
  - addBuiltInListInitializesWithCorrectEnabledState: Verifies built-in list loaded with correct enabled state
  - enabledExternalListFiltersAbbreviationsWhenDisabled: Tests that UI reflects filtered abbreviations
  - storeSettingsPersistsEnabledStateToPreferences: Ensures toggle states are saved to preferences

Implementation Additions for Testing

The following methods and properties were added specifically to support testing:

AbbreviationsFileViewModel.java
- Added refreshAbbreviations() method to simulate UI updates when toggle state changes
- Added thorough isEnabled(), setEnabled(), and enabledProperty() methods for test validation
JournalAbbreviationsTabViewModel.java
- Added markAsDirty() method to allow tests to mark files as needing to be saved
- Enhanced storeSettings() to provide verification points for proper state persistence
JournalAbbreviationRepository.java
- Implemented addCustomAbbreviation(abbreviation, sourcePath, enabled) with source tracking for test scenarios
- Added test-friendly mapping between abbreviations and their sources for verification
JournalAbbreviationPreferences.java
- Added hasExplicitEnabledSetting() method to improve testability of preference storage
- Implemented clean getters/setters for toggle states to simplify test verification

These additions ensure the toggle functionality can be thoroughly tested while maintaining clean separation between the application code and test code.

Mandatory checks

I own the copyright of the code submitted and I license 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 (if change is visible to the user)
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.

This feature allows users to enable/disable specific journal abbreviation lists, including both the built-in list and external CSV files, without removing them from configuration. - Added toggle controls in UI with visual indicators for enabled/disabled states - Implemented filtering of abbreviations based on source enabled state - Ensured toggle states persist between application sessions - Optimized performance with efficient repository loading - Added comprehensive test coverage for new functionality Closes JabRef#12468

subhramit · 2025-04-08T16:38:48Z

Please update your screenshots here as well.

zikunz · 2025-04-08T18:25:36Z

@subhramit Got it, I will make sure all the screenshots will be updated in the PR content above :)

zikunz · 2025-04-08T18:26:49Z

I tried to fix the two screenshots in the PR content, may I ask whether you are able to see them? @subhramit

subhramit · 2025-04-08T19:09:34Z

I tried to fix the two screenshots in the PR content, may I ask whether you are able to see them? @subhramit

yes, they are fine now

zikunz · 2025-04-08T19:30:12Z

Thank you! @subhramit

Journal abbreviations coming from sources that the user has disabled should neither be generated nor reversed.\n\nThis patch:\n 1. Makes UndoableUnabbreviator skip entries whose source is disabled\n2. Introduces AbbreviationWithSource to persist source metadata\n3. Filters candidates early in AbbreviateAction\n4. Refreshes repository state when a source is toggled in the UI

zikunz · 2025-04-13T09:49:44Z

Update: the bug is now fixed and I proceed to refactor the code now. Afterwards, this PR will be ready for review :)

This commit fixes test failures that occurred after implementing the journal abbreviation toggle feature. The changes include: 1. Ensuring the built-in list is always enabled by default in the JournalAbbreviationLoader for backward compatibility 2. Updating journal abbreviation tests to use controlled test data rather than depending on the built-in repository contents 3. Adding a more comprehensive test case for the abbreviation cycle

jabref-machine · 2025-04-13T12:11:39Z

Your pull request conflicts with the target branch.

Please merge upstream/main 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.

jabref-machine · 2025-04-13T12:11:49Z

Your pull request conflicts with the target branch.

Please merge upstream/main 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.

src/test/java/org/jabref/gui/journals/AbbreviateActionTest.java

Integrate journal abbreviation toggle functionality (JabRef#12880) with the LTWA repository support from main branch. Resolve conflicts in JournalAbbreviationRepository, JournalAbbreviationLoader, and MainMenu to ensure both features work correctly together. The combined functionality allows users to enable/disable specific journal abbreviation sources while maintaining LTWA abbreviation support.

zikunz · 2025-04-18T19:06:17Z

@koppor @Siedlerchr @subhramit

I have completed resolving the 6 merge conflicts between my PR and PR #12880 (which closed #12273). The resolved changes are reflected in my recent commit with the commit message of "feat: resolve merge conflicts with journal abbreviation toggle feature".

To properly test the combined functionality, I first proceeded to git checkout 1a4e1f38864e9bb1fc336a366ec24c3c0d48a94f in main branch to understand the behavior after merging #12880 to main (without my code changes).

During my local testing of the merged functionality, I observed some behavior that I would like to confirm is working as intended:

When testing with the LTWA abbreviation mode, I noticed that the word "graph" does not get abbreviated to "gr." despite the csv file found in Add support for LTWA #12273 containing the entry -graph-;"-gr.";"eng".

I can successfully abbreviate "Journal of Polymer Science Part A" to "J. Polym. Sci. A" using LTWA mode (matching a test case in Add support for LTWA #12273), but when I try to unabbreviate it, it does not revert to the original text. In addition, "Journal of Polymer Science Part A" does not seem to be found in the the csv file found in Add support for LTWA #12273.

When attempting to abbreviate "Dem" (this is achieved by first abbreviating "Demonstration" using the shortest unique mode) using LTWA mode, the result is an empty string.

I want to ensure that my merge conflict resolution is correct and that I am understanding the expected behavior of the LTWA abbreviation functionality properly. Could you please advise if these observations align with the intended functionality of the LTWA implementation, or if further adjustments are needed?

Thank you for your guidance.

…reviation-toggle

koppor · 2025-04-19T12:47:09Z

@Yubo-Cao Can you look into #12912 (comment) maybe? I currently don't have the resources to properly answer.

zikunz · 2025-04-19T18:26:43Z

@Yubo-Cao Can you look into #12912 (comment) maybe? I currently don't have the resources to properly answer.

@koppor Thank you!

@Yubo-Cao I look forward to your guidance. Thank you in advance!

trag-bot · 2025-04-19T19:11:58Z

src/test/java/org/jabref/logic/journals/UndoableUnabbreviatorTest.java

+    @Test
+    void checkBasicAbbreviate() {
+        BibEntry entry = new BibEntry();
+        entry.setField(StandardField.JOURNAL, "TJ");


When creating a new BibEntry object, 'withers' should be used instead of 'setField'. This improves code readability and follows modern Java practices.

src/main/java/org/jabref/gui/preferences/journals/AbbreviationsFileViewModel.java

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTabViewModel.java

zikunz · 2025-04-23T20:24:39Z

The changes so far are looking good. How much more work do you estimate it'll take to get to a "ready" state?
See if you can get rid of Collectors and Collections wherever possible. I have left some hints in comments below and some miscellaneous code suggestions.

@subhramit Thank you so much for your thorough code review and feedback. I estimate I will need approximately 1 - 2 additional days to bring this PR to a "ready" state. Here is what remains on my task list (please let me know if I still miss any):

Code Refactoring (most significant effort)

Address all remaining review comments by trag-bot

Implement your suggestions regarding Collectors and Collections alternatives

Conduct a final quality review to identify additional improvements

PR Documentation Updates

Enhance the description with clear explanations of:

Modified files and rationale for changes

Implementation approach

Key design decisions and alternatives considered

...

Documentation Repo Updates

Open a corresponding issue in the documentation repo

Submit a PR with necessary documentation changes

I am really thankful for your guidance on reducing dependencies on Collectors and Collections - I will incorporate your suggestions in my upcoming changes. The hints you have provided in the comments are especially helpful.

I just updated the PR content and opened an issue in the documentation repo. I addressed all trag-bot comments and now working on resolving all comments from @subhramit's code review. The refactoring might take some time.

Co-authored-by: Subhramit Basu <[email protected]>

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTab.java

src/main/java/org/jabref/gui/journals/AbbreviateAction.java

src/main/java/org/jabref/gui/preferences/journals/AbbreviationsFileViewModel.java

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTab.java

src/test/java/org/jabref/gui/journals/AbbreviateActionTest.java

src/test/java/org/jabref/gui/preferences/journals/JournalAbbreviationsViewModelTabTest.java

src/test/java/org/jabref/logic/journals/JournalAbbreviationRepositoryTest.java

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTab.java

zikunz · 2025-04-23T21:24:22Z

All checks have passed and no more trag-bot comments for the time being, I will proceed to address the remaining comments @subhramit raised during code review. Please feel free to add more comments for the code changes.

JabRef/jabref#12912 src/test/java/org/jabref/logic/journals/JournalAbbreviationRepositoryTest.java Extract Variable result : Optional<Abbreviation> in method package abbreviationsWithEscapedAmpersand() : void from class org.jabref.logic.journals.JournalAbbreviationRepositoryTest Extract Attribute private AMERICAN_JOURNAL : Abbreviation in class org.jabref.logic.journals.JournalAbbreviationRepositoryTest

trag-bot · 2025-04-25T15:08:50Z

@trag-bot didn't find any issues in the code! ✅✨

subhramit · 2025-04-26T04:17:59Z

@zikunz note that not all tragbot comments are relevant.
E.g. if you are dealing with pure bollean functions, assertTrue and assertFalse is alright to use.

subhramit · 2025-04-26T04:20:45Z

Could you also answer #12912 (comment)

subhramit · 2025-04-26T04:22:01Z

src/main/java/org/jabref/gui/journals/UndoableUnabbreviator.java

        if (!journalAbbreviationRepository.isAbbreviatedName(text)) {
-            return false; // Cannot unabbreviate unabbreviated name.


Revert the comment removal

zikunz force-pushed the feature/journal-abbreviation-toggle branch from dd85326 to 37c8d2c Compare April 8, 2025 15:02

zikunz mentioned this pull request Apr 8, 2025

Ability to disable the built-in JabRef journal abbreviation list #12468

Open

subhramit marked this pull request as draft April 8, 2025 15:21

zikunz added 8 commits April 13, 2025 18:17

test: add coverage for unabbreviation operations

ed985ec

refactor: address issues raised by the bot for existing testing code

5828a7e

fix: resolve issues raised by the bot regarding testing code

623ab21

fix: resolve more issues raised by the bot regarding testing code

0589d14

fix: resolve remaining issues raised by the bot regarding testing code

62ccc81

fix: resolve additional issues raised by the bot regarding testing code

b6a92b8

fix: try to resolve all issues raised by the bot regarding testing code

774f5fb

trag-bot bot reviewed Apr 13, 2025

View reviewed changes

src/test/java/org/jabref/gui/journals/AbbreviateActionTest.java Show resolved Hide resolved

zikunz added 3 commits April 19, 2025 03:09

fix: resolve merge conflicts in CHANGELOG.md

00b8d24

doc: update issue number for this PR

e3b62b7

Merge remote-tracking branch 'upstream/main' into feature/journal-abb…

d3f7ff4

…reviation-toggle

trag-bot bot reviewed Apr 19, 2025

View reviewed changes

fix: address the final Checkstyle issue

9dafa2a

zikunz force-pushed the feature/journal-abbreviation-toggle branch from 720209d to 9dafa2a Compare April 23, 2025 19:31

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/preferences/journals/AbbreviationsFileViewModel.java Show resolved Hide resolved

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTabViewModel.java Show resolved Hide resolved

zikunz mentioned this pull request Apr 23, 2025

Documentation needed: Toggle functionality for journal abbreviation lists JabRef/user-documentation#560

Open

zikunz force-pushed the feature/journal-abbreviation-toggle branch from b3eb812 to 9dafa2a Compare April 23, 2025 20:21

zikunz and others added 2 commits April 24, 2025 04:26

fix: apply suggestions from code review

9b4a43f

Co-authored-by: Subhramit Basu <[email protected]>

doc: add JavaDoc suggested by trag-bot

d555a09

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTab.java Show resolved Hide resolved

zikunz changed the title ~~[WIP] Add toggle functionality for journal abbreviation lists~~ Add toggle functionality for journal abbreviation lists Apr 23, 2025

zikunz marked this pull request as ready for review April 23, 2025 20:43

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/journals/AbbreviateAction.java Show resolved Hide resolved

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/preferences/journals/AbbreviationsFileViewModel.java Show resolved Hide resolved

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTab.java Show resolved Hide resolved

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/test/java/org/jabref/gui/journals/AbbreviateActionTest.java Show resolved Hide resolved

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/test/java/org/jabref/gui/preferences/journals/JournalAbbreviationsViewModelTabTest.java Show resolved Hide resolved

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/test/java/org/jabref/gui/preferences/journals/JournalAbbreviationsViewModelTabTest.java Show resolved Hide resolved

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/test/java/org/jabref/logic/journals/JournalAbbreviationRepositoryTest.java Show resolved Hide resolved

fix: address comments by trag-bot

c85ec97

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTab.java Outdated Show resolved Hide resolved

fix: correct Checkstyle issues

5160d78

trag-bot bot reviewed Apr 23, 2025

View reviewed changes

src/main/java/org/jabref/gui/preferences/journals/JournalAbbreviationsTab.java Show resolved Hide resolved

Merge branch 'main' into feature/journal-abbreviation-toggle

ccea652

subhramit reviewed Apr 26, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add toggle functionality for journal abbreviation lists #12912

Add toggle functionality for journal abbreviation lists #12912

zikunz commented Apr 8, 2025 •

edited

Loading

subhramit commented Apr 8, 2025

zikunz commented Apr 8, 2025

zikunz commented Apr 8, 2025

subhramit commented Apr 8, 2025

zikunz commented Apr 8, 2025

zikunz commented Apr 13, 2025

jabref-machine commented Apr 13, 2025

jabref-machine commented Apr 13, 2025

zikunz commented Apr 18, 2025 •

edited

Loading

koppor commented Apr 19, 2025

zikunz commented Apr 19, 2025

trag-bot bot Apr 19, 2025

zikunz commented Apr 23, 2025

zikunz commented Apr 23, 2025

trag-bot bot commented Apr 25, 2025

subhramit commented Apr 26, 2025

subhramit commented Apr 26, 2025

subhramit Apr 26, 2025

		if (!journalAbbreviationRepository.isAbbreviatedName(text)) {
		return false; // Cannot unabbreviate unabbreviated name.

Add toggle functionality for journal abbreviation lists #12912

Are you sure you want to change the base?

Add toggle functionality for journal abbreviation lists #12912

Conversation

zikunz commented Apr 8, 2025 • edited Loading

Toggle Functionality for Journal Abbreviation Lists

What

Why

How

Key Features

Filtering Logic

Persistence

UI Feedback

Design Considerations

Performance Considerations

Design Alternatives Considered

Proposed Code Changes

Frontend Changes (GUI)

Backend Changes (Logic)

Testing Strategy

Test Files and Coverage

Implementation Additions for Testing

Mandatory checks

subhramit commented Apr 8, 2025

zikunz commented Apr 8, 2025

zikunz commented Apr 8, 2025

subhramit commented Apr 8, 2025

zikunz commented Apr 8, 2025

zikunz commented Apr 13, 2025

jabref-machine commented Apr 13, 2025

jabref-machine commented Apr 13, 2025

zikunz commented Apr 18, 2025 • edited Loading

koppor commented Apr 19, 2025

zikunz commented Apr 19, 2025

trag-bot bot Apr 19, 2025

Choose a reason for hiding this comment

zikunz commented Apr 23, 2025

zikunz commented Apr 23, 2025

trag-bot bot commented Apr 25, 2025

subhramit commented Apr 26, 2025

subhramit commented Apr 26, 2025

subhramit Apr 26, 2025

Choose a reason for hiding this comment

zikunz commented Apr 8, 2025 •

edited

Loading

zikunz commented Apr 18, 2025 •

edited

Loading