Skip to content

Commit 5596d8d

Browse files
ArchmongerArchmonger
authored
Django form component (#267)
1 parent c8b4ec0 commit 5596d8d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1664
-29
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,15 @@ Don't forget to remove deprecated code on each major release!
1919

2020
## [Unreleased]
2121

22-
- Nothing (yet)!
22+
### Added
23+
24+
- Automatically convert Django forms to ReactPy forms via the new `reactpy_django.components.django_form` component!
2325

2426
## [5.1.1] - 2024-12-02
2527

2628
### Fixed
2729

28-
- Fixed regression in v5.1.0 where components would sometimes not output debug messages when `settings.py:DEBUG` is enabled.
30+
- Fixed regression from the previous release where components would sometimes not output debug messages when `settings.py:DEBUG` is enabled.
2931

3032
### Changed
3133

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
- [Multiple root components](https://reactive-python.github.io/reactpy-django/latest/reference/template-tag/)
3131
- [Cross-process communication/signaling](https://reactive-python.github.io/reactpy-django/latest/reference/hooks/#use-channel-layer)
3232
- [Django view to ReactPy component conversion](https://reactive-python.github.io/reactpy-django/latest/reference/components/#view-to-component)
33+
- [Django form to ReactPy component conversion](https://reactive-python.github.io/reactpy-django/latest/reference/components/#django-form)
3334
- [Django static file access](https://reactive-python.github.io/reactpy-django/latest/reference/components/#django-css)
3435
- [Django database access](https://reactive-python.github.io/reactpy-django/latest/reference/hooks/#use-query)
3536

‎docs/examples/html/django_form_bootstrap.html

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{% load django_bootstrap5 %}
2+
3+
<!-- Note: CSS/JS is loaded here only for demonstration purposes.
4+
You should load this CSS/JS in your HTML <head> instead. -->
5+
{% bootstrap_css %}
6+
{% bootstrap_javascript %}
7+
8+
<!-- The actual form that is rendered by ReactPy -->
9+
{% bootstrap_form form %}
10+
{% bootstrap_button button_type="submit" content="OK" %}
11+
{% bootstrap_button button_type="reset" content="Reset" %}

‎docs/examples/python/django_form.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
from reactpy import component, html
2+
3+
from example.forms import MyForm
4+
from reactpy_django.components import django_form
5+
6+
7+
@component
8+
def basic_form():
9+
children = [html.input({"type": "submit"})]
10+
return django_form(MyForm, bottom_children=children)

‎docs/examples/python/django_form_bootstrap.py

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
from reactpy import component
2+
3+
from example.forms import MyForm
4+
from reactpy_django.components import django_form
5+
6+
7+
@component
8+
def basic_form():
9+
return django_form(MyForm, form_template="bootstrap_form.html")

‎docs/examples/python/django_form_class.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
from django import forms
2+
3+
4+
class MyForm(forms.Form):
5+
username = forms.CharField(label="Username")

‎docs/examples/python/django_form_on_success.py

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
from reactpy import component, hooks, html
2+
from reactpy_router import navigate
3+
4+
from example.forms import MyForm
5+
from reactpy_django.components import django_form
6+
from reactpy_django.types import FormEventData
7+
8+
9+
@component
10+
def basic_form():
11+
submitted, set_submitted = hooks.use_state(False)
12+
13+
def on_submit(event: FormEventData):
14+
"""This function will be called when the form is successfully submitted."""
15+
set_submitted(True)
16+
17+
if submitted:
18+
return navigate("/homepage")
19+
20+
children = [html.input({"type": "submit"})]
21+
return django_form(MyForm, on_success=on_submit, bottom_children=children)

‎docs/examples/python/example/forms.py

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
from django import forms
2+
3+
4+
class MyForm(forms.Form): ...

‎docs/src/dictionary.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,4 @@ linter
4848
linters
4949
linting
5050
formatters
51+
bootstrap_form

‎docs/src/reference/components.md

Lines changed: 102 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ Compatible with sync or async [Function Based Views](https://docs.djangoproject.
156156

157157
??? info "Existing limitations"
158158

159-
There are currently several limitations of using `#!python view_to_component` that may be resolved in a future version.
159+
There are currently several limitations of using `#!python view_to_component` that will be [resolved in a future version](https://github.com/reactive-python/reactpy-django/issues/269).
160160

161161
- Requires manual intervention to change HTTP methods to anything other than `GET`.
162162
- ReactPy events cannot conveniently be attached to converted view HTML.
@@ -292,12 +292,12 @@ Compatible with sync or async [Function Based Views](https://docs.djangoproject.
292292

293293
??? info "Existing limitations"
294294

295-
There are currently several limitations of using `#!python view_to_iframe` that may be resolved in a future version.
295+
There are currently several limitations of using `#!python view_to_iframe` which may be [resolved in a future version](https://github.com/reactive-python/reactpy-django/issues/268).
296296

297297
- No built-in method of signalling events back to the parent component.
298-
- All provided `#!python *args` and `#!python *kwargs` must be serializable values, since they are encoded into the URL.
298+
- All provided `#!python args` and `#!python kwargs` must be serializable values, since they are encoded into the URL.
299299
- The `#!python iframe` will always load **after** the parent component.
300-
- CSS styling for `#!python iframe` elements tends to be awkward/difficult.
300+
- CSS styling for `#!python iframe` elements tends to be awkward.
301301

302302
??? question "How do I use this for Class Based Views?"
303303

@@ -381,6 +381,104 @@ Compatible with sync or async [Function Based Views](https://docs.djangoproject.
381381

382382
---
383383

384+
## Django Form
385+
386+
Automatically convert a Django form into a ReactPy component.
387+
388+
Compatible with both [standard Django forms](https://docs.djangoproject.com/en/stable/topics/forms/#building-a-form) and [ModelForms](https://docs.djangoproject.com/en/stable/topics/forms/modelforms/).
389+
390+
=== "components.py"
391+
392+
```python
393+
{% include "../../examples/python/django_form.py" %}
394+
```
395+
396+
=== "forms.py"
397+
398+
```python
399+
{% include "../../examples/python/django_form_class.py" %}
400+
```
401+
402+
??? example "See Interface"
403+
404+
<font size="4">**Parameters**</font>
405+
406+
| Name | Type | Description | Default |
407+
| --- | --- | --- | --- |
408+
| `#!python form` | `#!python type[Form | ModelForm]` | The form to convert. | N/A |
409+
| `#!python on_success` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called when the form is successfully submitted. | `#!python None` |
410+
| `#!python on_error` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called when the form submission fails. | `#!python None` |
411+
| `#!python on_receive_data` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called before newly submitted form data is rendered. | `#!python None` |
412+
| `#!python on_change` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called when a form field is modified by the user. | `#!python None` |
413+
| `#!python auto_save` | `#!python bool` | If `#!python True`, the form will automatically call `#!python save` on successful submission of a `#!python ModelForm`. This has no effect on regular `#!python Form` instances. | `#!python True` |
414+
| `#!python extra_props` | `#!python dict[str, Any] | None` | Additional properties to add to the `#!html <form>` element. | `#!python None` |
415+
| `#!python extra_transforms` | `#!python Sequence[Callable[[VdomDict], Any]] | None` | A list of functions that transforms the newly generated VDOM. The functions will be repeatedly called on each VDOM node. | `#!python None` |
416+
| `#!python form_template` | `#!python str | None` | The template to use for the form. If `#!python None`, Django's default template is used. | `#!python None` |
417+
| `#!python thread_sensitive` | `#!python bool` | Whether to run event callback functions in thread sensitive mode. This mode only applies to sync functions, and is turned on by default due to Django ORM limitations. | `#!python True` |
418+
| `#!python top_children` | `#!python Sequence[Any]` | Additional elements to add to the top of the form. | `#!python tuple` |
419+
| `#!python bottom_children` | `#!python Sequence[Any]` | Additional elements to add to the bottom of the form. | `#!python tuple` |
420+
| `#!python key` | `#!python Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings. | `#!python None` |
421+
422+
<font size="4">**Returns**</font>
423+
424+
| Type | Description |
425+
| --- | --- |
426+
| `#!python Component` | A ReactPy component. |
427+
428+
??? info "Existing limitations"
429+
430+
The following fields are currently incompatible with `#!python django_form`: `#!python FileField`, `#!python ImageField`, `#!python SplitDateTimeField`, and `#!python MultiValueField`.
431+
432+
Compatibility for these fields will be [added in a future version](https://github.com/reactive-python/reactpy-django/issues/270).
433+
434+
??? question "How do I style these forms with Bootstrap?"
435+
436+
You can style these forms by using a form styling library. In the example below, it is assumed that you have already installed [`django-bootstrap5`](https://pypi.org/project/django-bootstrap5/).
437+
438+
After installing a form styling library, you can then provide ReactPy a custom `#!python form_template` parameter. This parameter allows you to specify a custom HTML template to use to render this the form.
439+
440+
Note that you can also set a global default for `form_template` by using [`settings.py:REACTPY_DEFAULT_FORM_TEMPLATE`](./settings.md#reactpy_default_form_template).
441+
442+
=== "components.py"
443+
444+
```python
445+
{% include "../../examples/python/django_form_bootstrap.py" %}
446+
```
447+
448+
=== "forms.py"
449+
450+
```python
451+
{% include "../../examples/python/django_form_class.py" %}
452+
```
453+
454+
=== "bootstrap_form.html"
455+
456+
```jinja
457+
{% include "../../examples/html/django_form_bootstrap.html" %}
458+
```
459+
460+
??? question "How do I handle form success/errors?"
461+
462+
You can react to form state by providing a callback function to any of the following parameters: `#!python on_success`, `#!python on_error`, `#!python on_receive_data`, and `#!python on_change`.
463+
464+
These functions will be called when the form is submitted.
465+
466+
In the example below, we will use the `#!python on_success` parameter to change the URL upon successful submission.
467+
468+
=== "components.py"
469+
470+
```python
471+
{% include "../../examples/python/django_form_on_success.py" %}
472+
```
473+
474+
=== "forms.py"
475+
476+
```python
477+
{% include "../../examples/python/django_form_class.py" %}
478+
```
479+
480+
---
481+
384482
## Django CSS
385483

386484
Allows you to defer loading a CSS stylesheet until a component begins rendering. This stylesheet must be stored within [Django's static files](https://docs.djangoproject.com/en/stable/howto/static-files/).

‎docs/src/reference/hooks.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Query functions can be sync or async.
4646
| --- | --- | --- | --- |
4747
| `#!python query` | `#!python Callable[FuncParams, Awaitable[Inferred]] | Callable[FuncParams, Inferred]` | A function that executes a query and returns some data. | N/A |
4848
| `#!python kwargs` | `#!python dict[str, Any] | None` | Keyword arguments to passed into the `#!python query` function. | `#!python None` |
49-
| `#!python thread_sensitive` | `#!python bool` | Whether to run your query function in thread sensitive mode. This mode only applies to sync query functions, and is turned on by default due to Django ORM limitations. | `#!python True` |
49+
| `#!python thread_sensitive` | `#!python bool` | Whether to run your query function in thread sensitive mode. This setting only applies to sync functions, and is turned on by default due to Django ORM limitations. | `#!python True` |
5050
| `#!python postprocessor` | `#!python AsyncPostprocessor | SyncPostprocessor | None` | A callable that processes the query `#!python data` before it is returned. The first argument of postprocessor function must be the query `#!python data`. All proceeding arguments are optional `#!python postprocessor_kwargs`. This postprocessor function must return the modified `#!python data`. | `#!python None` |
5151
| `#!python postprocessor_kwargs` | `#!python dict[str, Any] | None` | Keyworded arguments passed into the `#!python postprocessor` function. | `#!python None` |
5252

@@ -188,7 +188,7 @@ Mutation functions can be sync or async.
188188
| Name | Type | Description | Default |
189189
| --- | --- | --- | --- |
190190
| `#!python mutation` | `#!python Callable[FuncParams, bool | None] | Callable[FuncParams, Awaitable[bool | None]]` | A callable that performs Django ORM create, update, or delete functionality. If this function returns `#!python False`, then your `#!python refetch` function will not be used. | N/A |
191-
| `#!python thread_sensitive` | `#!python bool` | Whether to run the mutation in thread sensitive mode. This mode only applies to sync mutation functions, and is turned on by default due to Django ORM limitations. | `#!python True` |
191+
| `#!python thread_sensitive` | `#!python bool` | Whether to run the mutation in thread sensitive mode. This setting only applies to sync functions, and is turned on by default due to Django ORM limitations. | `#!python True` |
192192
| `#!python refetch` | `#!python Callable[..., Any] | Sequence[Callable[..., Any]] | None` | A query function (the function you provide to your `#!python use_query` hook) or a sequence of query functions that need a `#!python refetch` if the mutation succeeds. This is useful for refreshing data after a mutation has been performed. | `#!python None` |
193193

194194
<font size="4">**Returns**</font>

‎docs/src/reference/settings.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ The prefix used for all ReactPy WebSocket and HTTP URLs.
3434

3535
**Example Value(s):** `#!python "example_project.postprocessor"`, `#!python None`
3636

37-
Dotted path to the default `#!python reactpy_django.hooks.use_query` postprocessor function.
37+
Dotted path to the default postprocessor function used by the [`use_query`](./hooks.md#use-query) hook.
3838

3939
Postprocessor functions can be async or sync. Here is an example of a sync postprocessor function:
4040

@@ -48,6 +48,18 @@ Set `#!python REACTPY_DEFAULT_QUERY_POSTPROCESSOR` to `#!python None` to disable
4848

4949
---
5050

51+
### `#!python REACTPY_DEFAULT_FORM_TEMPLATE`
52+
53+
**Default:** `#!python None`
54+
55+
**Example Value(s):** `#!python "my_templates/bootstrap_form.html"`
56+
57+
File path to the default form template used by the [`django_form`](./components.md#django-form) component.
58+
59+
This file path must be valid to Django's [template finder](https://docs.djangoproject.com/en/stable/topics/templates/#support-for-template-engines).
60+
61+
---
62+
5163
### `#!python REACTPY_AUTH_BACKEND`
5264

5365
**Default:** `#!python "django.contrib.auth.backends.ModelBackend"`
@@ -131,7 +143,7 @@ This setting is incompatible with [`daphne`](https://github.com/django/daphne).
131143

132144
Configures whether to use an async ReactPy rendering queue. When enabled, large renders will no longer block smaller renders from taking place. Additionally, prevents the rendering queue from being blocked on waiting for async effects to startup/shutdown (which is typically a relatively slow operation).
133145

134-
This setting is currently experimental, and currently no effort is made to de-duplicate renders. For example, if parent and child components are scheduled to render at the same time, both renders will take place even though a single render of the parent component would have been sufficient.
146+
This setting is currently in early release, and currently no effort is made to de-duplicate renders. For example, if parent and child components are scheduled to render at the same time, both renders will take place even though a single render of the parent component would have been sufficient.
135147

136148
---
137149

‎pyproject.toml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@ extra-dependencies = [
9494
"twisted",
9595
"tblib",
9696
"servestatic",
97+
"django-bootstrap5",
9798
]
9899
matrix-name-format = "{variable}-{value}"
99100

@@ -140,7 +141,12 @@ pythonpath = [".", "tests/"]
140141
################################
141142

142143
[tool.hatch.envs.django]
143-
extra-dependencies = ["channels[daphne]>=4.0.0", "twisted", "servestatic"]
144+
extra-dependencies = [
145+
"channels[daphne]>=4.0.0",
146+
"twisted",
147+
"servestatic",
148+
"django-bootstrap5",
149+
]
144150

145151
[tool.hatch.envs.django.scripts]
146152
runserver = [

‎src/js/src/index.tsx

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,21 @@ import { ReactPyDjangoClient } from "./client";
22
import React from "react";
33
import ReactDOM from "react-dom";
44
import { Layout } from "@reactpy/client/src/components";
5+
import { DjangoFormProps } from "./types";
6+
7+
/**
8+
* Interface used to bind a ReactPy node to React.
9+
*/
10+
export function bind(node) {
11+
return {
12+
create: (type, props, children) =>
13+
React.createElement(type, props, ...children),
14+
render: (element) => {
15+
ReactDOM.render(element, node);
16+
},
17+
unmount: () => ReactDOM.unmountComponentAtNode(node),
18+
};
19+
}
520

621
export function mountComponent(
722
mountElement: HTMLElement,
@@ -79,3 +94,51 @@ export function mountComponent(
7994
// Start rendering the component
8095
ReactDOM.render(<Layout client={client} />, client.mountElement);
8196
}
97+
98+
export function DjangoForm({
99+
onSubmitCallback,
100+
formId,
101+
}: DjangoFormProps): null {
102+
React.useEffect(() => {
103+
const form = document.getElementById(formId) as HTMLFormElement;
104+
105+
// Submission event function
106+
const onSubmitEvent = (event) => {
107+
event.preventDefault();
108+
const formData = new FormData(form);
109+
110+
// Convert the FormData object to a plain object by iterating through it
111+
// If duplicate keys are present, convert the value into an array of values
112+
const entries = formData.entries();
113+
const formDataArray = Array.from(entries);
114+
const formDataObject = formDataArray.reduce((acc, [key, value]) => {
115+
if (acc[key]) {
116+
if (Array.isArray(acc[key])) {
117+
acc[key].push(value);
118+
} else {
119+
acc[key] = [acc[key], value];
120+
}
121+
} else {
122+
acc[key] = value;
123+
}
124+
return acc;
125+
}, {});
126+
127+
onSubmitCallback(formDataObject);
128+
};
129+
130+
// Bind the event listener
131+
if (form) {
132+
form.addEventListener("submit", onSubmitEvent);
133+
}
134+
135+
// Unbind the event listener when the component dismounts
136+
return () => {
137+
if (form) {
138+
form.removeEventListener("submit", onSubmitEvent);
139+
}
140+
};
141+
}, []);
142+
143+
return null;
144+
}

‎src/js/src/types.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,8 @@ export type ReactPyDjangoClientProps = {
1818
prerenderElement: HTMLElement | null;
1919
offlineElement: HTMLElement | null;
2020
};
21+
22+
export interface DjangoFormProps {
23+
onSubmitCallback: (data: Object) => void;
24+
formId: string;
25+
}

0 commit comments

Comments
 (0)