pysxLearn by building

Navigation · Lesson 15 of 28

Links, history and navigation

Use browser history and relative navigation without breaking native anchors.

A navigation link still needs to behave like a link. A modified click, a download, another target or an external URL has native browser meaning. Internal navigation may be intercepted only when that ordinary anchor action is eligible.

Relative paths use familiar filesystem-style ./ and ../ resolution. A query or fragment update changes a different part of the current location. Push adds history; replace changes the current entry.

Understand the moving parts

Link composes a normal callback with the router's navigation decision. A NavigationEvent may explicitly cancel that decision; cancelling is different from changing the destination after navigation already happened.

The controls below change the actual lesson URL. Use Back and Forward after moving between project details. A replace-query control should not create an extra history entry, while a cancelled destination should leave the URL alone.

Walk through the code

from pysx import (
    Fragment,
    Link,
    NavigationEvent,
    Route,
    RouteState,
    Router,
    derived,
    project,
    pysx,
    signal,
)


def routes(router: Router, slug: str, state: RouteState) -> Fragment:
    path = "/pysx/learn/" + slug
    location = derived(lambda: router.location().url)
    notice = signal("No cancelled navigation")
    project = derived(lambda: state.params().get("id", "No project selected"))
    visits = signal(0)

    def increment(_: object) -> None:
        visits.update(lambda value: value + 1)

    def cancel(event: NavigationEvent) -> None:
        event.cancel_navigation()
        notice.set("Navigation cancelled")

    return pysx(t"""
        div:
            Link(router={router} href={path + "/projects/1"} id="route-one"):
                "Project one"
            Link(router={router} href={path + "/projects/2"} id="route-two"):
                "Project two"
            Link(router={router} href="?tab=details" replace={True} id="route-query"):
                "Replace query"
            Link(router={router} href={path} id="route-reset"): "Lesson root"
            Link(router={router} href={path + "/files/docs/start"} id="route-files"):
                "Wildcard files"
            Link(router={router} href={path + "/not-a-project"} id="route-missing"):
                "Lesson fallback"
            Link(router={router} href={path + "/cancelled"} on_navigate={cancel}
                id="route-cancel"): "Cancel this navigation"
            Link(router={router} href={path} target="_blank" id="route-native"):
                "Open lesson in another tab"
        output(id="route-location"): {location}
        output(id="route-project"): {project}
        button(id="route-increment" onClick={increment}): "Increment route-local count"
        output(id="route-count"): {visits}
        output(id="route-notice"): {notice}
    """)


def app() -> Fragment:
    def lesson(state: RouteState) -> Fragment:
        return routes(router, "links-and-history", state)

    router = Router(
        [
            Route("/", lesson),
            Route("/pysx/learn/links-and-history", lesson),
            Route("/pysx/learn/links-and-history" + "/projects/:id", lesson),
            Route("/pysx/learn/links-and-history" + "/files/*path", lesson),
            Route("/pysx/learn/links-and-history" + "/*missing", lesson),
        ]
    )

    return pysx(t"""
        main: {router.view()}
    """)

Project links push real destinations. Replace query uses replace=True; the cancelled link calls cancel_navigation() before changing history. The location readout derives from the same router. The standalone version uses the same lesson paths without the surrounding course navigation.

Try it live

Push a detail URL, replace its query, go Back and Forward, then try a cancelled link.

What to observe

The address bar and readout agree. Cancellation changes neither the destination nor history.

/pysx/learn/links-and-history/not-a-project?tab=detailsNo project selected0No cancelled navigation

Take this with you

Use real links, deliberate history semantics and browser-local native exceptions.