[ENH] Sticky sync tabs and URL param #104

mikemckiernan · 2022-10-26T14:52:10Z

Addresses #103.

Add a Sphinx configuration option that is named
sphinx_design_sync_tabs_storage_key so that I can set a project-specific local storage key rather than risk clobbering the value for sphinx-design-last-tab across different projects.

Add support for a URL search param ?tab=blah
so that I can copy and paste a URL and the receiver sees the tab
content that I see. The URL search param is set in browser
local storage when you click a tab.

If you visit a URL with search param ?tab=blah, set the
local storage value to blah. If blah matches
a synchronization key for a tab, show the tab.

welcome · 2022-10-26T14:52:12Z

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.

Welcome to the EBP community! 🎉

mikemckiernan · 2022-10-29T13:04:41Z

@chrisjsewell , please let me know if there's something I need to do before a review. Also, I'm completely open to suggestion on changes.

chrisjsewell · 2022-11-04T17:52:35Z

Hey @mikemckiernan, sorry I wasn't able to look at this just yet, maybe @choldgraf could have a quick look?

mikemckiernan · 2022-11-07T18:15:36Z

Yep, it'd be great if @choldgraf could peek and provide feedback. I appreciate everyone's time and help. Great project too!

choldgraf

This looks helpful, thanks - a few quick questions on the UX for this.

choldgraf · 2022-11-08T13:39:08Z

docs/tabs.md

+To include the tab as a URL parameter, add a setting like the following example in your `conf.py` file:
+
+```python
+sphinx_design_sync_tabs_url_param = "tab"


What's the benefit of making this configurable? My general preference is to keep our configuration surface area as small as possible unless somebody explicitly asks for extra functionality. E.g., just force the url param to be something like sd-last-tab

The benefit of making it configurable is that the URL is customer-facing. The two common URL search param values that I've seen in the wild are code and tab. My thinking is that the tabs don't always show code, so that felt wrong to hard code. If you prefer a single, hard-coded value, my preference is tab and I can revise it so.

my general inclination is always to start with the simplest-humanly-possible configuration/implementation, and only complexify once there's clear demand for it, in order to minimize our maintenance burden and the likelihood of deprecations, given that these projects all have pretty limited ongoing maintenance time.

So I'd suggest we ask this question: how important do you think it is to be able to configure the URL param? If >20% of users would want to configure it, let's add it here. If <20% would, then let's keep it simple and see if people request this in the future.

After revising, I forgot one more reason for making the URL search param configurable. If the end user does not set it, then the URL is not set with a search param after clicking a tab (though stickiness still works because local storage is set). Originally, I thought this was a decent compromise for backward compatibility since the current release doesn't set a URL search param.

docs/tabs.md

choldgraf · 2022-11-08T13:43:18Z

sphinx_design/compiled/sd_tabs.js

+const storageKey = '&{storage_key}';
+// The default value for paramKey is the string 'None'. That value indicates
+// not to set a URL search parameter.
+const paramKey = '&{param_key}';


I'm a bit confused about the UX if people have multiple groups of synced tabs throughout their site. In that case would it just store the state of the synced tab group that was last-clicked?

That sounds correct--if one Sphinx project has a set of synchronized tabs with python, java, and c and another set with lua and shell, or windows and linux for that matter, then whatever is clicked last is set in the storage key. We'd need add another option for the tab and store the data so folks could specify the python-java-c sets differently from the windows-linux sets.

I was thinking that the typical use is for a Sphinx project to use the tabs for programming language, platform, or user interface. If you feel that isn't featureful enough and want to add an option, LMK and I'll see what I can do.

yep I think you're probably right, but we should just clarify this in the docs so that people know what to expect. My feeling is that for now we should just assume a single set of synced tabs, and expand the complexity only if people request it explicitly

I typed more about the UX, though I might have poisoned the problem.

https://sphinx-design--104.org.readthedocs.build/en/104/tabs.html#save-tab-state-across-visits

Oh, and you can be the second person with first-hand user experience: https://sphinx-design--104.org.readthedocs.build/en/104/tabs.html?tab=rst

mikemckiernan · 2022-11-15T14:58:48Z

@choldgraf , thanks for the feedback. PLMK if there's anything else you'd like changed or that I can clarify.

mikemckiernan · 2023-01-05T17:12:18Z

@choldgraf , @chrisjsewell , can I get another look at this PR? I'd like to get my org to bring in this change from upstream. Thanks and let me know if there's anything else to revise.

chrisjsewell · 2023-01-10T09:38:41Z

@choldgraf this is still awaiting your feedback

Add a Sphinx configuration option that is named `sphinx_design_sync_tabs_storage_key` so that users can set a project-specific local storage key rather than risk clobbering the value for `sphinx-design-last-tab` across different projects. Add support for an optional URL search param of like `?tab=blah` or `?code=blah` so that I can copy and paste a URL and the receiver sees the tab content that I see. By default, no param and you get to add "Oh, and click blah" in your message. If the URL has search param `?tab=blah`, set the local storage value to `blah`. If `blah` matches a synchronization key for a tab, show the tab. When someone clicks a tab, set the local storage value to the synchronization key value and also update the URL search params with `?tab=<value>` if the project configures a URL param.

mikemckiernan · 2023-02-13T17:18:37Z

@choldgraf , @chrisjsewell , any chance of another look? I'm running out of runway. Thanks very much.

We need #119 or #120 first though.

torbsorb · 2024-01-03T08:47:54Z

In our project we used to use sphinx-tabs which already has this feature. Maybe sphinx-design could adopt that method? https://github.com/executablebooks/sphinx-tabs/blob/master/sphinx_tabs/static/tabs.js. It has the advantage of not cluttering the URL.

mikemckiernan force-pushed the sticky-tabs branch from 0f4f48f to 816517d Compare October 28, 2022 19:55

choldgraf reviewed Nov 8, 2022

View reviewed changes

maximlt mentioned this pull request Jan 18, 2023

Categorization and tagging holoviz-topics/examples#236

Open

mikemckiernan force-pushed the sticky-tabs branch from 1e1a002 to c8c0fd6 Compare February 2, 2023 14:03

BasPH mentioned this pull request Dec 4, 2023

Add support for tabs (and other UX components) to docs apache/airflow#36041

Merged

mikemckiernan closed this May 21, 2024

chrisjsewell mentioned this pull request May 22, 2024

✨ NEW: sync tabs by URL query parameters #196

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[ENH] Sticky sync tabs and URL param #104

[ENH] Sticky sync tabs and URL param #104

mikemckiernan commented Oct 26, 2022 •

edited

welcome bot commented Oct 26, 2022

mikemckiernan commented Oct 29, 2022

chrisjsewell commented Nov 4, 2022

mikemckiernan commented Nov 7, 2022

choldgraf left a comment

choldgraf Nov 8, 2022

mikemckiernan Nov 8, 2022 •

edited

choldgraf Nov 9, 2022

mikemckiernan Nov 9, 2022

choldgraf Nov 8, 2022

mikemckiernan Nov 9, 2022 •

edited

choldgraf Nov 9, 2022

mikemckiernan Nov 9, 2022 •

edited

mikemckiernan commented Nov 15, 2022

mikemckiernan commented Jan 5, 2023

chrisjsewell commented Jan 10, 2023

mikemckiernan commented Feb 13, 2023

torbsorb commented Jan 3, 2024

[ENH] Sticky sync tabs and URL param #104

[ENH] Sticky sync tabs and URL param #104

Conversation

mikemckiernan commented Oct 26, 2022 • edited

welcome bot commented Oct 26, 2022

mikemckiernan commented Oct 29, 2022

chrisjsewell commented Nov 4, 2022

mikemckiernan commented Nov 7, 2022

choldgraf left a comment

Choose a reason for hiding this comment

choldgraf Nov 8, 2022

Choose a reason for hiding this comment

mikemckiernan Nov 8, 2022 • edited

Choose a reason for hiding this comment

choldgraf Nov 9, 2022

Choose a reason for hiding this comment

mikemckiernan Nov 9, 2022

Choose a reason for hiding this comment

choldgraf Nov 8, 2022

Choose a reason for hiding this comment

mikemckiernan Nov 9, 2022 • edited

Choose a reason for hiding this comment

choldgraf Nov 9, 2022

Choose a reason for hiding this comment

mikemckiernan Nov 9, 2022 • edited

Choose a reason for hiding this comment

mikemckiernan commented Nov 15, 2022

mikemckiernan commented Jan 5, 2023

chrisjsewell commented Jan 10, 2023

mikemckiernan commented Feb 13, 2023

torbsorb commented Jan 3, 2024

mikemckiernan commented Oct 26, 2022 •

edited

mikemckiernan Nov 8, 2022 •

edited

mikemckiernan Nov 9, 2022 •

edited

mikemckiernan Nov 9, 2022 •

edited