beeware / beeware/toga

Add a Forms API

Open
#3,192 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
5.4k
Forks
827
Avg merge
9h 45m
Merged PRs (30d)
58

Description

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

A common feature of rich web framework (e.g., Django) is a Forms API.

Toga has the same constituent parts of a web framework (widgets, labels, layout), and the use cases are much the same (display inputs for a set of inputs that I want to gather and validate); it makes sense that Toga also offers a Form API.

### Describe the solution you'd like

An API, similar in scope to [Django's Form API](https://docs.djangoproject.com/en/5.1/ref/forms/api/), for displaying and validating user input.

Some notable features:
* Data validation via a `clean()`/`is_valid()` process. This would be triggered by the user pressing a "submit" button. Some widgets already have validation and error handling on a per-widget basis; this also needs to allow for validation at the form level (e.g., catching mutually inconsistent values on a form)
* A default rendering mode. It should be possible to just put a form into a layout.
* Access to internals. It should be possible to access the individual widgets and build a custom layout without losing the rest of the form validation API
* The ability to model N-ary relationships (FormSets in Django's API)

### Describe alternatives you've considered

Don't do this at all. Consider it out of scope for Toga, and leave it to third-parties to develop as an add on. However, the Django experience has shown there's significant value in having a good set of defaults available.

### Additional context

This could even be considered a stop-gap measure for #2162. A Form is one of the more common uses for a grid layout - it's effectively a 2xN grid, with column 1 being the labels, and column 2 being the values for the form.

It also ties in with (and is a likely pre-requisite for) #90 - a settings panel would likely be an in-Toga consumer of a Form API.

A Form API (with a default rendering) also allows for platform-specific rendering of forms. For example, on iOS, a form generally isn't rendered as a 2xN grid - it's a variant on a UITableViewController

Contributor guide

Open the contributing guide

Research direction

Review Toga's existing widgets, labels, layouts, and per-widget validation behavior, then compare the requested scope with Django's Form API. Define what the form, rendering, validation, widget access, and FormSet interfaces should be; done means the API and its platform-specific rendering expectations are agreed and implemented.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
desktop, frontend
Issue type
Feature
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.