more smithing

reactive-python · Archmonger · May 31, 2022 · Apr 17, 2022 · Apr 17, 2022 · Apr 17, 2022
commit 5d924d38dd7f631f784e4111132df0c00eee678b
@@ -3,7 +3,6 @@
 # Django IDOM &middot; [![Tests](https://github.com/idom-team/django-idom/workflows/Test/badge.svg?event=push)](https://github.com/idom-team/django-idom/actions?query=workflow%3ATest) [![PyPI Version](https://img.shields.io/pypi/v/django-idom.svg)](https://pypi.python.org/pypi/django-idom) [![License](https://img.shields.io/badge/License-MIT-purple.svg)](https://github.com/idom-team/django-idom/blob/main/LICENSE)
 
 <!--header-end-->
-
 <!--intro-start-->
 
 IDOM is a Python micro-framework that links your web framework of choice to a ReactJS frontend, allowing you to create **interactive websites without needing JavaScript!**
@@ -50,7 +49,7 @@ def HelloComponent(recipient: str):
 
 In your **Django app**'s HTML located within your `templates` folder, you can now embed your IDOM component using the `component` template tag. Within this tag, you will need to type in your dotted path to the component function as the first argument.
 
-Additonally, you can pass in keyworded arguments into your component function. For example, pay attention to how the function definition for HelloComponent (_in the previous example_) accepts a 'recipient' argument.
+Additonally, you can pass in keyword arguments into your component function. For example, pay attention to how the function definition for HelloComponent (_in the previous example_) accepts a 'recipient' argument.
 
 <!--html-header-end-->
 <!--html-code-start-->

diff --git a/docs/django/templatetag.md b/docs/django/templatetag.md
@@ -1,43 +1,60 @@
-Integrated within Django IDOM, we bundle a template tag. Within this tag, you can pass in keyworded parameters directly into your component.
+Integrated within Django IDOM, we bundle a template tag. Within this tag, you can pass in keyword arguments directly into your component.
 
-```jinja title="my-template.html"
-{% load idom %}
-<!DOCTYPE html>
-<html>
-  <body>
-    {% component "example.components.HelloComponent" recipient="World" %}
-  </body>
-</html>
-```
+{% include-markdown "../../README.md" start="<!--html-code-start-->" end="<!--html-code-end-->" %}
 
-<!--q-multiple-components-start-->
+<!--context-start-->
 
-??? question "Can I use multiple components on one page?"
+??? warning "Do not use context variables for the IDOM component name"
 
-    You can add as many components to a webpage as needed by using the template tag multiple times. Retrofitting legacy sites to use reactive components will typically involve many components on one page.
+       Our pre-processor relies on the template tag containing a string.
 
-    But keep in mind, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one central component within your body tag as shown below.
+       **Do not** use Django context variables for the component path. For example, **do not** do the following:
+
+       ```python title="views.py"
+       def example_view():
+              context = {"MyVariable": "example_project.my_app.components.HelloComponent"}
+              return render(request, "my-template.html", context)
+       ```
+
+       ```jinja title="my-template.html"
+       ...
+       {% component MyVariable recipient="World" %}
+       ...
+       ```
+
+       Failure to follow this warning will result in a performance penalty and jankiness when using the Django autoreloader.
+
+<!--context-end-->
+<!--kwarg-start-->
 
-<!--q-multiple-components-end-->
-<!--q-kwargs-start-->
+??? info "Reserved keyword arguments: `class` and `key`"
 
-??? question "Can I use positional arguments instead of keyworded arguments?"
+    For this template tag, there are two reserved keyword arguments: `class` and `key`
 
-       You can only pass in **keyworded arguments** within the template tag. Due to technical limitations, **positional arguments** are not supported at this time.
+    -   `class` allows you to apply a HTML class to the top-level component div. This is useful for styling purposes.
+    -   `key` allows you to force the component to use a [specific key value](https://idom-docs.herokuapp.com/docs/guides/understanding-idom/why-idom-needs-keys.html?highlight=key). You typically won't need to set this.
 
-       Also, be mindful of [reserved keywords](../django/templatetag.md).
+    ```jinja title="my-template.html"
+    ...
+    {% component "example.components.MyComponent" class="my-html-class" key=123 %}
+    ...
+    ```
+
+<!--kwarg-end-->
+<!--multiple-components-start-->
+
+??? question "Can I use multiple components on one page?"
+
+    You can add as many components to a webpage as needed by using the template tag multiple times. Retrofitting legacy sites to use reactive components will typically involve many components on one page.
+
+    But keep in mind, in scenarios where you are trying to create a Single Page Application (SPA) within Django, you will only have one central component within your body tag as shown below.
 
-<!--q-kwargs-end-->
+<!--multiple-components-end-->
+<!--kwargs-start-->
 
----
+??? question "Can I use positional arguments instead of keyword arguments?"
 
-For this template tag, there are only two reserved parameters: `class` and `key`
+       You can only pass in **keyword arguments** within the template tag. Due to technical limitations, **positional arguments** are not supported at this time.
 
--   `class` allows you to apply a HTML class to the top-level component div. This is useful for styling purposes.
--   `key` allows you to force the component to use a [specific key value](https://idom-docs.herokuapp.com/docs/guides/understanding-idom/why-idom-needs-keys.html?highlight=key). You typically won't need to set this.
 
-```jinja title="my-template.html"
-...
-{% component "example.components.MyComponent" class="my-html-class" key=123 %}
-...
-```
+<!--kwargs-end-->
diff --git a/docs/how-to-use/create-component.md b/docs/how-to-use/create-component.md
@@ -5,13 +5,12 @@
 ---
 
 {% include-markdown "../../README.md" start="<!--py-header-start-->" end="<!--py-header-end-->" %}
-
 {% include-markdown "../../README.md" start="<!--py-code-start-->" end="<!--py-code-end-->" %}
 
-??? question "What do I name my component files and functions?"
+??? question "What do I name my IDOM files and functions?"
 
-      You can have full freedom in where you name or place your files/functions within IDOM.
+      You have full freedom in naming/placement of your files and functions.
 
       You should determine the best way to sort your Python modules and component functions to fit your needs.
 
-      Ultimately, components are referenced by Python dotted path in `my-template.html`. So, at minimum this path needs to be valid to Python's `importlib`.
+      Ultimately, components are referenced by Python dotted path in `my-template.html` (_see next step_). So, at minimum this path needs to be valid to Python's `importlib`.
diff --git a/docs/how-to-use/initial-steps.md b/docs/how-to-use/initial-steps.md
@@ -6,16 +6,14 @@
 
 If you've reached this point, you should have already [installed Django-IDOM](../installation/index.md) through the previous steps.
 
-Django provides you high flexibility on where your apps can reside.
+For the examples within this section, we will assume you've placed the files [generated by `startapp`](https://docs.djangoproject.com/en/dev/intro/tutorial01/#creating-the-polls-app) directly into your **Django project** folder. This is common for small projects.
 
-However, for the examples within this section we will assume you've placed the files [generated by `startapp`](https://docs.djangoproject.com/en/dev/intro/tutorial01/#creating-the-polls-app) directly into your **Django project** folder. This is common for small projects.
-
-??? Info "Starting from scratch"
+??? question "I've never used Django, what do I do now?"
 
       {% include-markdown "../installation/index.md" start="<!--dj-proj-start-->" end="<!--dj-proj-end-->" %}
 
       Afterwards, make sure to follow the [Django-IDOM installation instructions](../installation/index.md).
 
 ??? question "How do I organize my Django project for IDOM?"
 
-      Django-IDOM has no requirements on file structure. Organize everything as you wish, just like any other Django project.
+      Django-IDOM has no project structure requirements. Organize everything as you wish, just like any Django project.
diff --git a/docs/how-to-use/learn-more.md b/docs/how-to-use/learn-more.md
@@ -4,6 +4,6 @@ If you followed the previous steps, you've now created a "Hello World" component
 
 The docs you are reading only covers our Django integration.
 
-Check out the [IDOM Core Documentation](https://idom-docs.herokuapp.com/docs/guides/creating-interfaces/index.html) to learn more about our advanced features, such as adding interactivity through events and hooks!
+To learn more about our advanced features, such as interactive events and hooks, check out the [IDOM Core Documentation](https://idom-docs.herokuapp.com/docs/guides/creating-interfaces/index.html)!
 
 [Learn More](https://idom-docs.herokuapp.com/docs/guides/creating-interfaces/index.html){ .md-button .md-button--primary}
diff --git a/docs/how-to-use/reference-component.md b/docs/how-to-use/reference-component.md
@@ -1,16 +1,15 @@
 ???+ summary
 
-       Use our template tag in your HTML.
+       Decide where the component will be displayed by using our template tag.
 
 ---
 
 {% include-markdown "../../README.md" start="<!--html-header-start-->" end="<!--html-header-end-->" %}
-
 {% include-markdown "../../README.md" start="<!--html-code-start-->" end="<!--html-code-end-->" %}
-
-{% include-markdown "../django/templatetag.md" start="<!--q-multiple-components-start-->" end="<!--q-multiple-components-end-->" %}
-
-{% include-markdown "../django/templatetag.md" start="<!--q-kwargs-start-->" end="<!--q-kwargs-end-->" %}
+{% include-markdown "../django/templatetag.md" start="<!--context-start-->" end="<!--context-end-->" %}
+{% include-markdown "../django/templatetag.md" start="<!--kwarg-start-->" end="<!--kwarg-end-->" %}
+{% include-markdown "../django/templatetag.md" start="<!--multiple-components-start-->" end="<!--multiple-components-end-->" %}
+{% include-markdown "../django/templatetag.md" start="<!--kwargs-start-->" end="<!--kwargs-end-->" %}
 
 ??? question "Where is my templates folder?"
 

diff --git a/docs/how-to-use/render-component.md → docs/how-to-use/render-view.md b/docs/how-to-use/render-component.md → docs/how-to-use/render-view.md
@@ -1,6 +1,6 @@
 ???+ summary
 
-    Render the template with a view.
+    Select your template containing an IDOM component, and render it using a Django view.
 
 ---
 

@@ -6,6 +6,10 @@ hide:
 
 {% include-markdown "../README.md" start="<!--header-start-->" end="<!--header-end-->" %}
 
+## It's React for Django Developers.
+
+---
+
 {% include-markdown "../README.md" start="<!--intro-start-->" end="<!--intro-end-->" %}
 
 ## Resources

@@ -1,6 +1,6 @@
 <!--dj-proj-start-->
 
-We are going to assume you have created [a basic **Django project**](https://docs.djangoproject.com/en/dev/intro/tutorial01/), which also involves generating/installing at least one **Django app**. If not, check out this [9 minute video tutorial](https://www.youtube.com/watch?v=ZsJRXS_vrw0) created by _IDG TECHtalk_.
+These docs assumes you have created [a basic **Django project**](https://docs.djangoproject.com/en/dev/intro/tutorial01/), which also involves generating/installing at least one **Django app**. If not, check out this [9 minute YouTube tutorial](https://www.youtube.com/watch?v=ZsJRXS_vrw0) created by _IDG TECHtalk_.
 
 <!--dj-proj-end-->
 

@@ -5,8 +5,8 @@ nav:
     - How to Use:
           - 1. Initial Steps: how-to-use/initial-steps.md
           - 2. Create a Component: how-to-use/create-component.md
-          - 3. Reference Your Component: how-to-use/reference-component.md
-          - 4. Render Your Component: how-to-use/render-component.md
+          - 3. Use the Template Tag: how-to-use/reference-component.md
+          - 4. Render Your View: how-to-use/render-view.md
           - 5. Learn More: how-to-use/learn-more.md
     - Django-Only Features:
           - Hooks: django/hooks.md

@@ -37,6 +37,7 @@ def _register_component(full_component_name: str) -> None:
         ) from error
 
     IDOM_REGISTERED_COMPONENTS[full_component_name] = component
+    _logger.debug("IDOM has registered component %s", full_component_name)
 
 
 class ComponentPreloader:
@@ -118,8 +119,8 @@ def _register_components(self, components: Set) -> None:
 
         for component in components:
             try:
+                _logger.info("IDOM preloader has detected component %s", component)
                 _register_component(component)
-                _logger.info("IDOM has registered component %s", component)
             except Exception:
                 _logger.exception(
                     "IDOM failed to register component %s! This component path may not be valid, or an error may have occurred while importing.",