Hook Cleanup (#101)

- Allow `use_mutation` to have `refetch=None`, as the docs suggest is possible. - `use_origin` hook to return the browser's `location.origin` - Fix flaky `test_use_query_and_mutation` test (Key presses require at least 100ms between `keyup`/`keydown` on GH actions) - Logging for `use_mutation`/`use_query` errors (currently silent, which is very hard to debug) - Document `use_mutation`'s `reset()` - Document `use_query` requires a `Model` or `QuerySet` return (due to enforcing no lazy queries) - Document interface on all APIs - Documentation misc cleanup and styling
reactive-python · Oct 14, 2022 · 276f962 · 276f962
1 parent 78823ee
commit 276f962
Show file tree

Hide file tree

Showing 23 changed files with 680 additions and 312 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,7 +22,18 @@ Using the following categories, list your changes in this order:
 
 ## [Unreleased]
 
--   Nothing (Yet)
+### Added
+
+-   `use_origin` hook to return the browser's `location.origin`.
+
+### Changed
+
+-   `use_mutation` and `use_query` will now log any query failures.
+
+### Fixed
+
+-   Allow `use_mutation` to have `refetch=None`, as the docs suggest is possible.
+-   `use_query` will now prefetch all fields to prevent `SynchronousOnlyOperation` exceptions.
 
 ## [1.2.0] - 2022-09-19
 

diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@ You'll need a file to define your [IDOM](https://github.com/idom-team/idom) comp
 <!--py-header-end-->
 <!--py-code-start-->
 
-```python title="components.py"
+```python linenums="1"
 from idom import component, html
 
 @component
@@ -51,7 +51,7 @@ Additonally, you can pass in keyword arguments into your component function. For
 <!--html-header-end-->
 <!--html-code-start-->
 
-```jinja title="my-template.html"
+```jinja linenums="1"
 {% load idom %}
 <!DOCTYPE html>
 <html>

diff --git a/docs/includes/examples.md b/docs/includes/examples.md
@@ -1,6 +1,6 @@
 <!--hello-world-view-start-->
 
-```python
+```python linenums="1"
 from django.http import HttpResponse
 
 def hello_world_view(request, *args, **kwargs):
@@ -11,7 +11,7 @@ def hello_world_view(request, *args, **kwargs):
 
 <!--hello-world-cbv-start-->
 
-```python
+```python linenums="1"
 from django.http import HttpResponse
 from django.views import View
 
@@ -20,4 +20,15 @@ class HelloWorldView(View):
         return HttpResponse("Hello World!")
 ```
 
-<!--hello-world-cbv-end-->
+<!--hello-world-cbv-end-->
+
+<!--todo-model-start-->
+
+```python linenums="1"
+from django.db import models
+
+class TodoItem(models.Model):
+    text = models.CharField(max_length=255)
+```
+
+<!--todo-model-end-->
diff --git a/docs/src/contribute/django-idom.md → docs/src/contribute/code.md b/docs/src/contribute/django-idom.md → docs/src/contribute/code.md
diff --git a/docs/src/features/components.md b/docs/src/features/components.md
@@ -1,10 +1,14 @@
+???+ summary
+
+    Prefabricated components can be used within your `components.py` to help simplify development.
+
 ## View To Component
 
 Convert any Django view into a IDOM component by usng this decorator. Compatible with sync/async [Function Based Views](https://docs.djangoproject.com/en/dev/topics/http/views/) and [Class Based Views](https://docs.djangoproject.com/en/dev/topics/class-based-views/).
 
 === "components.py"
 
-    ```python
+    ```python linenums="1"
     from idom import component, html
     from django_idom.components import view_to_component
     from .views import hello_world_view
@@ -47,7 +51,7 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible
 
     === "components.py"
 
-        ```python
+        ```python linenums="1"
         from idom import component, html
         from django_idom.components import view_to_component
         from .views import HelloWorldView
@@ -69,7 +73,7 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible
 
     === "components.py"
 
-        ```python
+        ```python linenums="1"
         from idom import component, html
         from django_idom.components import view_to_component
         from .views import hello_world_view
@@ -99,7 +103,7 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible
 
     === "components.py"
 
-        ```python
+        ```python linenums="1"
         from idom import component, html
         from django_idom.components import view_to_component
         from .views import hello_world_view
@@ -125,7 +129,7 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible
 
     === "components.py"
 
-        ```python
+        ```python linenums="1"
         from idom import component, html
         from django_idom.components import view_to_component
         from .views import hello_world_view
@@ -153,7 +157,7 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible
 
     === "components.py"
 
-        ```python
+        ```python linenums="1"
         from idom import component, html
         from django_idom.components import view_to_component
         from .views import hello_world_view
@@ -174,7 +178,7 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible
 
     === "views.py"
 
-        ```python
+        ```python linenums="1"
         from django.http import HttpResponse
 
         def hello_world_view(request, *args, **kwargs):
@@ -185,17 +189,33 @@ Convert any Django view into a IDOM component by usng this decorator. Compatible
 
 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/dev/howto/static-files/).
 
-```python title="components.py"
-from idom import component, html
-from django_idom.components import django_css
+=== "components.py"
+
+    ```python linenums="1"
+    from idom import component, html
+    from django_idom.components import django_css
+
+    @component
+    def my_component():
+        return html.div(
+            django_css("css/buttons.css"),
+            html.button("My Button!"),
+        )
+    ```
 
-@component
-def my_component():
-    return html.div(
-        django_css("css/buttons.css"),
-        html.button("My Button!"),
-    )
-```
+??? example "See Interface"
+
+    <font size="4">**Parameters**</font>
+
+    | Name | Type | Description | Default |
+    | --- | --- | --- | --- |
+    | static_path | `str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A |
+
+    <font size="4">**Returns**</font>
+
+    | Type | Description |
+    | --- | --- |
+    | `Component` | An IDOM component. |
 
 ??? question "Should I put `django_css` at the top of my component?"
 
@@ -207,7 +227,7 @@ def my_component():
 
     Here's an example on what you should avoid doing for Django static files:
 
-    ```python
+    ```python linenums="1"
     from idom import component, html
     from django.templatetags.static import static
 
@@ -225,7 +245,7 @@ def my_component():
 
     For external CSS, substitute `django_css` with `html.link`.
 
-    ```python
+    ```python linenums="1"
     from idom import component, html
 
     @component
@@ -246,17 +266,33 @@ def my_component():
 
 Allows you to defer loading JavaScript until a component begins rendering. This JavaScript must be stored within [Django's static files](https://docs.djangoproject.com/en/dev/howto/static-files/).
 
-```python title="components.py"
-from idom import component, html
-from django_idom.components import django_js
+=== "components.py"
+
+    ```python linenums="1"
+    from idom import component, html
+    from django_idom.components import django_js
+
+    @component
+    def my_component():
+        return html.div(
+            html.button("My Button!"),
+            django_js("js/scripts.js"),
+        )
+    ```
 
-@component
-def my_component():
-    return html.div(
-        html.button("My Button!"),
-        django_js("js/scripts.js"),
-    )
-```
+??? example "See Interface"
+
+    <font size="4">**Parameters**</font>
+
+    | Name | Type | Description | Default |
+    | --- | --- | --- | --- |
+    | static_path | `str` | The path to the static file. This path is identical to what you would use on a `static` template tag. | N/A |
+
+    <font size="4">**Returns**</font>
+
+    | Type | Description |
+    | --- | --- |
+    | `Component` | An IDOM component. |
 
 ??? question "Should I put `django_js` at the bottom of my component?"
 
@@ -268,7 +304,7 @@ def my_component():
 
     Here's an example on what you should avoid doing for Django static files:
 
-    ```python
+    ```python linenums="1"
     from idom import component, html
     from django.templatetags.static import static
 
@@ -286,7 +322,7 @@ def my_component():
 
     For external JavaScript, substitute `django_js` with `html.script`.
 
-    ```python
+    ```python linenums="1"
     from idom import component, html
 
     @component