You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The advantage of the PRG pattern is that it is very straightforward to implement and keeps most of the rendering logic on the server side. The disadvantage is that it requires an extra round trip to the database to fetch the updated data, and re-rendering the entire page template may be less efficient than a partial page update on the client side.
62
+
The advantage of the PRG pattern is that it is very straightforward to implement and keeps most of the rendering logic on the server side. The disadvantage is that it requires an extra round trip to the database to fetch the updated data, and re-rendering the entire page template may be less efficient than a partial page update on the client side.
63
+
64
+
## Form validation flow
65
+
66
+
We've experimented with several approaches to validating form inputs in the FastAPI endpoints.
67
+
68
+
### Objectives
69
+
70
+
Ideally, on an invalid input, we would redirect the user back to the form, preserving their inputs and displaying an error message about which input was invalid.
71
+
72
+
This would keep the error handling consistent with the PRG pattern described in the [Architecture](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/architecture) section of this documentation.
73
+
74
+
To keep the code DRY, we'd also like to handle such validation with Pydantic dependencies, Python exceptions, and exception-handling middleware as much as possible.
75
+
76
+
### Obstacles
77
+
78
+
One challenge is that if we redirect back to the page with the form, the page is re-rendered with empty form fields.
79
+
80
+
This can be overcome by passing the inputs from the request as context variables to the template.
81
+
82
+
But that's a bit clunky, because then we have to support form-specific context variables in every form page and corresponding GET endpoint.
83
+
84
+
Also, we have to:
85
+
86
+
1. access the request object (which is not by default available to our middleware), and
87
+
2. extract the form inputs (at least one of which is invalid in this error case), and
88
+
3. pass the form inputs to the template (which is a bit challenging to do in a DRY way since there are different sets of form inputs for different forms).
89
+
90
+
Solving these challenges is possible, but gets high-complexity pretty quickly.
91
+
92
+
### Approaches
93
+
94
+
The best solution, I think, is to use really robust client-side form validation to prevent invalid inputs from being sent to the server in the first place. That makes it less important what we do on the server side, although we still need to handle the server-side error case as a backup in the event that something slips past our validation on the client side.
95
+
96
+
Here are some patterns we've considered for server-side error handling:
97
+
98
+
<style>
99
+
.styled-table, .styled-tableth, .styled-tabletd {
100
+
border: 1pxsolidblack;
101
+
padding: 8px;
102
+
border-collapse: collapse;
103
+
}
104
+
105
+
.styled-tableth:nth-child(1) { width: 5%; }
106
+
.styled-tableth:nth-child(2) { width: 50%; }
107
+
.styled-tableth:nth-child(3),
108
+
.styled-tableth:nth-child(4),
109
+
.styled-tableth:nth-child(5) { width: 15%; }
110
+
.styled-tableth:nth-child(6) { width: 10%; }
111
+
</style>
112
+
113
+
<tableclass="styled-table">
114
+
<thead>
115
+
<tr>
116
+
<th>ID</th>
117
+
<th>Approach</th>
118
+
<th>Returns to same page</th>
119
+
<th>Preserves form inputs</th>
120
+
<th>Follows PRG pattern</th>
121
+
<th>Complexity</th>
122
+
</tr>
123
+
</thead>
124
+
<tbody>
125
+
<tr>
126
+
<td>1</td>
127
+
<td>Validate with Pydantic dependency, catch and redirect from middleware (with exception message as context) to an error page with "go back" button</td>
128
+
<td>No</td>
129
+
<td>Yes</td>
130
+
<td>Yes</td>
131
+
<td>Low</td>
132
+
</tr>
133
+
<tr>
134
+
<td>2</td>
135
+
<td>Validate in FastAPI endpoint function body, redirect to origin page with error message query param</td>
136
+
<td>Yes</td>
137
+
<td>No</td>
138
+
<td>Yes</td>
139
+
<td>Medium</td>
140
+
</tr>
141
+
<tr>
142
+
<td>3</td>
143
+
<td>Validate in FastAPI endpoint function body, redirect to origin page with error message query param and form inputs as context so we can re-render page with original form inputs</td>
144
+
<td>Yes</td>
145
+
<td>Yes</td>
146
+
<td>Yes</td>
147
+
<td>High</td>
148
+
</tr>
149
+
<tr>
150
+
<td>4</td>
151
+
<td>Validate with Pydantic dependency, use session context to get form inputs from request, redirect to origin page from middleware with exception message and form inputs as context so we can re-render page with original form inputs</td>
152
+
<td>Yes</td>
153
+
<td>Yes</td>
154
+
<td>Yes</td>
155
+
<td>High</td>
156
+
</tr>
157
+
<tr>
158
+
<td>5</td>
159
+
<td>Validate in either Pydantic dependency or function endpoint body and directly return error message or error toast HTML partial in JSON, then mount error toast with HTMX or some simple layout-level Javascript</td>
160
+
<td>Yes</td>
161
+
<td>Yes</td>
162
+
<td>No</td>
163
+
<td>Low</td>
164
+
</tr>
165
+
</tbody>
166
+
</table>
167
+
168
+
Presently this template primarily uses option 1 but also supports option 2. Ultimately, I think option 5 will be preferable; support for that [is planned](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/issues/5) for a future update or fork of this template.
Copy file name to clipboardExpand all lines: docs/contributing.qmd
+49-9Lines changed: 49 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,46 @@ title: "Contributing"
4
4
5
5
## Contributors
6
6
7
-
Fork the repository, create a new branch, make your changes, and submit a pull request.
7
+
### Opening issues and bug reports
8
8
9
-
### Render the documentation
9
+
When opening a new issue or submitting a bug report, please include:
10
10
11
-
The README and documentation website are rendered with [Quarto](https://quarto.org/docs/). Make changes to the `.qmd` files in the root folder and the `docs` folder. Then run the following commands to render:
11
+
1. A clear, descriptive title
12
+
2. For bug reports:
13
+
- Description of the expected behavior
14
+
- Description of the actual behavior
15
+
- Steps to reproduce the issue
16
+
- Version information (OS, Python version, package version)
17
+
- Any relevant error messages or screenshots
18
+
3. For feature requests:
19
+
- Description of the proposed feature
20
+
- Use case or motivation for the feature
21
+
- Any implementation suggestions (optional)
22
+
23
+
Labels help categorize issues:
24
+
- Use `bug` for reporting problems
25
+
- Use `enhancement` for feature requests
26
+
- Use `documentation` for documentation improvements
27
+
- Use `question` for general queries
28
+
29
+
### Contributing code
30
+
31
+
To contribute code to the project:
32
+
33
+
1. Fork the repository and clone your fork locally
34
+
2. Create a new branch from `main` with a descriptive name
35
+
3. Review the [customization](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/customization.html), [architecture](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/architecture.html), and [authentication](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/authentication.html) pages for guidance on design patterns and code structure and style
36
+
4. Ensure all tests pass, including `mypy` type checking
37
+
5. Stage, commit, and push your changes to the branch:
38
+
- Use clear, descriptive commit messages
39
+
- Keep commits focused and atomic
40
+
6. Submit your pull request:
41
+
- Provide a clear description of the changes
42
+
- Link to any related issues
43
+
44
+
### Rendering the documentation
45
+
46
+
The README and documentation website are rendered with [Quarto](https://quarto.org/docs/). If you ,make changes to the `.qmd` files in the root folder and the `docs` folder, run the following commands to re-render the docs:
0 commit comments