V1 documentation

[AnnMarieW]

It's awesome to see the progress on the Bootstrap 5 support - there are so many cool new features. :confetti_ball:

Here is a list of suggested changes and additions to the documentation. Perhaps we can use this to track all pre-release issues in the docs. This looks like a long list, but most of the items will be easy to fix. I'm happy to get started on a PR for any of the changes you approve.

Home page

• [x] On the homepage the Bootstrap example formatting is lost with the change to the Navbar. Unfortunately simply adding the container as Bootstrap 5 requires won't work as the content of the navbar is then too long. (Fixed in #676 )

Themes Page

• [x] Update references from Bootstrap v4 to v5 (Fixed in #686)

Left Nav menu

• [x] "Dash for R" just goes to the Quickstart page. Delete? (Fixed in v1)
• [x] Add a section for how to add Bootstrap Icons (Fixed in #661 )

Quickstart

• [x] :arrow_up_small: Language tabs for all examples aren't working (Fixed in #654 )

Overall

• [x] Headings - The first subheadings are currently inconsistent. For example, sometimes it's "Basic Example" or "Basic Usage" or "Simple Example" (or none). I think it would be better to make them all "Examples" to match the official Bootstrap documentation. (Fixed in v1)
• [x] Change all the examples back to camelCase (Fixed in #684)
• [x] Now that Dash isn't using class_name in their components, we ought to change the html ones back to className. This does depend on the note in the original bit though about delaying moving all components back to className, and how quickly this is pushed out over. (Fixed in #684)
• [x] Make sure new components have both className and class_name. (Fixed in v1)
• [x] Add R/Julia formatters and linting (low priority) (Fixed in v1)
• [x] Links now all have text-decoration by default - needs removing
• [x] ~Question: Should we also provide some other options for styling links? Perhaps show how to add custom css to revert all links back to Bootstrap 4 behaviour? In V4, the link was underlined on hover, and in V5 it is not. I think just removing the underline makes it less clear that it's a link. Also in V5: Removed hover and focus styles for <a> and <button> elements. We are still showing a hover effect in Badge. Should this be changed in the component?~ Not changing this now. Will reconsider if people start complaining.
• [x] ~Remove lists from callback Output, Input State in snippets~ Worth keeping as is, as it maintains backwards compatibility, and doesn't provide that many advantages over the current approach

Component Landing Page

• [x] Add more content including full example of how to use the component in an app (Fixed in #687 )

Icons Page

• [x] Add more content (Fixed in #661 )

Accordion

• [x] First example should be without a callback, and move the example with the callback to the end. (Fixed in #653 )

Alerts

• [x] It would be cool to add an example with Bootstrap Icons, like shown here. Perhaps add a section to show how to add the Bootstrap icons and the icon stylesheet. (Fixed in #661 )
• [x] Toggle with and without fade looks the same to me. Add a prop for transition time? (Fixed in #654 )

Badge

• [x] Can't read the number in the badge in the first example. Change class_name to "bg-secondary" (Fixed in #659 )
• [x] I just realized that the reason you couldn't read the number in the badge in the first example was because of a change made in Bootstrap 5 that eliminated the badge-* color classes and now you need to set background color and text color independently. There is now a text_color prop. Should we demo this new prop instead of adding text-primary to the class_name? (Fixed in #659 )
• [x] Add example for "Positioned". It's pretty cool and shows off some of the new Bootstrap classes. (Fixed in #659 )
• [x] Change heading "Conteztual variations" to "Background colors". (Fixed in v1)
• [x] In Pill badges add "text-dark" to the class_name in the "bg-light" example. (Fixed in #659 )

Breadcrumb

• [x] Add definition of Breadcrumb - "Indicate the current page's location within a navigation hierarchy and automatically adds separators" (Fixed in v1)

Buttons and Button Groups

• [x] Block buttons example - Add more examples on formatting with classes - or just add a link to the Bootstrap docs? (Fixed in #660 )
• [x] Add ToggleButton and ToggleButtonGroup components from react-bootstrap. Add "Toggle states" example, and remove the "RadioItems as ButtonGroup" example. (Save for a future release)
• [x] Add mixed styles and outline example to Button Groups (Fixed in #660 )
• [x] Add example for the download prop. (Fixed in #660 )
• [x] Dropdown inside ButtonGroup isn't formatted correctly (Fixed in #662 )

Card

• [x] Add image overlay example. (Fixed in #665 )
• [x] Add Horizontal example. (Fixed in #665 )
• [x] ~Add Grid cards example.~ (Possibly add in future)

Carousel

• [x] Add Dark variant example. This is cool! - it was annoying when you couldn't easily change the color of the indicators and captions in V4. (Fixed in #653 )
• [x] Julia and R examples aren't working with interval (Fixed in #655 )

Collapse

• [x] :arrow_up_small: Remove Accordion example from this section now that there is an Accordion component. (Fixed in #653 )

Dropdown Menu

• [x] :arrow_up_small: DropdownMenu direction doesn't work - they are all the same. (Fixed in #662 )
• [x] :arrow_up_small: DropdownMenu alignment doesn't work. (Fixed in #662 )
• [x] :arrow_up_small: Divider=True does not show a divider. (Fixed in #662 )
• [x] ~Add a Split button example.~ Not really supported right now, add in future release perhaps.
• [x] Add a Dark dropdowns example. (Fixed in #662 )
• [x] ~Add Active example.~ Already included in the Menu content example

Fade

• [x] all good

Input

• [x] Update the text in the "Labels and text" and "RadioItems and Checklist" examples to remove the FormGroup (Fixed in #674 )

InputGroup

• [x] Add Multiple addons example. (Fixed in v1)

Jumbotron

• [x] Even though Jumbotron component has been dropped in Bootstrap 5, we could just include it as an example - at least for a while. https://getbootstrap.com/docs/5.0/examples/jumbotron/ (See #671 )

Layout

• [x] ...
• [x] Order is a maximum of 5 instead of 12. Changed in react-bootstrap to match Bootstrap 5 grid changes (Fixed in #664 )

ListGroup

• [x] Add Flush example. (Fixed in #653 )
• [x] Add Horizontal example. (Fixed in #653 )

Modal

• [x] :arrow_up_small: The full screen example doesn't work (Fixed in #653 )
• [x] Add a toggle between modals example? It's kinda cool. (Fixed in #672 )
• [x] R/JL callbacks not working for size (Fixed in #655 )
• [x] loading_state being passed to ModalHeader and ModalTitle. Should be omitted. (Fixed in #666 )
• [x] change zIndex to zindex or z_index for consistancy? (Fixed in #666 )

Nav

• [x] :arrow_up_small: Dropdown button doesn't work (Fixed in #662 )
• [x] Dropped active property in NavItem, but is there a workaround for this? react-bootstrap does not have a prop for active in NavItem (Clarified in #675 )

NavBar

• [x] :arrow_up_small: NavbarSimple - Dropdown button doesn't work and alignment is wrong (Fixed in #662 )
• [x] :arrow_up_small: Navbar example - Alignment and margins are wrong. The brand should not show link format (underlined). (Fixed in #654 )
• [x] :arrow_up_small: Bootstrap 5 breaking change NavBar now requires a container. Should update Navbar example to include an inner container (Fixed in #667 )
• [x] Navbar example - Toggler button becomes left-aligned when clicked on a small screen (Fixed in #667 )

Offcanvas

• [x] Cool! and great examples!
• [x] Issues as using the version of bootstrap that has the backdrop in front of the offcanvas so all tests will fail - need to get this fixed by react-bootstrap (appears to be a closed PR recently so shouldn't be long now) (Fixed in #655 )

Pagination

• [x] :arrow_up_small: Make first example without a callback and move callback example to the end. (Fixed in #653 )

Popover

• [x] The default position should be to the right. (Fixed in #652)
• [x] Fix tests (Fixed in #655 )

Progress

• [x] :arrow_up_small:The example with Interval doesn't work. (Fixed in #663 )
• [x] ~Add example using app.long_callback? (Might be complicated as docs are reasonably high traffic and lots of people running the example could swamp the docs server. Maybe a non-running example / link to examples/)~ Not right now as we don't want to deploy Redis backend for the docs, too much complexity for marginal value.

Spinners

• [x] All good

Tabs

• [x] :arrow_up_small: card=True is no longer required? If so the text in "Tabs in cards" example should be updated. Plus, should it be removed from here in Tabs.js?

Table

• [x] Add table-colors example. (Fixed in 653)
• [x] Add multi header example to Table from DataFrame. (Fixed in #653 )

Toast

• [x] :arrow_up_small: In the first example, the X button doesn't work. (Fixedin #654 )

Tooltips

• [x] All good

[tcbegley]

Amazing! Thanks so much for taking the time to go through this list @AnnMarieW! I haven't read them all super carefully yet, but it looks like these are all great suggestions.

Once we get the #646 finished up and merged into v1 branch, I would be very happy for us to start working through this list.

[glsdown]

@AnnMarieW - I've been working through some of the docs snippets and fixing components where I can. I think over in PR #653 I've now got all the layouts working, but having some issues with a couple of pesky javascript and callback ones (if you wanted to take a look, feel free to). Happy to start working through some of these too.

Also noticed a couple of other things in the docs (they may be things that have been broken in #646 / #653, but including here so it's all in one place):

• [x] The first example on the tooltip page isn't working (Fixed in #655 )
• [x] The navbar collapsible menu isn't working - either in the example or in the main app itself (Fixed in v1)
• [x] RadioItems as ButtonGroup formatting is interesting (Fixed in #658 )
• [x] Dropdown menus appear to have stopped working (Fixed in #662 )

[AnnMarieW]

Hi @glsdown Thanks for your comments -- I'll keep an eye on #653 and #646 and update the progress here too.

Many of the suggestions for examples to add are low priority. I know that any additions come with the overhead of maintaining them in the long term, not only in Python, but in Julia and R as well. They should probably be ranked for the ones that would add the most value. I have marked the items with bugs and 2 examples that I think have a higher priority with a :arrow_up_small:

The Dropdown menu bugs are noted here already, but I the first Tooltip example and Navbar collapse seems to work for me. It's just the Dropdown menu inside the collapsed Navbar that doesn't work. Do you think it's just different versions?

btw, I :heart_eyes: the Accordion, Offcanvas, Pagnation, and Breadcrumb components you added. I can't wait for V1 to be live!

---

---

---

---

[glsdown]

Thanks! I've had a lot of help with them though.

Unfortunately, none of them appear to work for me on the react-bootstrap branch #646 , so it's probably something @tcbegley or I have broken in the move over to react-bootstrap (unless that's the one you are working on, in which case I have no idea why it's not working for me). With the drop downs, all of them are really temperamental. Some of them work when you click on them, some of them bring up a drop down halfway across the screen, and some of them just don't display anything. The same drop down will exhibit all 3 behaviours too...

I'll take a look at it this evening, and see where it has been introduced.

[glsdown]

@AnnMarieW I've made some of the changes above (now ticked) and they should now all be merged into v1 branch.

@tcbegley has said not to do the following though:

In the sidebar...

• Change "Alert" to "Alerts"
• Change "Button" to "Buttons"
• Change "Spinner" to "Spinners"
• Change Toast to Toasts
• Change Tooltip to Tooltips

He thinks that having the sidebar as the component name works at the moment rather than copying the bootstrap style.

Also he said to leave for now until it's clearer what Dash are doing:

• Change all the examples back to camelCase

Additionally outstanding from the work I was doing on updating and making sure tests were run are:

• Callback tests failing for docs:
  • carousel - this auto advances with R and Julia. I think setting interval=None is the thing that stops it advancing in python, but the equivalents in R (NULL) and julia (nothing) don't do the same thing (also tried with 0, and that didn't work either).
  • modal - R/JL callbacks not working for size but I'm unsure why as the python one does, and I can't see there are any functional differences
  • offcanvas - issues as using the version of bootstrap that has the backdrop in front of the offcanvas so all tests will fail - need to get this fixed by react-bootstrap (appears to be a closed PR recently so shouldn't be long now)
  • popover - It doesn't appear that the component ID is being passed to the element on the page which is why the tests themselves are failing here, although even if the tests were working, it seems to respond differently to bools in JL as doesn't react to 0 and 1, but does to explicit true/false, however, can't narrow down what is causing the callbacks to fail.
• Populate landing page for components - in docs/components_page/components/main.md
• Add R/Julia formatters and linting (low priority)

[AnnMarieW]

Great - I made updates to the checklist.

Good point regarding not changing the names on the sidebar - it makes more sense to match the component name. I'm still not sure whether it's worthwhile adding more new examples, but they can stay on the list as low priority suggestions.

[glsdown]

One to add on the list above:

• [x] On the homepage the Bootstrap example formatting is lost with the change to the Navbar. Unfortunately simply adding the container as Bootstrap 5 requires won't work as the content of the navbar is then too long.

[glsdown]

Another item to add to the list above:

• [x] Now that Dash isn't using class_name in their components, we ought to change the html ones back to className. This does depend on the note in the original bit though about delaying moving all components back to className, and how quickly this is pushed out over.

[tcbegley]

Closing as checklist has been completed, preview docs here