component and template tag docs

Archmonger · Archmonger · commit 53c0499bb2fd · 2024-06-21T20:04:17.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -34,13 +34,19 @@ Using the following categories, list your changes in this order:
 
 ## [Unreleased]
 
+### Added
+
+-   Client-side Python components can now be rendered via the new `pyscript_component` template tag
+-   Client-side components can be embedded into existing server-side components via `reactpy_django.components.pyscript_component`.
+-   You can now write Python code that runs within client browser via the `reactpy_django.html.pyscript` element. This is a viable substitution for most JavaScript code.
+
 ### Changed
 
 -   New syntax for `use_query` and `use_mutation` hooks. Here's a quick comparison of the changes:
 
     ```python
-    query = use_query(QueryOptions(thread_sensitive=True), get_items, value=123456, foo="bar") # Old
-    query = use_query(get_items, {"value":12356, "foo":"bar"}, thread_sensitive=True) # New
+    query = use_query(QueryOptions(thread_sensitive=True), get_items, foo="bar") # Old
+    query = use_query(get_items, {"foo":"bar"}, thread_sensitive=True) # New
 
     mutation = use_mutation(MutationOptions(thread_sensitive=True), remove_item) # Old
     mutation = use_mutation(remove_item, thread_sensitive=True) # New
@@ -50,6 +56,10 @@ Using the following categories, list your changes in this order:
 
 -   `QueryOptions` and `MutationOptions` have been removed. Their values are now passed direct into the hook.
 
+### Fixed
+
+-   Resolved a bug where Django-ReactPy would not properly detect `settings.py:DEBUG`.
+
 ## [3.8.1] - 2024-05-07
 
 ### Added
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# <img src="https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg" align="left" height="45"/> ReactPy Django
+# <img src="https://raw.githubusercontent.com/reactive-python/reactpy/main/branding/svg/reactpy-logo-square.svg" align="left" height="45"/> ReactPy-Django
 
 <p>
     <a href="https://github.com/reactive-python/reactpy-django/actions?query=workflow%3ATest">
@@ -21,6 +21,7 @@
 [ReactPy-Django](https://github.com/reactive-python/reactpy-django) is used to add [ReactPy](https://reactpy.dev/) support to an existing **Django project**. This package also turbocharges ReactPy with features such as...
 
 -   [SEO compatible rendering](https://reactive-python.github.io/reactpy-django/latest/reference/settings/#reactpy_prerender)
+-   [Client-Side Python components](https://reactive-python.github.io/reactpy-django/latest/reference/template-tag/#pyscript-component)
 -   [Single page application (SPA) capabilities](https://reactive-python.github.io/reactpy-django/latest/reference/router/#django-router)
 -   [Distributed computing](https://reactive-python.github.io/reactpy-django/latest/reference/settings/#reactpy_default_hosts)
 -   [Performance enhancements](https://reactive-python.github.io/reactpy-django/latest/reference/settings/#performance-settings)
@@ -82,7 +83,7 @@ def hello_world(recipient: str):
 
 <!--py-code-end-->
 
-## [`my_app/templates/my-template.html`](https://docs.djangoproject.com/en/dev/topics/templates/)
+## [`my_app/templates/my_template.html`](https://docs.djangoproject.com/en/dev/topics/templates/)
 
 <!--html-header-start-->
 
diff --git a/docs/examples/html/pyscript-component.html b/docs/examples/html/pyscript-component.html
@@ -0,0 +1,14 @@
+{% load reactpy %}
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup %}
+</head>
+
+<body>
+    {% pyscript_component "./example_project/my_app/components/hello_world.py" %}
+</body>
+
+</html>
diff --git a/docs/examples/html/pyscript-initial-object.html b/docs/examples/html/pyscript-initial-object.html
@@ -0,0 +1,3 @@
+<body>
+    {% pyscript_component "./example_project/my_app/components/root.py" initial=my_initial_object %}
+</body>
diff --git a/docs/examples/html/pyscript-initial-string.html b/docs/examples/html/pyscript-initial-string.html
@@ -0,0 +1,3 @@
+<body>
+    {% pyscript_component "./example_project/my_app/components/root.py" initial="<div> Loading ... </div>" %}
+</body>
diff --git a/docs/examples/html/pyscript-multiple-files.html b/docs/examples/html/pyscript-multiple-files.html
@@ -0,0 +1,15 @@
+{% load reactpy %}
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup %}
+</head>
+
+<body>
+    {% pyscript_component "./example_project/my_app/components/root.py"
+    "./example_project/my_app/components/child.py" %}
+</body>
+
+</html>
diff --git a/docs/examples/html/pyscript-root.html b/docs/examples/html/pyscript-root.html
@@ -0,0 +1,3 @@
+<body>
+    {% pyscript_component "./example_project/my_app/components/main.py" root="main" %}
+</body>
diff --git a/docs/examples/html/pyscript-setup-config-object.html b/docs/examples/html/pyscript-setup-config-object.html
@@ -0,0 +1,4 @@
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup config=my_config_object %}
+</head>
diff --git a/docs/examples/html/pyscript-setup-config-string.html b/docs/examples/html/pyscript-setup-config-string.html
@@ -0,0 +1,4 @@
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup config="{'experimental_create_proxy':'auto'}" %}
+</head>
diff --git a/docs/examples/html/pyscript-setup-dependencies.html b/docs/examples/html/pyscript-setup-dependencies.html
@@ -0,0 +1,4 @@
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup "dill==0.3.5" "markdown<=3.6.0" "nest_asyncio" "titlecase" %}
+</head>
diff --git a/docs/examples/html/pyscript-setup.html b/docs/examples/html/pyscript-setup.html
@@ -0,0 +1,6 @@
+{% load reactpy %}
+
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup %}
+</head>
diff --git a/docs/examples/html/pyscript-ssr-parent.html b/docs/examples/html/pyscript-ssr-parent.html
@@ -0,0 +1,14 @@
+{% load reactpy %}
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>ReactPy</title>
+    {% pyscript_setup %}
+</head>
+
+<body>
+    {% component "example_project.my_app.components.server_side_component" %}
+</body>
+
+</html>
diff --git a/docs/examples/python/example/views.py b/docs/examples/python/example/views.py
@@ -2,4 +2,4 @@
 
 
 def index(request):
-    return render(request, "my-template.html")
+    return render(request, "my_template.html")
diff --git a/docs/examples/python/pyscript-component-initial-object.py b/docs/examples/python/pyscript-component-initial-object.py
@@ -0,0 +1,12 @@
+from reactpy import component, html
+from reactpy_django.components import pyscript_component
+
+
+@component
+def server_side_component():
+    return html.div(
+        pyscript_component(
+            "./example_project/my_app/components/root.py",
+            initial=html.div("Loading ..."),
+        ),
+    )
diff --git a/docs/examples/python/pyscript-component-initial-string.py b/docs/examples/python/pyscript-component-initial-string.py
@@ -0,0 +1,12 @@
+from reactpy import component, html
+from reactpy_django.components import pyscript_component
+
+
+@component
+def server_side_component():
+    return html.div(
+        pyscript_component(
+            "./example_project/my_app/components/root.py",
+            initial="<div> Loading ... </div>",
+        ),
+    )
diff --git a/docs/examples/python/pyscript-component-multiple-files-root.py b/docs/examples/python/pyscript-component-multiple-files-root.py
@@ -0,0 +1,12 @@
+from reactpy import component, html
+from reactpy_django.components import pyscript_component
+
+
+@component
+def server_side_component():
+    return html.div(
+        pyscript_component(
+            "./example_project/my_app/components/root.py",
+            "./example_project/my_app/components/child.py",
+        ),
+    )
diff --git a/docs/examples/python/pyscript-component-root.py b/docs/examples/python/pyscript-component-root.py
@@ -0,0 +1,12 @@
+from reactpy import component, html
+from reactpy_django.components import pyscript_component
+
+
+@component
+def server_side_component():
+    return html.div(
+        pyscript_component(
+            "./example_project/my_app/components/main.py",
+            root="main",
+        ),
+    )
diff --git a/docs/examples/python/pyscript-hello-world.py b/docs/examples/python/pyscript-hello-world.py
@@ -0,0 +1,6 @@
+from reactpy import component, html
+
+
+@component
+def root():
+    return html.div("Hello, World!")
diff --git a/docs/examples/python/pyscript-initial-object.py b/docs/examples/python/pyscript-initial-object.py
@@ -0,0 +1,10 @@
+from django.shortcuts import render
+from reactpy import html
+
+
+def index(request):
+    return render(
+        request,
+        "my_template.html",
+        context={"my_initial_object": html.div("Loading ...")},
+    )
diff --git a/docs/examples/python/pyscript-js-execution.py b/docs/examples/python/pyscript-js-execution.py
@@ -0,0 +1,11 @@
+import js
+from reactpy import component, html
+
+
+@component
+def root():
+
+    def onClick(event):
+        js.document.title = "New window title"
+
+    return html.button({"onClick": onClick}, "Click Me!")
diff --git a/docs/examples/python/pyscript-multiple-files-child.py b/docs/examples/python/pyscript-multiple-files-child.py
@@ -0,0 +1,6 @@
+from reactpy import component, html
+
+
+@component
+def child_component():
+    return html.div("This is a child component from a different file.")
diff --git a/docs/examples/python/pyscript-multiple-files-root.py b/docs/examples/python/pyscript-multiple-files-root.py
@@ -0,0 +1,11 @@
+from typing import TYPE_CHECKING
+
+from reactpy import component, html
+
+if TYPE_CHECKING:
+    from .child import child_component
+
+
+@component
+def root():
+    return html.div("This text is from the root component.", child_component())
diff --git a/docs/examples/python/pyscript-root.py b/docs/examples/python/pyscript-root.py
@@ -0,0 +1,6 @@
+from reactpy import component, html
+
+
+@component
+def main():
+    return html.div("Hello, World!")
diff --git a/docs/examples/python/pyscript-setup-config-object.py b/docs/examples/python/pyscript-setup-config-object.py
@@ -0,0 +1,9 @@
+from django.shortcuts import render
+
+
+def index(request):
+    return render(
+        request,
+        "my_template.html",
+        context={"my_config_object": {"experimental_create_proxy": "auto"}},
+    )
diff --git a/docs/examples/python/pyscript-ssr-child.py b/docs/examples/python/pyscript-ssr-child.py
@@ -0,0 +1,6 @@
+from reactpy import component, html
+
+
+@component
+def root():
+    return html.div("This text is from my client-side component")
diff --git a/docs/examples/python/pyscript-ssr-parent.py b/docs/examples/python/pyscript-ssr-parent.py
@@ -0,0 +1,10 @@
+from reactpy import component, html
+from reactpy_django.components import pyscript_component
+
+
+@component
+def server_side_component():
+    return html.div(
+        "This text is from my server-side component",
+        pyscript_component("./example_project/my_app/components/root.py"),
+    )
diff --git a/docs/examples/python/template-tag-bad-view.py b/docs/examples/python/template-tag-bad-view.py
@@ -2,5 +2,8 @@
 
 
 def example_view(request):
-    context_vars = {"my_variable": "example_project.my_app.components.hello_world"}
-    return render(request, "my-template.html", context_vars)
+    return render(
+        request,
+        "my_template.html",
+        context={"my_variable": "example_project.my_app.components.hello_world"},
+    )
diff --git a/docs/src/assets/css/admonition.css b/docs/src/assets/css/admonition.css
diff --git a/docs/src/dictionary.txt b/docs/src/dictionary.txt
diff --git a/docs/src/learn/add-reactpy-to-a-django-project.md b/docs/src/learn/add-reactpy-to-a-django-project.md
diff --git a/docs/src/learn/your-first-component.md b/docs/src/learn/your-first-component.md
diff --git a/docs/src/reference/components.md b/docs/src/reference/components.md
diff --git a/docs/src/reference/template-tag.md b/docs/src/reference/template-tag.md
diff --git a/docs/src/reference/utils.md b/docs/src/reference/utils.md
diff --git a/src/reactpy_django/components.py b/src/reactpy_django/components.py
diff --git a/src/reactpy_django/pyscript/component_template.py b/src/reactpy_django/pyscript/component_template.py
diff --git a/src/reactpy_django/templatetags/reactpy.py b/src/reactpy_django/templatetags/reactpy.py
diff --git a/src/reactpy_django/utils.py b/src/reactpy_django/utils.py
diff --git a/tests/test_app/pyscript/components/server_side.py b/tests/test_app/pyscript/components/server_side.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+<body>`
	`2`	`+ {% pyscript_component "./example_project/my_app/components/root.py" initial=my_initial_object %}`
	`3`	`+</body>`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +<head>
 +    <title>ReactPy</title>
 +    {% pyscript_setup config=my_config_object %}
 +</head>