05: Bulma and Jinja2

Author: pauleveritt

docs/building/bulma.md

@@ -0,0 +1,85 @@
+# Bulma and Jinja2
+
+Let's start moving towards the goal of providing attractive examples.
+Each example will appear in several "targets", primarily a website like
+the [existing examples](https://pyscript.net/examples/).
+
+In this step, we'll start building the PSC website.
+We will *not* in this step, though, tackle any concept of a build step, nor anything beyond the homepage.
+
+Big ideas: use off-the-shelf CSS framework, static generation, dead-simple web tech.
+
+## Why Bulma?
+
+We're making a website -- the PyScript Collective.
+But we're also making a web app -- the PyScript Gallery.
+As it turns out, we're also shipping a PyPI package -- the PyScript Gallery, aka `psga`.
+
+We need a nice-looking web app.
+Since we're not designers, let's use a popular, off-the-shelf CSS framework.
+I have experience with (and faith in) [Bulma](https://bulma.io): it's attractive out-of-the-box, mature, and strikes the
+right balance.
+
+## Bring In Bulma
+
+The tests are in good shape and having `beautifulsoup` will prove...beautiful.
+We start with a failing test, one using `BeautifulSoup` to fetch the `link[rel="stylesheet"]` node, then fetch the URL pointed to there.
+
+To make it pass, I:
+
+- Downloaded the bits into static
+- Added a `<link rel="stylesheet" href="/static/bulma.min.css" />` to the home page.
+
+I also added the other parts of the Bulma starter (doctype, meta.)
+If we open it up in the browser, it looks a bit different.
+
+## Navbar and Footer
+
+We'd like a common navbar on all our pages.
+Bulma [has a navbar](https://bulma.io/documentation/components/navbar/).
+This also means a download of the PyScript SVG logo, which we'll write a test for.
+
+Ditto for a -- for now, *very* simple -- [footer component](https://bulma.io/documentation/layout/footer/).
+
+## Body
+
+Bulma makes use of `<section>`, `<footer>`, etc.
+Let's put the "main" part of our page into a `<main class="section">` tag.
+
+For the failing test, we'll simply look to see there is a `<main>`.
+But, as this is no longer a static asset, we'll put this in `test_app.test_homepage`.
+
+## Templating
+
+It sucks to repeat the layout across every static HTML file.
+Let's make some Jinja2 templates, then [setup Starlette](https://www.starlette.io/templates/) to use it the templates.
+
+As precursor, install Jinja2 as a dependency.
+
+We'll start by making a templates directory at `src/psc/templates`.
+In there, we'll make `page.jinja2` and `layout.jinja2`.
+
+In `layout.jinja2`, take everything out that isn't in `<main>`.
+Provide a slot for title and main.
+Then change `page.jinja2` to point at `layout.jinja2`, filling those two slots.
+
+In `app.py`, we change the `homepage` route to return a template.
+The context dictionary for the template will have two pieces of data:
+- The title of the current page
+- The HTML that should go in the main block.
+
+Let's do three things:
+
+- Change `index.html` only have the `<main>` part
+- In the route, read the file content
+- Then pass the file contents into `page.jinja2`, using `| safe`
+
+When done correctly, the tests should pass.
+
+## Future
+
+This PSC prototype just uses downloaded Bulma CSS and other assets.
+It doesn't bring in the SASS customizations and software, nor does it look at Bulma forks that bring in CSS Variables.
+
+While we did a little templating, we didn't go far.
+It's going to get a lot more interesting and intricate, as we have different ways we want to package things.

docs/building/index.md

@@ -30,4 +30,5 @@ proper_package
 cmd_runner
 playwright
 first_pyscript
+bulma
 ```

poetry.lock

@@ -23,6 +23,7 @@ typer = { extras = ["all"], version = "^0.6.1" }
 starlette = "^0.20.4"
 uvicorn = "^0.18.2"
 python-frontmatter = "^1.0.0"
+Jinja2 = "^3.1.2"
 
 [tool.poetry.dev-dependencies]
 Pygments = ">=2.10.0"

pyproject.toml

@@ -1,33 +1,49 @@
 """Provide a web server to browse the examples."""
+from pathlib import Path
 
 from starlette.applications import Starlette
 from starlette.requests import Request
 from starlette.responses import FileResponse
-from starlette.responses import HTMLResponse
 from starlette.routing import Mount
 from starlette.routing import Route
 from starlette.staticfiles import StaticFiles
+from starlette.templating import Jinja2Templates
+from starlette.templating import _TemplateResponse
 
-from .here import HERE, PYSCRIPT
-from .here import PYODIDE
-from .here import STATIC
+from psc.here import PYODIDE
+from psc.here import PYSCRIPT
+from psc.here import STATIC
+
+
+HERE = Path(__file__).parent
+templates = Jinja2Templates(directory=HERE / "templates")
 
 
 async def favicon(request: Request) -> FileResponse:
-    """Route just for serving the favicon."""
+    """Handle the favicon."""
     return FileResponse(HERE / "favicon.png")
 
 
-def index_page(request: Request) -> HTMLResponse:
+async def homepage(request: Request) -> _TemplateResponse:
     """Handle the home page."""
-    return HTMLResponse("<h1>Hello, world!</h1>")
+    index_file = HERE / "index.html"
+
+    return templates.TemplateResponse(
+        "page.jinja2",
+        dict(
+            title="Home Page",
+            main=index_file.read_text(),
+            request=request,
+        ),
+    )
 
 
 routes = [
-    Route("/", index_page),
-    Mount("/static", StaticFiles(directory=STATIC)),
+    Route("/", homepage),
+    Route("/index.html", homepage),
     Route("/favicon.png", favicon),
     Mount("/examples", StaticFiles(directory=HERE / "examples")),
+    Mount("/static", StaticFiles(directory=STATIC)),
     Mount("/pyscript", StaticFiles(directory=PYSCRIPT)),
     Mount("/pyodide", StaticFiles(directory=PYODIDE)),
 ]

src/psc/app.py

@@ -14,8 +14,8 @@
 from requests.models import Response
 from starlette.testclient import TestClient
 
-from psc.here import HERE
 from psc.app import app
+from psc.here import HERE
 
 
 @dataclass

src/psc/fixtures.py

@@ -1,6 +1,7 @@
 """Paths that can be referenced anywhere and get the right target."""
 from pathlib import Path
 
+
 HERE = Path(__file__).parent
 STATIC = HERE / "static"
 PYODIDE = HERE / "pyodide"

src/psc/here.py

@@ -0,0 +1,7 @@
+<main class="section">
+    <h1>PyScript Collective</h1>
+    <h2>Examples</h2>
+    <ul>
+        <li><a href="examples/hello_world/index.html">Hello World</a></li>
+    </ul>
+</main>