Repository navigation
Route Page
Route::page($route, $view, $options) answers a GET with a Pug view, through the framework's page controller. The
page gets its data from read-only capabilities, never from models: the same capabilities REST, the JS client and
AI agents call. Since 2.5.0; visitorsOnly, comeBack and query since 2.20.0, query defaults since 2.21.0.
Route::page('/books/{id}', 'Bookshelf/book', ['data' => ['book' => 'get_book'], 'notFound' => 'Bookshelf/notfound']);/caligrafy-quill:new-capability get_book books:read read-only public: one book with its author, shown at /books/{id}
Claude writes the capability in application/services/<Folder>/, the Route::page line in
application/config/routing/web.php and the Pug view in application/views/.
Check before you say OK:
- the page's
datanames read-only capabilities only; - fixed addresses (
/books/new) are declared before the ones with a variable (/books/{id}); -
/books/abcand/books/999show thenotFoundview with a404, not a500.
Before you start: the Bookshelf tables, the Book model and the capabilities list_books and get_book of
Routing, steps 1 to 3.
-
Declare the pages. In
application/config/routing/web.php, beforeRoute::run();:Route::page('/books', 'Bookshelf/books', ['data' => ['books' => 'list_books']]); Route::page('/books/new', 'Bookshelf/new', ['signedIn' => true, 'comeBack' => true]); Route::page('/books/{id}', 'Bookshelf/book', ['data' => ['book' => 'get_book'], 'notFound' => 'Bookshelf/notfound']);
/books/newcomes before/books/{id}: the first route that matches wins. -
Write the view.
application/views/Bookshelf/books.pugreads$books, the result oflist_books(a page ofpaginate():dataandtotal), as plain arrays:extends ../default/master/site block content section.cq-hero.cq-hero--page h1.cq-display Books section.cq-band.cq-band--tight .cq-inner if $books['total'] == 0 p.cq-empty-state No books yet. else ul.cq-rows each $book in $books['data'] li.cq-row a(href=$home . 'books/' . $book['id'])= $book['title'] span= ' (' . $book['author']['name'] . ', ' . $book['published_year'] . ')'
Pug in Caligrafy is PHP: strings are joined with
., never+. -
Open it.
http://localhost:8080/bookslists the books,/books/3shows one,/books/abcshows thenotFoundview with a404(get_book'sintegerrule refusesabc).
| Option | Default | What it does |
|---|---|---|
data |
none |
name => 'capability': calls each capability as the person who opens the page and gives the result to the view as $name. Its inputs are the query string and the route variables; the route variables win (/books/3?id=9 gives id = 3). name => ['capability', ['author_id' => 2]] gives fixed inputs instead. Only read-only capabilities |
signedIn |
false |
true: visitors are sent to /login
|
level |
0 |
people whose level (the permissions column of users) is lower are sent to /notAuthorized, visitors to /login
|
comeBack |
false |
true, with signedIn or level, or when a data capability needs someone: visitors go to /login?return=<this page, with its query string>, and Route::auth brings them back after signing in (2.20.0) |
visitorsOnly |
none | a path: people already signed in are sent there (a sign-up or landing page) (2.20.0) |
query |
none | what the view gets of the query string: ['show'] gives $show, '' when absent (2.20.0); ['app' => 'index'] gives $app, 'index' when absent (2.21.0). A route variable of the same name wins |
with |
none | fixed values for the view: ['with' => ['title' => 'Books']]
|
notFound |
none | a view shown with a 404 when a data capability refuses (not found, or inputs it refuses). It gets the route variables, the with values, $message, $authorized and $user
|
signedIn, level and visitorsOnly need Auth::authentication('User', 'users'); in web.php; without it, opening
the page stops with an error that says so.
More examples, each one line:
Route::page('/', 'default/index');
Route::page('/admin/books', 'Bookshelf/admin', ['level' => 1, 'data' => ['books' => 'list_books']]);
Route::page('/about', 'default/about', ['with' => ['title' => 'About the Bookshelf']]);
Route::page('/join', 'Bookshelf/join', ['visitorsOnly' => '/books']);
Route::page('/books', 'Bookshelf/books', ['data' => ['books' => 'list_books'], 'query' => ['sort' => 'title']]);
Route::page('/apps/{appName}', 'Client/app', ['query' => ['app' => 'index']]); // a Vue, bot or ML app- the route variables (
$id), the names listed inquery, thewithvalues; - the
dataresults, as plain arrays ($book['title'],$book['author']['name']); -
$authorized(true when someone is signed in) and$user(id,username,permissions, ornull).
The rest of the query string stays out of the view: a data capability gets it as inputs. authorized and user are
reserved names: a data, with or query entry with one of them is an error.
A request with Accept: application/json gets the view's data as JSON instead of the page.
| The capability | The answer |
|---|---|
| needs someone signed in, nobody is | a redirect to /login (comeBack: with ?return=), with the authentication module; else 403
|
refuses the person (forbidden) |
403 [ERROR 1006] Forbidden
|
| finds nothing, or refuses the inputs | the notFound view with 404, else 404 [ERROR 1005] Page Not Found
|
-
Route::page()andRoute::pages()(the pages declared so far, 2.24.0: Snap shows a capability through the page made for it) -
PageController::render(): the controller everyRoute::pagegoes through
-
A page whose data capability writes:
Route::pagerefuses it (opening a page must not change data). UseRoute::formfor writes, orRoute::actionwhen opening an address really has to change something. -
/books/{id}before/books/new:/books/newshows the booknew(a 404). Declare fixed addresses first. -
signedInwithoutAuth::authentication(...)above the page: every visit stops with an error. -
Reading
$_GETin the view: only the names ofqueryreach it. Add the name toquery, or make it an input of thedatacapability. -
A
dataorwithentry nameduserorauthorized: those names are reserved.
- Routing: how a request finds its route, route variables
- Views: Pug pages and the page components
- Forms:
Route::form - Declarative routes: every route type in one page
-
Queries: what the
datacapabilities read with
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)