🤔 bslib function prefixes
Nobody has claimed this yet.
- Dominant language
- SCSS
- Stars
- 569
- Forks
- 72
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 5
Description
I've opened this issue to record some thoughts I've written elsewhere about bslib's naming conventions. In general, I think it's worth picking a few standard prefixes that we use in many places.
If we ignore shiny's reversal of the "input" prefix, shiny currently has some prior art on two prefix pairings:
input_{type}pairs withupdate_{type}. The update function modifies options and properties that can be set in the input function.output_{type}pairs withrender_{type}. The render function provides the dynamic output.
We could also increase this surface area to include additional prefixes: toggle_, insert_ and remove_:
update_*()changes the properties of the component – like state, labels, styles, titles, etc – in particular the properties that are set during the component's initialization.toggle_*()is used for binary state only — open/closed, on/off, active/inactive — by default flips state but can force a particular state. A key distinction is thattoggle_would only be used for the primary state reported via input to the server.insert_*()andremove_*()for adding and removing UI elementsinput_*,output_*,render_*, standard shiny stuffpage_*andlayout_*for layoutsnavset_*andnav_*for navs and content toggles
Here are a couple examples of changes we might make, drawn from our current functions:
toggle_sidebar()instead ofsidebar_toggle()(the second one kinda sounds like a noun and not a verb)toggle_accordion_panel()instead ofaccordion_panel_set()toggle_switch()(keeping update_switch())update_accordion_panel()update_accordion()- maybe we don't need this one, but one thing it might do is open/close more than one panel at a time
insert_accordion_panel(),remove_accordion_panel()
This has some reach into nav land, too:
insert_nav()orinsert_nav_panel()would consumenav_append(),nav_prepend()andnav_insert()update_nav_panel()would handlenav_hide()andnav_show()update_navset()would handlenav_select()(or maybe it'd betoggle_nav_panel())
A point about toggle_: Thinking about nav_hide() and nav_show() brought up that toggle_* would only be used for binary state that's reported back to the server. In other words, we wouldn't use toggle_nav_panel() to hide/show the nav because that's not the dominant state of the nav panel. We might also choose not to use toggle_nav_panel() to activate the nav panel because there's no clear opposite (how do you "unactivate" a nav panel?)
To summarize, I think the key for me is the distinction between contexts. When you're writing your UI you're in a "what else goes in an accordion" mind frame. You want to type accordion and hit tab to see the other things you can include there. When you're in your server logic, you're in a different head space. You're thinking about the verb first... "okay so when this input value changes, I want to... update... my accordion".
Related to #676.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with related issue #676 and audit the existing functions named here, including sidebar_toggle(), accordion_panel_set(), nav_append(), nav_prepend(), nav_insert(), nav_hide(), nav_show(), and nav_select(). Compare them with the proposed prefix rules; done means the naming scope and decisions are agreed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- r
- Domain
- developer-experience
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100