GSoC 2025 ‐ Walkthrough and Welcome Tab

Student	Yubo Cao
Organization	[JabRef]
Primary repository	[JabRef/jabref]
Project name	Improved walkthrough and welcome tab
Project mentors	@Siedlerchr, @calixtus, @Houssem Nasri, @ThiloteE, @subhramit
Project page	Google Summer of Code 2025 Project Page
Status	Complete

Project summary

JabRef is a free, open-source reference manager that has been evolving since 2003. Over the years, our community has continuously added new features to help users manage their references more efficiently. However, some of these features can be challenging for new users to discover, and the default setting of certian features cannot be determined without prior knowledge about the user's intended usecase of JabRef. To address such challenge ( #12664 and #9461), walkthroughs and a welcome tab is created to help new users get started with JabRef without needing to read through the entire documentation.

Refined project issue—#12272.

This project implements the following features:

1. Walkthroughs:
   • Configure main file directory
   • Customize the entry table
   • Link PDF/external files to entries through the built-in full-text download, URL download, and directly drag-and-drop file
   • Group entries in library
   • Search through the library using basic full-text search and advanced Lucene syntax
2. Welcome Tab:
   • Responsive layout
   • Quick settings:
     • Set the main file directory
     • Change JabRef's visual theme
     • Optimize JabRef for large libraries
     • Toggle whether citation key should be shown in the entry table
     • Configure push to application
     • Configure whether JabRef should check for update on start, web search, Mr. DLib, Grobid, and other online services
   • Walkthroughs can be directly opened from the welcome tab, making it easier for new users to get started with JabRef.
   • Donation Prompt

Pull Requests to main branch:

Scope—GSoC

#13182—Implementation of walkthrough infrastructure

• Implemented walkthrough infrastructure that contains a:
  • Declarative API to create new walkthroughs
  • A walkthrough renderer that can robustly resolve the node that needs to be highlighted, revert to previous state if the user clicks outside the walkthrough, and handle the case where the node is not visible in the current view

#13595—Walkthrough Fixes

• Adapt an entirely event-driven approach to render walkthroughs, instead of using a Timeline to poll the node in the event tree every 50ms
• Support more robust walkthrough creation that may involve modifying JabRef's state, such as changing the library or search settings

#13679—Add more walkthroughs, donation prompt, and responsive layout for welcome tab

• File search and add group walkthroughs are implemented
• Donation prompt that would show up annually on the welcome tab is implemented
• Make welcome tab responsive and change from two-column layout to one-column layout on small screens

#13407—Welcome tab

• Initial refinement of the welcome tab that includes quick settings and two-column layout

Outside core scope

#13194—Add Markdown rendering to AI Chat

• Used Flexmark to render Markdown in AI Chat
• Used rangeShape to implement a selectable TextFlow

#13386—Dark Titlebar

• Make JabRef's title bar adapt to the system theme

#13192—Update Gradle Properties

Before GSoC

#12880—Add support for LTWA (issue #12276)

• Used Antlr4 to build a title parser
• Implemented support for abbreivating Journal title using ISO 4's List of Title Words Abbreviations (LTWA)

#12978—Update documentation images and fix spelling

• Updated getting started guide for new developers

Here is a complete list of my commits to JabRef (main).

Screenshots

Welcome tab in light theme.

Welcome tab in dark theme.

Link PDF to entry walkthrough:

Change theme quick settings dialog:

Challenges and learning highlights

Many challenges were encountered during the project, but the most significant are as follows:

1. It was not possible to debug unit-tests in Windows because of Gradle's long-path mitigation failed to shorten the command line length sufficiently to work under the Windows's character limit (#34003)
2. JavaFX's Platform.runLater cannot deterministically schedule the task to run in the JavaFX application thread, not only leading to not easily reproducible bugs but also making it difficult to debug the state transition errors in the walkthrough renderer, especially after switching to a purely event-driven approach (#13595)
3. JavaFX's onMouseClicked is not as robust as a HTML button's onClick, but rather can be overriden by a variety of other events, such as onAction, event filters, and onMousePressed (note click is only triggered after a press and release is left-unconsumed). As such, to maintain the generality of the walkthrough renderer, reading JavaFX's source code and understanding how to write EventDispatcher turned out to be necessary.
4. Stylesheet applied on a JavaFX window doesn't inherit from the parent window's stylesheet, making popup windows' requiring case-by-case styling.

As a result of overcoming the above challenges (and many other), I have learned a lot about JavaFX and how to debug JavaFX applications. But perhaps the more important learning highlights are:

1. Work with teams across different timezones, and to communicate effectively with my mentors, other contributors, and the community.
2. Ask for assistance when needed, and present my work in ways that's easy to understand and follow during the weekly meetings.