beeware / beeware/toga

Add a SidebarScaffold

Open
#4,303 2 comments 1 reaction 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
5.4k
Forks
827
Avg merge
15h 39m
Merged PRs (30d)
40

Description

### What is the problem or limitation you are having?

We should provide a SidebarScaffold - a scaffold for an app that contains a single panel of content, plus a mechanism for describing controls for switching between panels of content, displayed in some sort of sidebar or navigation rail.

### Describe the solution you'd like

A SidebarScaffold will extend the default Scaffold (see #4298), but will also accept a definition of a grouped collection of content that can be selected.

The scaffold will have an `on_show_content(widget, selection, **kwargs)` handler; this handler is expected to ensure that the main content widget is in a "presentable" state (updating the values, or replacing the entire content view, based on the selection provided). This mirrors the API from DetailContainer (#4300).

On desktop platforms, the SidebarScaffold will be implemented as 2-part SplitContainer where the left hand container provides an always-visible list of content that can be selected. Tree-based widgets should be used for the list of content.

On iOS, the SidebarScaffold will be implemented using [UISplitViewController](https://developer.apple.com/documentation/uikit/uisplitviewcontroller?language=objc), with the list of content that can be selected being a UITableViewController.

On Android, the SidebarScaffold will be implemented using a [NavigationRail](https://m3.material.io/components/navigation-rail/overview).

### Describe alternatives you've considered

The API for specifying the sidebar content still needs to be designed.

It could be:

* a TreeSource with specific keys for labels, icons, etc
* a collection of OptionItems (or a variant of that basic structure)
* a Group of commands, with the constructor for the SidebarScaffold accepting the Group (or groups?) of commands that will be displayed

### Additional context

See discussions on #4271 for background.

On mobile, the sidebar content will also need to handle the display of App group commands, as the top-left location of the navigation bar that will be used to reveal the sidebar content will occupy the space that is used on the default scaffold to display the app menu.

Contributor guide

Open the contributing guide

Research direction

Start by reading the default Scaffold in #4298, DetailContainer in #4300, and the background discussion in #4271. Compare the desktop SplitContainer and tree-based widgets with the iOS UISplitViewController/UITableViewController and Android NavigationRail requirements; the work is complete when the sidebar API is designed and supported across the stated platforms.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
desktop, frontend, mobile
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.