Wwhy

Recipes

Small pages that do real work.

Each recipe is a file or two, not a project. They assume a Gradle project with the io.github.slayyyyer.why plugin, pages under src/why, and ./gradlew whyRun serving them; see install if you have not started one yet.

01

Hello, file

a page with no sections · the URL is the filename

Put a plain HTML file in the site folder. A file with no imports:, controller: or view: labels is all view.

src/why/hello.why
<h1>Hello from a file</h1>
<p>No build step, no route table.</p>

Open /hello (or /hello.why). There is no registration step; the file is the route.

02

A shared layout

imports · partials · import-only files

A leading underscore makes a file importable but not reachable. Use it for chrome you never want to serve on its own.

src/why/_header.why
view:
<header class="site">
  <strong>My site</strong>
  <nav>
    <a href="/">home</a>
    <a href="/about">about</a>
  </nav>
</header>
src/why/index.why
imports:
_header

view:
{{> _header}}
<h1>Home</h1>
<p>The header is a file, not a component.</p>

/_header and /_header.why both answer 404; {{> _header}} still works. Imports are transitive, so a header can import its own footer.

03

A list from SQLite

schema.sql · db.query · each/else

Drop a schema next to the pages. It runs once, when the database file does not exist.

src/why/schema.sql
create table if not exists notes (
  id integer primary key,
  body text not null,
  created_at text not null
);
src/why/notes.why
imports:
_header

controller:
notes = db.query("select * from notes order by id desc")

view:
{{> _header}}
<h1>Notes</h1>
{{#each notes}}
  <article>
    <p>{{it.body}}</p>
    <p class="meta">{{it.created_at}}</p>
  </article>
{{else}}
  <p>No notes yet.</p>
{{/each}}

Rows are hashes keyed by column label, so {{it.body}} works. The query returns a list; {{else}} handles the empty case.

04

A query parameter

params · db.get · escaped output

Query parameters are strings. Bind one into a prepared statement; never concatenate it into SQL.

src/why/post.why
controller:
post = db.get("select * from posts where id = ?", params.id)

view:
<h1>{{post.title}}</h1>
{{{post.body}}}

/post?id=3 gives params.id == "3". {{post.title}} is escaped; {{{post.body}}} is raw. Only use the raw form for content you trust.

05

A guestbook

POST · bound insert · flash · redirect

One page reads and writes. The POST branch validates, inserts, queues a one-shot notice, and redirects; the GET renders the list and the form.

src/why/schema.sql (add)
create table if not exists guestbook (
  id integer primary key,
  name text not null,
  message text not null,
  created_at text not null
);
src/why/guestbook.why
imports:
_header

controller:
if request.method == "POST"
  name = form.name.strip
  message = form.message.strip
  if name != "" and message != ""
    db.exec("insert into guestbook (name, message, created_at) values (?, ?, datetime('now'))", name, message)
    flash.set("notice", "Thanks — your note is in the book.")
    redirect("/guestbook")
  end
end

entries = db.query("select * from guestbook order by id desc limit 50")
title = "Guestbook"

view:
{{> _header}}
<h1>{{title}}</h1>
{{#if flash.notice}}<p class="note">{{flash.notice}}</p>{{/if}}

<form method="post" action="/guestbook">
  <label>Name <input name="name" maxlength="60" required></label>
  <label>Message <textarea name="message" rows="3" maxlength="500" required></textarea></label>
  <button type="submit">Sign the guestbook</button>
</form>

{{#each entries}}
  <article>
    <p class="meta"><strong>{{it.name}}</strong> · {{it.created_at}}</p>
    <p>{{it.message}}</p>
  </article>
{{else}}
  <p>No entries yet. Be the first.</p>
{{/each}}

The flash is keyed by a why_session cookie, shown on the next page request, and then gone. Empty fields fall through silently — the demo's validation is deliberately minimal.

06

Check in CI

why check · GitHub Actions

why check parses and checks every page and exits 1 on problems, so it drops into a workflow with no extra plugin.

.github/workflows/check.yml
name: check
on:
  push:
  pull_request:

jobs:
  why:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "21"
      - run: ./gradlew whyCheck

That is the whole check: no server, no database, no port. whyCheck reports imports, partials, duplicate defs, undefined free-function calls and URL collisions, then prints a page map. It also runs as part of ./gradlew check.


More detail lives in Using Why. The demo site in the repository is the full version of the guestbook recipe.