shinyhub-bookmarks

Selective URL bookmarks for Python Shiny apps running in ShinyHub.

The package registers the filters an app author considers meaningful. ShinyHub then adds a Bookmark this view control to its app switcher. Visitors see a plain-language receipt, can copy the exact view immediately, or customise which registered filters follow the link. Unselected filters return to the app's defaults when the bookmark opens.

from shiny import App, render, ui
from shinyhub_bookmarks import ChoiceRestore, Field, bookmarking_dependency, register


def app_ui(request):
    return ui.page_fluid(
        bookmarking_dependency(),
        ui.input_select("region", "Region", ["Europe", "Americas", "Asia"]),
        ui.input_slider("year", "Year", 2020, 2026, 2026),
        ui.output_text_verbatim("summary"),
    )


def server(input, output, session):
    register(
        session=session,
        input=input,
        fields={
            "region": Field("Region"),
            "year": Field("Year"),
        },
    )

    @render.text
    def summary():
        return f"{input.region()} · {input.year()}"


app = App(app_ui, server, bookmark_store="url")

Both pieces are required: bookmarking_dependency() installs the tiny browser bridge, and register() publishes the allow-list and creates links through Shiny's native bookmarking API. The UI must be a function accepting request so Shiny can restore URL state before rendering it. Call register() exactly once from the top-level server session. Module inputs can be included by their resolved IDs in that top-level field mapping; module-scoped registration is rejected because selective exclusion is owned by the root bookmark session.

Bookmarks that outlive the app

Native Shiny restoration ignores a removed input, but a retired choice can otherwise become empty or fall back differently across widgets. Declare current choices when a bookmark should remain dependable across app releases:

register(
    session=session,
    input=input,
    schema_version=3,
    legacy_fields={"segment": "Market segment"},
    fields={
        "region": Field(
            "Region",
            restore=ChoiceRestore(choices=REGIONS, default="Europe"),
            renamed_from={"territory": "Territory"},
        ),
        "product": Field(
            "Product",
            restore=ChoiceRestore(
                choices=lambda: PRODUCTS,
                default="All products",
                aliases={"Legacy planning": "Planning"},
                control="select",
            ),
        ),
    },
)

ChoiceRestore validates the saved value, applies aliases, and updates the current Shiny choice input. Supported controls are select, selectize, and radio. Multiple selections retain every choice that still exists, use the current display order, and preserve an empty selection. A missing declared default falls back to the valid value Shiny already selected.

renamed_from maps an old input ID to its former label and requires a ChoiceRestore policy so the saved value can actually be applied to the new control. legacy_fields names removed inputs that should be reported as ignored. Every new link records the app's schema_version; older links without metadata remain supported.

For a custom input whose live Python value differs from its JSON bookmark representation, pass an idempotent normalizer= to Field. It is applied to both sides before comparison; it does not change the value Shiny serializes or restores.

When anything changes, the switcher marks the bookmark action and presents a plain-language View adjusted receipt. It names migrated, unavailable, renamed, and removed filters and offers Copy updated link. The app still opens; stale state is never promoted into a blocking error.

An input that is neither registered nor declared as renamed or removed is shown with its URL-provided ID and saved value, labelled Unknown. Both are rendered as bounded plain text. At most three unknown inputs are listed before a compact overflow summary. Copying the updated link drops every unknown setting, so the warning clears on the next visit.

Privacy and behaviour

• The browser-local ShinyHub switcher receives the registered display values and generated URL so it can show the receipt and copy the link. The ShinyHub server neither receives nor persists bookmark state; selected values stay in Shiny's URL.
• Every registered field is selected by default, including values equal to the app's current defaults. The receipt makes that scope explicit before copying.
• App inputs not registered here are always excluded.
• A custom bookmark with no selected fields cannot be created.
• URLs over 8 KiB are rejected by default. Raise max_url_length only when the complete delivery path is known to accept longer URLs.
• The control stays absent when the bridge is not installed, so unsupported apps never show a dead action.