pysxLearn by building

Navigation · Lesson 14 of 28

Routes, parameters and deep links

Match a URL and keep route parameters live within an owned branch.

A route gives a URL a view and a lifetime. Parameters identify the record being displayed, while exact, nested, wildcard and fallback matches decide which branch should exist. A deep link must work on the initial HTTP request too.

Routers in one document share its real location. They are not independent toy browsers. This course deliberately places its routing exercise under the lesson's URL so it cannot silently compete with unrelated course routes.

Understand the moving parts

RouteState provides readable params and location. A compatible parameter change can retain a branch's local state; navigating away ends its owned work. Do not confuse that retention with global persistence.

Use the project links below and watch the actual address bar. Copy a project URL into a fresh tab. The lesson and selected project should render immediately without first visiting the course overview.

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, "routes-and-parameters", state)

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

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

The project links match the :id route and state.params() supplies the live project readout. Both project URLs use the same lesson handler, including on a direct deep-link load. The standalone version includes the lesson paths without the surrounding course navigation.

Try it live

Open project one and then project two, inspect the URL, and reload the second deep link.

What to observe

The selected project matches the URL before and after reload. Course navigation still works.

/pysx/learn/routes-and-parameters?tab=detailsNo project selected0No cancelled navigation

Take this with you

A route is both a URL match and an ownership boundary.