From d5c8a0cbce0619836e6e58760aabd4c9e4df7915 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Tue, 29 Apr 2025 15:23:54 -0400 Subject: [PATCH 1/5] docs: Explicitly call out module usage in bookmark button --- shiny/bookmark/_button.py | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/shiny/bookmark/_button.py b/shiny/bookmark/_button.py index cf2097976..457b41e26 100644 --- a/shiny/bookmark/_button.py +++ b/shiny/bookmark/_button.py @@ -28,6 +28,30 @@ def input_bookmark_button( A `bookmarkButton` is a [input_action_button()] with a default label that consists of a link icon and the text "Bookmark...". It is meant to be used for bookmarking state. + Default behavior + ---------------- + + By default, Shiny will listen for the default `id` being used and call + `session.bookmark()` on button click. However, this will not work if the bookmark + button is used within a module or more than one bookmark button is being utilized. + + For both situations, a custom `id` value is required. + + There are two recommendations to maintain the expected bookmark behavior: + * The supplied `id` value should be excluded from bookmarking with + `session.bookmark.exclude.append(ID)`. + * A reactive effect should be added that performs the bookmarking + (`session.bookmark()`) when the button is pressed. + + ```python + session.bookmark.exclude.append("CUSTOM_ID") + + @reactive.effect + @reactive.event(input.CUSTOM_ID) + async def _(): + await session.bookmark() + ``` + Parameters ---------- label @@ -39,7 +63,7 @@ def input_bookmark_button( disabled Whether the button is disabled. id - An ID for the bookmark button. The only time it is necessary to set the ID unless you have more than one bookmark button in your application. If you specify an input ID, it should be excluded from bookmarking with `session.bookmark.exclude.append(ID)`, and you must create a reactive effect that performs the bookmarking (`session.bookmark()`) when the button is pressed. + An ID for the bookmark button. title A tooltip that is shown when the mouse cursor hovers over the button. kwargs From fb2d2d951798434c979458f97ccef3102b77e4cb Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Tue, 29 Apr 2025 15:25:26 -0400 Subject: [PATCH 2/5] update changelog --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a22f3f3bf..fd03869e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,12 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Improvements -* `selectize`, `remove_button`, and `options` parameters of `ui.input_select()` have been deprecated; use `ui.input_selectize()` instead. (Thanks, @ErdaradunGaztea!) (#1947) +* `selectize`, `remove_button`, and `options` parameters of `ui.input_select()` have been deprecated; use `ui.input_selectize()` instead. (Thanks, @ErdaradunGaztea!) (#1947) * Improved the styling and readability of markdown tables rendered by `ui.Chat()` and `ui.MarkdownStream()`. (#1973) ### Bug fixes +* Explicitly call out module usage in UI input bookmark button documentation. (#1983) + ## [1.4.0] - 2025-04-08 From effcb4c6bcc92559d4be4844107a3f1fa941da17 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Tue, 29 Apr 2025 16:17:21 -0400 Subject: [PATCH 3/5] Update shiny/bookmark/_button.py Co-authored-by: Carson Sievert --- shiny/bookmark/_button.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shiny/bookmark/_button.py b/shiny/bookmark/_button.py index 457b41e26..bb24b5323 100644 --- a/shiny/bookmark/_button.py +++ b/shiny/bookmark/_button.py @@ -28,7 +28,7 @@ def input_bookmark_button( A `bookmarkButton` is a [input_action_button()] with a default label that consists of a link icon and the text "Bookmark...". It is meant to be used for bookmarking state. - Default behavior + Multiple (module) buttons ---------------- By default, Shiny will listen for the default `id` being used and call From 6cdf3323db3ec12284bc6fbd8a87ea0e3aa33a40 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Tue, 29 Apr 2025 16:18:06 -0400 Subject: [PATCH 4/5] Update shiny/bookmark/_button.py Co-authored-by: Carson Sievert --- shiny/bookmark/_button.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shiny/bookmark/_button.py b/shiny/bookmark/_button.py index bb24b5323..4e563716b 100644 --- a/shiny/bookmark/_button.py +++ b/shiny/bookmark/_button.py @@ -63,7 +63,7 @@ async def _(): disabled Whether the button is disabled. id - An ID for the bookmark button. + An ID for the bookmark button. This should only be provided when multiple buttons are needed (or used inside a module). See the note on multiple buttons. title A tooltip that is shown when the mouse cursor hovers over the button. kwargs From 5de0b7bed42d3f3df58aa9c98ca923965f5a9cc0 Mon Sep 17 00:00:00 2001 From: Barret Schloerke Date: Tue, 29 Apr 2025 16:19:16 -0400 Subject: [PATCH 5/5] Move additional section below `Parameters`/`Returns` --- shiny/bookmark/_button.py | 46 +++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/shiny/bookmark/_button.py b/shiny/bookmark/_button.py index 4e563716b..05b9b36c9 100644 --- a/shiny/bookmark/_button.py +++ b/shiny/bookmark/_button.py @@ -28,8 +28,30 @@ def input_bookmark_button( A `bookmarkButton` is a [input_action_button()] with a default label that consists of a link icon and the text "Bookmark...". It is meant to be used for bookmarking state. + Parameters + ---------- + label + The button label. + icon + The icon to display on the button. + width + The CSS width, e.g. '400px', or '100%'. + disabled + Whether the button is disabled. + id + An ID for the bookmark button. This should only be provided when multiple buttons are needed (or used inside a module). See the note on multiple buttons. + title + A tooltip that is shown when the mouse cursor hovers over the button. + kwargs + Additional attributes for the button. + + Returns + ------- + : + A UI element. + Multiple (module) buttons - ---------------- + ------------------------- By default, Shiny will listen for the default `id` being used and call `session.bookmark()` on button click. However, this will not work if the bookmark @@ -52,28 +74,6 @@ async def _(): await session.bookmark() ``` - Parameters - ---------- - label - The button label. - icon - The icon to display on the button. - width - The CSS width, e.g. '400px', or '100%'. - disabled - Whether the button is disabled. - id - An ID for the bookmark button. This should only be provided when multiple buttons are needed (or used inside a module). See the note on multiple buttons. - title - A tooltip that is shown when the mouse cursor hovers over the button. - kwargs - Additional attributes for the button. - - Returns - ------- - : - A UI element. - See Also -------- * :func:`~shiny.ui.input_action_button`