docs

Author: schloerke

docs/_quartodoc-core.yml

@@ -113,8 +113,8 @@ quartodoc:
             desc: "Decorators to set save and restore directories."
           flatten: true
           contents:
-            - bookmark.set_global_save_dir
-            - bookmark.set_global_restore_dir
+            - bookmark.set_global_save_dir_fn
+            - bookmark.set_global_restore_dir_fn
     - title: Chat interface
       desc: Build a chatbot interface
       contents:

shiny/api-examples/bookmark_callbacks/app.py

@@ -0,0 +1,92 @@
+from starlette.requests import Request
+
+from shiny import App, Inputs, Outputs, Session, reactive, render, ui
+from shiny.bookmark import BookmarkState
+
+
+# App UI **must** be a function to ensure that each user restores their own UI values.
+def app_ui(request: Request):
+    return ui.page_fluid(
+        ui.markdown(
+            "Directions: "
+            "\n1. Change the radio buttons below"
+            "\n2. Refresh your browser."
+            "\n3. Only the first radio button will be restored."
+            "\n4. Check the console messages for bookmarking events."
+        ),
+        ui.hr(),
+        ui.input_radio_buttons(
+            "letter",
+            "Choose a letter (Store in Bookmark 'input')",
+            choices=["A", "B", "C"],
+        ),
+        ui.input_radio_buttons(
+            "letter_values",
+            "Choose a letter (Stored in Bookmark 'values' as lowercase)",
+            choices=["A", "B", "C"],
+        ),
+        "Selection:",
+        ui.output_code("letters"),
+    )
+
+
+def server(input: Inputs, output: Outputs, session: Session):
+
+    # Exclude `"letter_values"` from being saved in the bookmark as we'll store it manually for example's sake
+    # Append or adjust this list as needed.
+    session.bookmark.exclude.append("letter_values")
+
+    lowercase_letter = reactive.value()
+
+    @reactive.effect
+    @reactive.event(input.letter_values)
+    async def _():
+        lowercase_letter.set(input.letter_values().lower())
+
+    @render.code
+    def letters():
+        return str(
+            [
+                input.letter(),
+                lowercase_letter(),
+            ]
+        )
+
+    # When the user interacts with the input, we will bookmark the state.
+    @reactive.effect
+    @reactive.event(input.letter, lowercase_letter, ignore_init=True)
+    async def _():
+        await session.bookmark()
+
+    # Before saving state, we can adjust the bookmark state values object
+    @session.bookmark.on_bookmark
+    async def _(state: BookmarkState):
+        print("Bookmark state:", state.input, state.values, state.dir)
+        with reactive.isolate():
+            state.values["lowercase"] = lowercase_letter()
+
+    # After saving state, we will update the query string with the bookmark URL.
+    @session.bookmark.on_bookmarked
+    async def _(url: str):
+        print("Bookmarked url:", url)
+        await session.bookmark.update_query_string(url)
+
+    @session.bookmark.on_restore
+    def _(state: BookmarkState):
+        print("Restore state:", state.input, state.values, state.dir)
+
+        # Update the radio button selection based on the restored state.
+        if "lowercase" in state.values:
+            uppercase = state.values["lowercase"].upper()
+            # This may produce a small blip in the UI as the original value was restored on the client's HTML request, _then_ a message is received by the client to update the value.
+            ui.update_radio_buttons("letter_values", selected=uppercase)
+
+    @session.bookmark.on_restored
+    def _(state: BookmarkState):
+        # For rare cases, you can update the UI after the session has been fully restored.
+        print("Restored state:", state.input, state.values, state.dir)
+
+
+# Make sure to set the bookmark_store to `"url"` (or `"server"`)
+# to store the bookmark information/key in the URL query string.
+app = App(app_ui, server, bookmark_store="url")

shiny/bookmark/_bookmark.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Awaitable, Callable, Literal
 
+from .._docstring import add_example
 from .._utils import AsyncCallbacks, CancelCallback, wrap_async
 from ._button import BOOKMARK_ID
 from ._restore_state import RestoreState
@@ -85,6 +86,7 @@ class Bookmark(ABC):
     _on_restore_callbacks: AsyncCallbacks
     _on_restored_callbacks: AsyncCallbacks
 
+    @add_example("input_bookmark_button")
     async def __call__(self) -> None:
         await self.do_bookmark()
 
@@ -136,6 +138,7 @@ def _restore_context(self) -> RestoreContext | None:
 
     #     await session.insert_ui(modal_with_url(url))
 
+    @add_example("bookmark_callbacks")
     def on_bookmark(
         self,
         callback: (
@@ -157,6 +160,7 @@ def on_bookmark(
         """
         return self._on_bookmark_callbacks.register(wrap_async(callback))
 
+    @add_example("bookmark_callbacks")
     def on_bookmarked(
         self,
         callback: Callable[[str], None] | Callable[[str], Awaitable[None]],

shiny/bookmark/_global.py

@@ -35,19 +35,89 @@ def as_bookmark_dir_fn(fn: BookmarkDirFn | None) -> BookmarkDirFnAsync | None:
     return wrap_async(fn)
 
 
-# TODO: Barret - Integrate Set / Restore for Connect. Ex: Connect https://github.com/posit-dev/connect/blob/8de330aec6a61cf21e160b5081d08a1d3d7e8129/R/connect.R#L915
+def set_global_save_dir_fn(fn: BookmarkDirFn):
+    """
+    Set the global bookmark save directory function.
 
+    This function is NOT intended to be used by app authors. Instead, it is a last resort option for hosted invironments to adjust how bookmarks are saved.
 
-def set_global_save_dir_fn(fn: BookmarkDirFn):
-    """TODO: Barret document"""
+    Parameters
+    ----------
+    fn : BookmarkDirFn
+        The function that will be used to determine the directory where bookmarks are saved. This function should create the directory (`pathlib.Path` object) that is returned.
+
+    Examples
+    --------
+    ```python
+    from pathlib import Path
+    from shiny.bookmark import set_global_save_dir_fn, set_global_restore_dir_fn
+
+    bookmark_dir = Path(__file__).parent / "bookmarks"
+
+    def save_bookmark_dir(id: str) -> Path:
+        save_dir = bookmark_dir / id
+        save_dir.mkdir(parents=True, exist_ok=True)
+        return save_dir
+
+    def restore_bookmark_dir(id: str) -> Path:
+        return bookmark_dir / id
+
+    # Set global defaults for bookmark saving and restoring.
+    set_global_restore_dir_fn(restore_bookmark_dir)
+    set_global_save_dir_fn(save_bookmark_dir)
+
+    app = App(app_ui, server, bookmark_store="server")
+    ```
+
+
+    See Also
+    --------
+    * `~shiny.bookmark.set_global_restore_dir_fn` : Set the global bookmark restore directory function
+    """
     global bookmark_save_dir
 
     bookmark_save_dir = as_bookmark_dir_fn(fn)
     return fn
 
 
 def set_global_restore_dir_fn(fn: BookmarkDirFn):
-    """TODO: Barret document"""
+    """
+    Set the global bookmark restore directory function.
+
+    This function is NOT intended to be used by app authors. Instead, it is a last resort option for hosted invironments to adjust how bookmarks are restored.
+
+    Parameters
+    ----------
+    fn : BookmarkDirFn
+        The function that will be used to determine the directory (`pathlib.Path` object) where bookmarks are restored from.
+
+    Examples
+    --------
+    ```python
+    from pathlib import Path
+    from shiny.bookmark import set_global_save_dir_fn, set_global_restore_dir_fn
+
+    bookmark_dir = Path(__file__).parent / "bookmarks"
+
+    def save_bookmark_dir(id: str) -> Path:
+        save_dir = bookmark_dir / id
+        save_dir.mkdir(parents=True, exist_ok=True)
+        return save_dir
+
+    def restore_bookmark_dir(id: str) -> Path:
+        return bookmark_dir / id
+
+    # Set global defaults for bookmark saving and restoring.
+    set_global_restore_dir_fn(restore_bookmark_dir)
+    set_global_save_dir_fn(save_bookmark_dir)
+
+    app = App(app_ui, server, bookmark_store="server")
+    ```
+
+    See Also
+    --------
+    * `~shiny.bookmark.set_global_save_dir_fn` : Set the global bookmark save directory function.
+    """
     global bookmark_restore_dir
 
     bookmark_restore_dir = as_bookmark_dir_fn(fn)

shiny/bookmark/_restore_state.py

@@ -7,6 +7,7 @@
 from typing import TYPE_CHECKING, Any, Literal, Optional
 from urllib.parse import parse_qs, parse_qsl
 
+from .._docstring import add_example
 from ..module import ResolvedId
 from ._bookmark_state import local_restore_dir
 from ._types import BookmarkRestoreDirFn
@@ -205,7 +206,6 @@ async def _load_state_qs(self, query_string: str, *, app: App) -> None:
         if not self.dir.exists():
             raise RuntimeError("Bookmarked state directory does not exist.")
 
-        # TODO: Barret; Store/restore as JSON
         input_values = from_json_file(self.dir / "input.json")
         self.input = RestoreInputSet(input_values)
 
@@ -387,6 +387,7 @@ def get_current_restore_context() -> RestoreContext | None:
     return ctx
 
 
+@add_example()
 def restore_input(resolved_id: ResolvedId, default: Any) -> Any:
     """
     Restore an input value

shiny/bookmark/_save_state.py

@@ -72,7 +72,6 @@ async def _save_state(self, *, app: App) -> str:
 
         if save_bookmark_fn is None:
             if in_shiny_server():
-                # TODO: Barret; Implement `bookmark_save_dir` for Connect
                 raise NotImplementedError(
                     "The hosting environment does not support server-side bookmarking."
                 )

shiny/session/_session.py

@@ -1201,8 +1201,8 @@ class UpdateProgressMessage(TypedDict):
 
 class SessionProxy(Session):
     def __init__(self, parent: Session, ns: ResolvedId) -> None:
-        # TODO: Barret - Q: Why are we storing `parent`? It really feels like all `._parent` should be replaced with `.root_scope()` or `._root`, really
-        # TODO: Barret - Q: Why is there no super().__init__()? Why don't we proxy to the root on get/set?
+        super().__init__()
+
         self._parent = parent
         self.app = parent.app
         self.id = parent.id

tests/playwright/shiny/bookmark/modules/app-core.py

@@ -15,7 +15,10 @@ def mod_btn(idx: int):
         ui.layout_column_wrap(
             ui.TagList(
                 ui.input_radio_buttons(
-                    "btn1", "Button Input", choices=["a", "b", "c"], selected="a"
+                    "btn1",
+                    "Button Input",
+                    choices=["a", "b", "c"],
+                    selected="a",
                 ),
                 ui.input_radio_buttons(
                     "btn2",