Add a Forms API
- 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
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