06: Examples with routes and templates.

pauleveritt · pauleveritt · commit fcb80ce44490 · 2022-09-13T15:05:36.000-04:00
diff --git a/docs/building/examples_template.md b/docs/building/examples_template.md
@@ -0,0 +1,110 @@
+# Examples Template
+
+Having a template is pretty slick.
+We'll now do the same for each example, but things are gonna get kinda weird: we need just part of the example's HTML.
+
+## Example Template and Route
+
+We'll start with a test.
+We already have a `TestClient` test at `test_hello_world.test_hello_world`.
+We start by adapting it to the same BeautifulSoup approach we just saw.
+
+Next, an implementation.
+We add a template at `templates/example.jinja2` then make a new `example` view and route in `app.py`.
+By copying the existing view, we get something that works and, with a small test change, passes the tests.
+But it's returning the contents of the home page.
+
+Instead, we:
+- Get the route parameter
+- Read that file
+- Use `beautifulsoup4` to extra the contents of `<main>`
+- Shove that into the template as the context value of `main`
+
+Along the way, we also extract this example's title from the `<title>` in the HTML file.
+We then shove it in as the template context value of `title`.
+
+This leaves out:
+- Everything in the `<head>`, such as...loading PyScript
+- All the `<py-*>` nodes elsewhere in the example's `<body>`
+
+Uhhh...that's kind of dumb.
+Why are we doing that?
+
+## Standalone vs. Integrated vs. Unmanaged
+
+The HTML for an example might appear in a bunch of places:
+
+1. *Standalone*.
+People want to cut-and-paste an example and run it from a `file:///` URL.
+The Contributor might want to start this way. It needs the PyScript JS/CSS and possibly a `<py-config>`.
+2. *Integrated Website*.
+In the website, for the "best" examples, we want everything to fit together well: consistent styling, fast page transitions, using the same PyScript/Pyodide.
+The Gallery should have control of these things, not the examples.
+Let's call those the "integrated" examples, vs. others that need their own control.
+3. *Unmanaged Website*.
+These are examples on the website which need to set their own Pyodide, or not use the Gallery CSS.
+4. *Integrated App*.
+These are when the examples are running in the Gallery Python web app, under Starlette.
+Perhaps the Contributor is browsing the example, perhaps a Coder is running the example via `pipx`.
+Mostly the same as "Integrated Website".
+5. *CI Builds Website*.
+In this case, the example is compiled into a `public` directory and included into the website.
+The example isn't really being executed.
+Rather, it's being assembled into output.
+
+At this point, we're still in "Integrated App".
+The Starlette process wants an "integrated" example, where the CSS/JS/Pyodide is under the `layout.jinja2` control.
+All the "integrated" examples will look and feel consistent.
+
+## Extra PyScript Stuff in Head
+
+With that said, an "integrated" examples might have other static assets to go in the `<head>`: extra CSS, for example.
+We'll add that to our example.
+
+Remember, these examples are "standalone".
+They include the `<link>` and `<script>` pointing to PyScript.
+We don't want *those* -- they come from `layout.jinja2`.
+We *do* want anything else them put in there, with relative links as the targets.
+
+Let's write a failing first for including `hello_world.css`.
+For implementation:
+- Add a slot in `layout.jinja2`
+- Change `example.jinja2` to fill that slot, based on passed in string
+- Pass in a string of all the HTML to include
+- Build that string from a `beautifulsoup` `select`
+
+## Example Template Needs `<py-config>`
+
+We want the HTML for the examples to get a Gallery-managed `<py-config>`.
+But we don't want this in other, non-example pages.
+We'll add an `extra_body` slot in `layout.jinja2`, then fill it from `example.jinja2`.
+
+Starting, of course, with a test.
+
+## Plucking Example Parts
+
+That's good for stuff in the `<head>`.
+But we have a problem in the `<body>`.
+PyScript only allows `<py-script>` as a direct child of `<body>`, so we can't put it in `<main>`.
+We need a policy like this:
+
+- Anything in the example's "UI" (the DOM) goes in `<main>` and gets copied over
+- Any `<py-*>` nodes directly under `<body>` get copied over
+- *Except* `<py-config>`
+- Everything else in `<body>` is left out
+
+We'll write some tests:
+- Ensure only one `<py-config>` with a runtime pointed to our local Pyodide
+- The `<py-script>` is copied over, in the right spot
+- Some tracer `<h6>` that is *outside* of `<main>` is *not* copied over
+
+## QA
+
+`mypy` gave us some trouble at the end, because `beautifulsoup` has some unusual typing.
+We thus moved the `example` view's soup filtering into a standalone function which had a `cast`.
+
+## Future
+
+This is actually pretty neat.
+But the view is doing too much.
+Later, we'll introduce a "resource" concept, kind of like a model, and move the work there.
diff --git a/docs/building/index.md b/docs/building/index.md
@@ -31,4 +31,5 @@ cmd_runner
 playwright
 first_pyscript
 bulma
+examples_template
 ```
diff --git a/src/psc/app.py b/src/psc/app.py
@@ -1,6 +1,8 @@
 """Provide a web server to browse the examples."""
+from http.client import HTTPException
 from pathlib import Path
 
+from bs4 import BeautifulSoup
 from starlette.applications import Starlette
 from starlette.requests import Request
 from starlette.responses import FileResponse
@@ -38,10 +40,63 @@ async def homepage(request: Request) -> _TemplateResponse:
     )
 
 
+async def example(request: Request) -> _TemplateResponse:
+    """Handle an example page."""
+    example_name = request.path_params["example_name"]
+    example_file = HERE / "examples" / example_name / "index.html"
+    example_content = example_file.read_text()
+    soup = BeautifulSoup(example_content, "html5lib")
+
+    # Get the example title from the HTML file
+    title_node = soup.select_one("title")
+    title = title_node.text if title_node else ""
+
+    # Assemble any extra head
+    extra_head_links = [
+        link.prettify()
+        for link in soup.select("head link")
+        if not link.attrs["href"].endswith("pyscript.css")
+        and not link.attrs["href"].endswith("favicon.png")
+    ]
+    extra_head_scripts = [
+        script.prettify()
+        for script in soup.select("head script")
+        if not script.attrs["src"].endswith("pyscript.js")
+    ]
+    extra_head_nodes = extra_head_links + extra_head_scripts
+    extra_head = "\n".join(extra_head_nodes)
+
+    # Assemble the main element
+    main_element = soup.select_one("main")
+    if main_element is None:
+        raise HTTPException("Example file has no <main> element")
+    main = f"<main>{main_element.decode_contents()}</main>"
+
+    # Get any non-py-config PyScript nodes
+    pyscript_nodes = [
+        pyscript.prettify()
+        for pyscript in soup.select("body > *")
+        if pyscript.name.startswith("py-") and pyscript.name != "py-config"
+    ]
+    extra_pyscript = "\n".join(pyscript_nodes)
+
+    return templates.TemplateResponse(
+        "example.jinja2",
+        dict(
+            title=title,
+            extra_head=extra_head,
+            main=main,
+            extra_pyscript=extra_pyscript,
+            request=request,
+        ),
+    )
+
+
 routes = [
     Route("/", homepage),
     Route("/index.html", homepage),
     Route("/favicon.png", favicon),
+    Route("/examples/{example_name}/index.html", example),
     Mount("/examples", StaticFiles(directory=HERE / "examples")),
     Mount("/static", StaticFiles(directory=STATIC)),
     Mount("/pyscript", StaticFiles(directory=PYSCRIPT)),
diff --git a/src/psc/examples/hello_world/hello_world.css b/src/psc/examples/hello_world/hello_world.css
@@ -0,0 +1,2 @@
+h1 {
+}
diff --git a/src/psc/examples/hello_world/hello_world.js b/src/psc/examples/hello_world/hello_world.js
@@ -0,0 +1 @@
+/* Stuff here */
diff --git a/src/psc/examples/hello_world/index.html b/src/psc/examples/hello_world/index.html
@@ -5,27 +5,34 @@
 
 <!DOCTYPE html>
 <html lang="en">
-<head>
-    <meta charset="utf-8"/>
-    <meta name="viewport" content="width=device-width,initial-scale=1"/>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
 
-    <title>PyScript Hello World</title>
+    <title>Hello World</title>
 
-    <link rel="icon" type="image/png" href="../../favicon.png"/>
-    <script defer src="../../pyscript/pyscript.js"></script>
-</head>
+    <link rel="icon" type="image/png" href="../../favicon.png">
+    <link rel="stylesheet" href="../../static/pyscript.css">
+    <script defer src="../../static/pyscript.js"></script>
+    <link rel="stylesheet" href="hello_world.css">
+    <script defer src="hello_world.js"></script>
+  </head>
 
 <body>
 <py-config>
-- autoclose_loader: true
-  runtimes:
+autoclose_loader: true
+runtimes:
     - src: "../../pyodide/pyodide.js"
       name: pyodide-0.20
       lang: python
 </py-config>
-<div>Hello...</div>
+<main>
+    <h1>Hello ...</h1>
+    <div id="output"></div>
+</main>
+<h6>More Info</h6>
 <py-script>
-    print("<div>...world</div>")
+    pyscript.write("output", "...world")
 </py-script>
 </body>
 </html>
diff --git a/src/psc/templates/example.jinja2 b/src/psc/templates/example.jinja2
@@ -0,0 +1,17 @@
+{% extends "layout.jinja2" %}
+{% block extra_head %}
+    <script defer src="/pyscript/pyscript.js"></script>
+    {{ extra_head | safe }}{% endblock %}
+{% block extra_body %}
+    <py-config>
+        autoclose_loader: true
+        runtimes:
+        - src: "/static/pyodide.js"
+        name: pyodide-0.20
+        lang: python
+    </py-config>
+    {{ extra_pyscript | safe }}
+{% endblock %}
+{% block main %}
+    {{ main | safe }}
+{% endblock %}
diff --git a/src/psc/templates/layout.jinja2 b/src/psc/templates/layout.jinja2
@@ -6,6 +6,8 @@
     <title>{{ title }} | PyScript Collective</title>
     <link rel="icon" href="/favicon.png">
     <link rel="stylesheet" href="/static/bulma.min.css">
+    {% block extra_head %}
+    {% endblock %}
 </head>
 <body>
 <nav class="navbar is-black" role="navigation" aria-label="main navigation">
@@ -29,6 +31,8 @@
         </div>
     </div>
 </nav>
+{% block extra_body %}
+{% endblock %}
 {% block main %}
 {% endblock %}
 <footer class="footer">
diff --git a/tests/examples/test_hello_world.py b/tests/examples/test_hello_world.py
@@ -9,8 +9,26 @@ def test_hello_world(client_page: PageT) -> None:
     """Test the static HTML for Hello World."""
     soup = client_page("/examples/hello_world/index.html")
     title = soup.select_one("title")
-    if title:
-        assert title.text == "PyScript Hello World"
+    assert title
+    assert title.text == "Hello World | PyScript Collective"
+
+    # See if extra_head got filled, then resolve those
+    assert soup.find_all("link", href="hello_world.css")
+    assert soup.find_all("script", src="hello_world.js")
+
+    # Ensure the ``<main>`` got filled
+    assert soup.select_one("main")
+
+    # Only one <py-config>, pointing to local runtime
+    py_configs = soup.select("py-config")
+    assert len(py_configs) == 1
+
+    # The <py-script> is present
+    py_scripts = soup.select("py-script")
+    assert len(py_scripts) == 1
+
+    # The tracer <h6> is not present
+    assert not soup.select("h6")
 
 
 @pytest.mark.full
