First cut at docs

Archmonger · Archmonger · commit 9c28f97e35dc · 2024-12-08T00:45:59.000-08:00
diff --git a/docs/examples/html/django_form_bootstrap.html b/docs/examples/html/django_form_bootstrap.html
@@ -0,0 +1,11 @@
+{% load django_bootstrap5 %}
+
+<!-- Note: CSS/JS is loaded here only for demonstration purposes.
+You should load this CSS/JS in your HTML <head> instead. -->
+{% bootstrap_css %}
+{% bootstrap_javascript %}
+
+<!-- The actual form that is rendered by ReactPy -->
+{% bootstrap_form form %}
+{% bootstrap_button button_type="submit" content="OK" %}
+{% bootstrap_button button_type="reset" content="Reset" %}
diff --git a/docs/examples/python/django_form.py b/docs/examples/python/django_form.py
@@ -0,0 +1,10 @@
+from reactpy import component, html
+
+from example.forms import MyForm
+from reactpy_django.components import django_form
+
+
+@component
+def basic_form():
+    children = [html.input({"type": "submit"})]
+    return django_form(MyForm, bottom_children=children)
diff --git a/docs/examples/python/django_form_bootstrap.py b/docs/examples/python/django_form_bootstrap.py
@@ -0,0 +1,9 @@
+from reactpy import component
+
+from example.forms import MyForm
+from reactpy_django.components import django_form
+
+
+@component
+def basic_form():
+    return django_form(MyForm, form_template="bootstrap_form.html")
diff --git a/docs/examples/python/django_form_class.py b/docs/examples/python/django_form_class.py
@@ -0,0 +1,5 @@
+from django import forms
+
+
+class MyForm(forms.Form):
+    username = forms.CharField(label="Username")
diff --git a/docs/examples/python/django_form_on_success.py b/docs/examples/python/django_form_on_success.py
@@ -0,0 +1,20 @@
+from reactpy import component, hooks, html
+from reactpy_router import navigate
+
+from example.forms import MyForm
+from reactpy_django.components import django_form
+from reactpy_django.types import FormEventData
+
+
+@component
+def basic_form():
+    success, set_success = hooks.use_state(False)
+
+    def on_success(event: FormEventData):
+        set_success(True)
+
+    if not success:
+        children = [html.input({"type": "submit"})]
+        return django_form(MyForm, on_success=on_success, bottom_children=children)
+
+    return navigate("/homepage")
diff --git a/docs/examples/python/example/forms.py b/docs/examples/python/example/forms.py
@@ -0,0 +1,4 @@
+from django import forms
+
+
+class MyForm(forms.Form): ...
diff --git a/docs/src/dictionary.txt b/docs/src/dictionary.txt
@@ -48,3 +48,4 @@ linter
 linters
 linting
 formatters
+bootstrap_form
diff --git a/docs/src/reference/components.md b/docs/src/reference/components.md
@@ -156,7 +156,7 @@ Compatible with sync or async [Function Based Views](https://docs.djangoproject.
 
 ??? info "Existing limitations"
 
-    There are currently several limitations of using `#!python view_to_component` that may be resolved in a future version.
+    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).
 
     - Requires manual intervention to change HTTP methods to anything other than `GET`.
     - 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.
 
 ??? info "Existing limitations"
 
-    There are currently several limitations of using `#!python view_to_iframe` that may be resolved in a future version.
+    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).
 
     - No built-in method of signalling events back to the parent component.
-    - All provided `#!python *args` and `#!python *kwargs` must be serializable values, since they are encoded into the URL.
+    - All provided `#!python args` and `#!python kwargs` must be serializable values, since they are encoded into the URL.
     - The `#!python iframe` will always load **after** the parent component.
-    - CSS styling for `#!python iframe` elements tends to be awkward/difficult.
+    - CSS styling for `#!python iframe` elements tends to be awkward.
 
 ??? question "How do I use this for Class Based Views?"
 
@@ -381,6 +381,103 @@ Compatible with sync or async [Function Based Views](https://docs.djangoproject.
 
 ---
 
+## Django Form
+
+Automatically convert a Django form into a ReactPy component.
+
+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/).
+
+=== "components.py"
+
+    ```python
+    {% include "../../examples/python/django_form.py" %}
+    ```
+
+=== "forms.py"
+
+    ```python
+    {% include "../../examples/python/django_form_class.py" %}
+    ```
+
+??? example "See Interface"
+
+    <font size="4">**Parameters**</font>
+
+    | Name | Type | Description | Default |
+    | --- | --- | --- | --- |
+    | `#!python form` | `#!python type[Form | ModelForm]` | The form instance to convert. | N/A |
+    | `#!python on_success` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called when the form is successfully submitted. | `#!python None` |
+    | `#!python on_error` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called when the form submission fails. | `#!python None` |
+    | `#!python on_receive_data` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called before newly submitted form data is rendered. | `#!python None` |
+    | `#!python on_change` | `#!python AsyncFormEvent | SyncFormEvent | None` | A callback function that is called when the form is changed. | `#!python None` |
+    | `#!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 False` |
+    | `#!python extra_props` | `#!python dict[str, Any] | None` | Additional properties to add to the `#!html <form>` element. | `#!python None` |
+    | `#!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` |
+    | `#!python form_template` | `#!python str | None` | The template to use for the form. If `#!python None`, Django's default template is used. | `#!python None` |
+    | `#!python top_children` | `#!python Sequence[Any]` | Additional elements to add to the top of the form. | `#!python tuple` |
+    | `#!python bottom_children` | `#!python Sequence[Any]` | Additional elements to add to the bottom of the form. | `#!python tuple` |
+    | `#!python key` | `#!python Key | None` | A key to uniquely identify this component which is unique amongst a component's immediate siblings. | `#!python None` |
+
+    <font size="4">**Returns**</font>
+
+    | Type | Description |
+    | --- | --- |
+    | `#!python Component` | A ReactPy component. |
+
+??? info "Existing limitations"
+
+    The following fields are currently incompatible with `#!python django_form`: `#!python FileField`, `#!python ImageField`, `#!python SplitDateTimeField`, and `#!python MultiValueField`.
+
+    Compatibility for these fields will be [added in a future version](https://github.com/reactive-python/reactpy-django/issues/270).
+
+??? question "How do I style these forms with Bootstrap?"
+
+    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/).
+
+    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.
+
+    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).
+
+    === "components.py"
+
+        ```python
+        {% include "../../examples/python/django_form_bootstrap.py" %}
+        ```
+
+    === "forms.py"
+
+        ```python
+        {% include "../../examples/python/django_form_class.py" %}
+        ```
+
+    === "bootstrap_form.html"
+
+        ```jinja
+        {% include "../../examples/html/django_form_bootstrap.html" %}
+        ```
+
+??? question "How do I handle form success/errors?"
+
+    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`.
+
+    These functions will be called when the form is submitted.
+
+    In the example below, we will use the `#!python on_success` parameter to change the URL upon successful submission.
+
+    === "components.py"
+
+        ```python
+        {% include "../../examples/python/django_form_on_success.py" %}
+        ```
+
+    === "forms.py"
+
+        ```python
+        {% include "../../examples/python/django_form_class.py" %}
+        ```
+
+---
+
 ## Django CSS
 
 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/).
diff --git a/docs/src/reference/settings.md b/docs/src/reference/settings.md
@@ -34,7 +34,7 @@ The prefix used for all ReactPy WebSocket and HTTP URLs.
 
 **Example Value(s):** `#!python "example_project.postprocessor"`, `#!python None`
 
-Dotted path to the default `#!python reactpy_django.hooks.use_query` postprocessor function.
+Dotted path to the default postprocessor function used by the [`use_query`](./hooks.md#use-query) hook.
 
 Postprocessor functions can be async or sync. Here is an example of a sync postprocessor function:
 
@@ -48,6 +48,18 @@ Set `#!python REACTPY_DEFAULT_QUERY_POSTPROCESSOR` to `#!python None` to disable
 
 ---
 
+### `#!python REACTPY_DEFAULT_FORM_TEMPLATE`
+
+**Default:** `#!python None`
+
+**Example Value(s):** `#!python "my_templates/bootstrap_form.html"`
+
+File path to the default form template used by the [`django_form`](./components.md#django-form) component.
+
+This file path must be valid to Django's [template finder](https://docs.djangoproject.com/en/stable/topics/templates/#support-for-template-engines).
+
+---
+
 ### `#!python REACTPY_AUTH_BACKEND`
 
 **Default:** `#!python "django.contrib.auth.backends.ModelBackend"`
@@ -131,7 +143,7 @@ This setting is incompatible with [`daphne`](https://github.com/django/daphne).
 
 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).
 
-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.
+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.
 
 ---
 
