Adding a Custom Page

Adding a new page (or “route”) to the SpatialDrive client allows you to create custom dashboards, management tools, or specialized views. the Foresight SDK uses a simple routing system that integrates with the egui immediate-mode UI library.

1. Define Your Page Handler

A page is defined by implementing the RouteHandler trait. This trait requires a unique route path and a build_handler method that returns the UI logic.

use fdk::prelude::*;
use fdk::libs::prelude::*;

pub struct MyCustomPage;

impl RouteHandler for MyCustomPage {
    fn route(&self) -> String {
        "/my-custom-page".into()
    }

    fn build_handler(&self, _request: RouteRequest) -> HandlerResult<Box<dyn Route>> {
        // This closure is called every frame when the page is active
        let ui_logic = move |ctx: &mut Ctx, ui: &mut Ui, _router: &mut ()| {
            ui.heading("Welcome to My Custom Page");
            ui.label("This page was added via a compiled plugin.");
            
            if ui.button("Click Me").clicked() {
                println!("Button clicked!");
            }
        };

        Ok(Box::new(ui_logic))
    }
}

2. Register the Route

To make the page accessible, register it within your plugin’s build method using add_route.

impl FoundryPlugin for HelloWorldPlugin {
    fn build(self, app: &mut FoundryPluginBuilder) {
        app.add_route(MyCustomPage);
        
        // Optionally, add a sidebar tab that navigates to this page
        app.add_tab_top(
            TabDescriptor::new("My Page").font_icon("ph-star"),
            "/my-custom-page"
        );
    }
}

3. Navigation

You can navigate between pages using the RouterCommandsCtxExt trait, which provides helper methods on the Ctx object.

To use these helpers, ensure you import the trait from the re-exported libs:

use fdk::libs::prelude::router::RouterCommandsCtxExt;

Navigating to a Route

Use ctx.navigate to move to a specific path:

if ui.button("Go Home").clicked() {
    ctx.navigate("/");
}

Moving Through History

You can easily move backward or forward through the navigation history:

if ui.button("Back").clicked() {
    ctx.back();
}

if ui.button("Forward").clicked() {
    ctx.forward();
}

Key Concepts

• Immediate Mode UI: the Foresight SDK uses egui. Your UI logic runs every frame, making it easy to create reactive interfaces without complex state management.
• Context (Ctx): The Ctx provides access to the engine, resources, and localization.
• Router: Manages the history and active page. Navigation is handled via the RouterCommandsCtxExt trait extension for Ctx.

Next Steps

• UI & Widgets: Learn how to use the SDK’s built-in widgets for a consistent look and feel.
• Asynchronous Tools: Integrate 3D viewport interaction with your custom pages.