Add toggle functionality for journal abbreviation lists

[zikunz]

Toggle Functionality for Journal Abbreviation Lists

Closes #12468.

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:

1. Repository loading is very efficient as it only builds active abbreviation sets
2. Abbreviation operations are typically infrequent user actions
3. 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

1. 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.

2. 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.

3. 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)

1. 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

2. 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

3. 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

4. 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)

5. 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

6. 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

7. 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

8. 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

9. 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

1. 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

2. 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:

1. AbbreviationsFileViewModel.java

   • Added refreshAbbreviations() method to simulate UI updates when toggle state changes
   • Added thorough isEnabled(), setEnabled(), and enabledProperty() methods for test validation

2. 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

3. JournalAbbreviationRepository.java

   • Implemented addCustomAbbreviation(abbreviation, sourcePath, enabled) with source tracking for test scenarios
   • Added test-friendly mapping between abbreviations and their sources for verification

4. 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.

[subhramit]

Please update your screenshots here as well.

[zikunz]

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

[zikunz]

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

[subhramit]

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]

Thank you! @subhramit

[zikunz]

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

[jabref-machine]

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]

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.

[zikunz]

@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:

1. 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".

2. 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.

3. 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.

[koppor]

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

[zikunz]

@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]

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

[zikunz]

@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.

Thank you for your guidance! Upon further reflection, I realized that trag-bot gave contradictory feedback where it first requested using assertTrue/assertFalse then started asking to use assertEqual. Once I recognized this inconsistency, I decided to halt any further modifications.

[zikunz]

Could you also answer #12912 (comment)

Yes sure, please give me some time, I will quote the comment and answer it :)

[zikunz]

Could you also answer #12912 (comment)

Yes sure, please give me some time, I will quote the comment and answer it :)

Thank you for raising this important design question which I did not consider. The current approach is suboptimal. Creating a new repository for every unabbreviate operation is inefficient and could potentially impact performance, especially with multiple external abbreviation lists.

On repository creation

I initially implemented it this way to ensure the operation always uses the latest toggle states, but there is definitely a better approach. I now propose implementing a caching mechanism through a JournalAbbreviationRepositoryManager that would:

• Cache the repository instance
• Only rebuild when preferences actually change
• Provide thread-safe access to the repository

This would maintain the same functionality while eliminating unnecessary repository recreation.

On preferences dependency

Regarding whether unabbreviate should depend on preferences at all, I think the answer is yes, it should, but indirectly. The unabbreviate operation needs to know which abbreviation lists are active, which is determined by user preferences.

However, I agree the current direct dependency is not ideal architecturally. A better approach would be:

1. Have the repository depend on preferences (it needs to know which sources are enabled)
2. Have the unabbreviate operation depend only on the repository
3. Use dependency injection to connect these components

This maintains the same functionality (enabling / disabling abbreviation sources) while better separating concerns.

I just implemented this repository manager approach in this PR. I also addressed all the previous comments you left. Could you please advise me what to do now? Thank you so much! @subhramit

[trag-bot]

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

[InAnYan]

Hi, @zikunz! I think I can hop in and help Subhramit et al. with this PR.

As JabRef is primarily done in free time by volunteers, we typically write small issues and expected small/medium PRs. But sometimes we have PRs that escalate in a lot of work.

Can you tell me:

1. Do you have any blockers?
2. Do you have any questions for design choices that should be discussed with maintainers?
3. What specifically this PR solves/done/improves? So that I know what to test for.
4. What is currently in progress and (if there is) planned in future?

For 4th point -- I think it's better to postpone this

[calixtus]

Please not another Manager. Especially not a repository manager. This is silly, almost funny.
The repository provides everything the application needs. If it needs to be refreshed because preferences have changed and the loading mechanics are dependent on the preferences (which they shouldn't!) the repository needs to handle this internally.

And please do not use AI to communicate with us. Speak real, use your own words.
Remember our two golden rules for use of ai: never let an ai think for you, never let an ai speak for you.