Routing callback inputs

[RenaudLN]

Allows to add new Inputs/States to the pages routing callback, to pass additional data to the layout functions.

This allows things like (non-exhaustive list):

• A language dropdown that will be passed to every layout function, for internationalisation
• Serialising the state in URL hashes without reloading the page on every input update, and using the hash on first load / refresh
• Passing a global app data store on page load

The syntax for this parameter is a dict of State objects: routing_callback_inputs={"language": Input("language", "value")}

Example 1: Internationalisation

app.py

from dash import Dash, Input, html, page_container

app = Dash(
   __name__,
   use_pages=True,
   routing_callback_inputs={
       # The language will be passed as a `layout` keyword argument to page layout functions
       "language": Input("language", "value"),
   },
)
app.layout = html.Div(
   [
       html.Div(
           [
               "My app",
               html.Div(
                   [
                       dcc.Link("Home", href="/"),
                       dcc.Link("Page 1", href="/page-1"),
                       dcc.Dropdown(
                           id="language",
                           options=[
                               {"label": "English", "value": "en"},
                               {"label": "Français", "value": "fr"},
                           ],
                       ),
                   ],
                   style={"marginLeft": "auto", "display": "flex", "gap": 10}
               )
           ],
           style={"background": "#CCC", "padding": 10, "marginBottom": 20, "display": "flex"},
       ),
       page_container,
   ]
)

pages/home.py

from dash import register_page, html

register_page(__name__, "/")

translations = {
    "en": {
        "title": "Hello world",
        "subtitle": "This is the home page.",
    },
    "fr": {
        "title": "Bonjour le monde",
        "subtitle": "Ceci est la page d'accueil.",
    }
}

def layout(language: str = "en"):
    return [
        html.H1(translations[language]["title"]),
        html.H2(translations[language]["subtitle"]),
    ]

Example 2: State serialisation in URL

app.py

from dash import Dash, State, html, page_container
from dash.dash import _ID_LOCATION

app = Dash(
    __name__,
    use_pages=True,
    routing_callback_inputs={
        # The app state is serialised in the URL hash without refreshing the page
        # This URL can be copied and then parsed on first load
        "state": State(_ID_LOCATION, "hash"),
    },
)
app.layout = html.Div(
    [
        html.Div(
            [
                "My app",
                html.Div(
                    [
                        dcc.Link("Home", href="/"),
                        dcc.Link("Page 1", href="/page-1"),
                    ],
                    style={"marginLeft": "auto", "display": "flex", "gap": 10}
                )
            ],
            style={"background": "#CCC", "padding": 10, "marginBottom": 20, "display": "flex"},
        ),
        page_container,
    ]
)

pages/home.py

import base64
import json
from dash import ALL, Input, Output, callback, html, dcc, register_page, ctx
from dash.dash import _ID_LOCATION

register_page(__name__, "/")

def layout(state: str):
    # Define default values
    defaults = {"country": "France", "year": 2020}
    # Decode the state from the hash
    state = defaults | (json.loads(base64.b64decode(state)) if state else {})

    return [
        html.Div(
            [
                dcc.Dropdown(
                    id={"type": "control", "id": "country"},
                    value=state.get("country"),
                    options=["France", "USA", "Canada"],
                ),
                dcc.Dropdown(
                    id={"type": "control", "id": "year"},
                    value=state.get("year"),
                    options=[{"label": str(y), "value": y} for y in range(1980, 2021)],
                ),
            ],
        ),
        html.Div(contents(**state), id="contents")
    ]

def contents(country: str, year: int):
    return f"Country: {country}, Year: {year}"


# Update the hash in the URL Location component
@callback(
    Output(_ID_LOCATION, "hash", allow_duplicate=True),
    Input({"type": "control", "id": ALL}, "value"),
    prevent_initial_call=True,
)
def update_hash(_values):
    return "#" + base64.b64encode(
        json.dumps(
            {inp["id"]["id"]: inp["value"] for inp in ctx.inputs_list[0]}
        )
        .encode("utf-8")
    ).decode("utf-8")


# Update the contents when the dropdowns are updated
@callback(
    Output("contents", "children"),
    Input({"type": "control", "id": "country"}, "value"),
    Input({"type": "control", "id": "year"}, "value"),
    prevent_initial_call=True,
)
def update_contents(country, year):
    return contents(country, year)

Contributor Checklist

• I have run the tests locally and they passed. (refer to testing section in contributing)
• I have added tests, or extended existing tests, to cover any new features or bugs fixed in this PR

optionals

• I have added entry in the CHANGELOG.md
• If this PR needs a follow-up in dash docs, community thread, I have mentioned the relevant URLS as follows
  • this GitHub #PR number updates the dash docs
  • here is the show and tell thread in Plotly Dash community

[T4rk1n]

Looks good, just need to add a test.

[RenaudLN]

Test added 👍

[T4rk1n]

💃 Looks good

[RenaudLN]

Docs update PR link: https://github.com/plotly/ddk-dash-docs/pull/2055