rstudio / rstudio/bslib

🤔 bslib function prefixes

Open
#706 0 comments 2 reactions 0 assignees View on GitHub

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 with update_{type}. The update function modifies options and properties that can be set in the input function.
  • output_{type} pairs with render_{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 that toggle_ would only be used for the primary state reported via input to the server.
  • insert_*() and remove_*() for adding and removing UI elements
  • input_* , output_*, render_*, standard shiny stuff
  • page_* and layout_* for layouts
  • navset_* and nav_* for navs and content toggles

Here are a couple examples of changes we might make, drawn from our current functions:

  • toggle_sidebar() instead of sidebar_toggle() (the second one kinda sounds like a noun and not a verb)
  • toggle_accordion_panel() instead of accordion_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() or insert_nav_panel() would consume nav_append(), nav_prepend() and nav_insert()
  • update_nav_panel() would handle nav_hide() and nav_show()
  • update_navset() would handle nav_select() (or maybe it'd be toggle_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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.