javafx-scene-router/README.md

JavaFX Scene Router

A router implementation for navigating between "pages" in your JavaFX application!

On the web, we tend to take for granted the fact that you can click on a link, go to a new page, then go back, go forward again, click on something else, and it all works seamlessly to route you through the internet. In desktop apps, that's less common, since most apps are simple enough to be built with a single component tree.

However, sometimes you'll want a web-like experience with your desktop app, and for that purpose, I've created javafx-scene-router. It allows you to initialize a router that controls the content of a Pane or similar, and depending on what route is selected, different content will be shown in that pane.

Usage

Add the following dependency to your pom.xml:

<dependency>
    <groupId>com.andrewlalis</groupId>
    <artifactId>javafx-scene-router</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Replace LATEST_VERSION with the most recent version found on maven central.

Then, most often you'll create a singleton instance of SceneRouter, probably in your app's main class like so:

import com.andrewlalis.javafx_scene_router.SceneRouter;

public class MyJavaFXApp extends Application {
    public static final SceneRouter router = new SceneRouter();

    public static void main(String[] args) {
        // Setup the router's routes before starting the app:
        router.map("accounts", MyJavaFXApp.class.getResource("/accounts-view.fxml"));
        router.map("account",  MyJavaFXApp.class.getResource("/account.fxml"));
        router.map("settings", MyJavaFXApp.class.getResource("/settings.fxml"));
        
        launch(args);
    }
}

From here, it's just a matter of attaching the router's view to one of your scene's nodes, and mapping string route names to other nodes or FXML files.

For example, suppose my app has a main scene with a MainController class. We'd hook up the router's view to that scene's center view, assuming you're using an AnchorPaneRouterView for your router (the default choice).

public class MainController {
    @FXML
    public BorderPane borderPane;

    @FXML
    public void initialize() {
        AnchorPaneRouterView view = (AnchorPaneRouterView) MyJavaFXApp.router.getView();
        borderPane.setCenter(view.getAnchorPane());
    }
}

Finally, we can use the router from anywhere in our app to control which "page" is being displayed:

public class MainController {
    // Rest of the class omitted.
    
    @FXML
    public void onBackButton() {
        MyJavaFXApp.router.navigateBack();
    }
    
    @FXML
    public void onAccountClicked() {
        Account acc = getClickedAccount();
        MyJavaFXApp.router.navigate("account", acc);
    }
}

Reactivity

The SceneRouter has been designed to be used in reactive JavaFX projects, and includes a few ways of doing this:

• The currentRouteProperty can be bound to, or have a listener attached, to update each time the current route changes.
• You can getBreadCrumbs() to get an observable list of breadcrumbs that changes each time the route's history changes.
• You can use addRouteChangeListener to add a listener that's notified each time the route has changed, with additional context and the previous route.
• You can use addRouteSelectionListener to add a listener for a specific route, that will be notified only when the router selects that route.
• You can make any of your controllers for route nodes implement RouteSelectionListener, in which case they'll automatically be registered using addRouteSelectionListener. Note that this does not apply to routes mapped using a pre-loaded node, as in the map(String route, Parent node) method. Only methods which take a URL to a resource work with this.