Repository navigation
Route Form
Route::form($route, $capability, $options) answers a form's POST (or its PUT or DELETE through _method) by
calling a capability with the form's fields, its files and the route variables (the route variables win), as the
person who sent it, then redirects. The page that shows the form stays a
Route::page. Since 2.19.0; visitorsOnly, same,
accepted, inputs and signsIn since 2.20.0, signsInWith since 2.21.7.
Route::form('/books', 'create_book', ['success' => '/books/{id}', 'flash' => 'Book added']);/caligrafy-quill:new-capability create_book books:write
"Add a 'New book' form at /books/new for signed-in people. After saving, go to the book's page and say 'Book added'.
If a field is wrong, come back to the form with the message under the field and what was typed."
Claude writes the capability, the Route::page of the form and its Route::form, and the Pug view with =csrf(),
old(), errors() and flash().
Check before you say OK:
- the form has
method='POST',=csrf(), and=methodField('PUT')or'DELETE'for those routes; -
successandbackpoint at the pages that showflash()anderrors(); - sending the form empty shows the messages under the fields, and the typed values stay.
The create_book capability is the one of
Declarative routes, step 1.
-
Declare the page and the form. In
application/config/routing/web.php:Route::page('/books/new', 'Bookshelf/new', ['signedIn' => true, 'comeBack' => true, 'data' => ['authors' => 'list_authors']]); Route::form('/books', 'create_book', ['success' => '/books/{id}', 'flash' => 'Book added']); Route::form('/books/{id}', 'update_book', ['method' => 'PUT', 'success' => '/books/{id}', 'flash' => 'Saved']); Route::form('/books/{id}', 'delete_book', ['method' => 'DELETE', 'success' => '/books', 'flash' => 'Book deleted']);
-
Write the form.
application/views/Bookshelf/new.pug:extends ../default/master/site block content section.cq-hero.cq-hero--page h1.cq-display New book section.cq-band.cq-band--tight .cq-inner.cq-inner--narrow if flash('error') .cq-alert.cq-alert--error(role='alert')= flash('error') form(method='POST', action=$home . 'books') =csrf() .cq-field label(for='title') Title input#title.form-control(type='text', name='title', value=old('title')) if errors('title') p.cq-field-error= errors('title') .cq-field label(for='author_id') Author select#author_id.form-select(name='author_id') each $a in $authors option(value=$a['id'], selected=$a['id'] == old('author_id'))= $a['name'] if errors('author_id') p.cq-field-error= errors('author_id') button.btn.btn-primary(type='submit') Add book
A
PUTorDELETEform adds=methodField('PUT')(or'DELETE') after=csrf(). -
Try it. On
/books/new, send the form empty: the page comes back with "Some of the inputs are invalid" at the top and "The Title field is required" under the title. Fill it in: you land on/books/<id>with "Book added".
| The capability | The person goes to | The next page has |
|---|---|---|
| succeeds |
success, its {name} filled from the result, then from the route variables; without success, back to the form |
flash('success') with the flash message |
refuses the input (invalid) or finds a duplicate (conflict) |
back: the back option, else the page it came from (the Referer, when it is a page of this site), else /
|
errors('title'), old('title'), flash('error')
|
| needs someone signed in, nobody is | the sign-in page (signIn, default /login); without the authentication module, 403
|
|
refuses the person (forbidden) |
403 [ERROR 1006] Forbidden
|
|
| finds nothing, or anything else |
404 [ERROR 1005] Page Not Found
|
| Option | Default | What it does |
|---|---|---|
method |
'POST' |
'PUT', 'DELETE', or a list (['POST', 'PUT']); GET is refused (pages are Route::page) |
success |
back to the form | a path with {placeholders}, a full https:// address, or function ($result) { return '/books/' . $result['id']; }
|
flash |
none | the message for flash('success'), with {placeholders} as in success; or ['key' => 'message']
|
back |
the Referer of this site, else /
|
where invalid input goes, with the route's {placeholders}: 'back' => '/books/{id}'
|
error |
the capability's message | your message for flash('error'), or ['key' => 'message']
|
signIn |
'/login' |
where a visitor goes when the capability needs someone |
visitorsOnly |
none | a path: people already signed in are sent there and the capability does not run; a JSON request gets 403
|
same |
none | fields that must match: ['password_again' => ['password', 'The two passwords are not the same']]; without a message, "The two values are not the same" |
accepted |
none | boxes that must be ticked: ['terms' => 'Accept the terms of use']
|
inputs |
none | values only the server sets: an array, or function ($input) { return [...]; }. They replace what the form sent; the route variables still win |
signsIn |
none | the field of the capability's answer that holds the id of the person to sign in: 'signsIn' => 'id'. A new session id and a new CSRF token, as for Route::auth
|
signsInWith |
'password' |
how signsIn signed the person in: what AuthRoutes::signedInBy() answers for that session (2.21.7) |
The order of the checks. visitorsOnly, then (JSON with the session) the CSRF header, then same and accepted,
then the capability. A form that breaks same or accepted never reaches the capability, and their messages arrive in
errors('password_again'), like the capability's. Both are read from what the person sent: declare password_again in
$rules only if the capability needs it.
Values the form must not choose. A form can send any field. inputs writes the ones only the server knows, over
anything the form sent: the address a payment page comes back to, the visitor's address, today's price.
A form that leaves the site for a payment page:
Route::form('/orders/{order}/pay', 'start_checkout', [
'inputs' => fn () => ['site' => session('home')],
'success' => fn ($result) => $result['url'],
'back' => '/orders',
]);A sign-up form that signs the person in, for visitors only (register_user is the capability the authentication
module ships):
Route::page('/join', 'Bookshelf/join', ['visitorsOnly' => '/books']);
Route::form('/join', 'register_user', [
'visitorsOnly' => '/books',
'same' => ['confirmpasscode' => ['passcode', 'The two passwords are not the same']],
'accepted' => ['terms' => 'Accept the terms of use to create an account'],
'signsIn' => 'id',
'success' => '/books',
'back' => '/join',
'flash' => 'Welcome to the Bookshelf',
]);signsIn is for a capability that creates or finds the person and answers their id: sign-up, an invitation link, a
confirmation code. A sign-in that decides how to sign in, or that has a state to check, is a
Route::action.
| Helper | What it gives |
|---|---|
=csrf() |
the hidden _token field every form post needs (403 [ERROR 3000] without it) |
=methodField('PUT') |
the hidden _method field of a PUT or DELETE form |
errors(), errors('title')
|
all the messages, or one field's (null when it has none) |
old('title', $default) |
what the person typed, else $default
|
flash('success'), flash('error')
|
the message of the last post; flash('saved', 'Your changes are saved') in your own code keeps one for the next request |
- One request only. The errors, the old values and the messages are read by the next page, then gone.
- Passwords, card numbers, tokens (any field whose name contains
pass,secret,token,card,cvc,cvvoriban), files and_fields are never kept forold(). -
JSON: a request with
Accept: application/jsongets the REST answer instead of redirects:{"data": ...}with201(aPOSTthat changes data) or200, or{"error": ...}with401,403,404,409or422. With the session cookie it needs theX-CSRF-Tokenheader.
Route::form()-
Caligrafy\Form: how the post is answered -
Caligrafy\Flashand the helperscsrf(),methodField(),errors(),old(),flash()
-
successredirects to a page that redirects again: the message is read by the page in between and lost. Pointsuccessandbackat the page that shows it. -
A JSON post with the session and no
X-CSRF-Tokenanswers403: send the header (apiHeaders()in the Vue apps). -
A placeholder with no value (
'success' => '/authors/{author}'when neither the result nor the route hasauthor) stops with an error that names it. -
A file form without
enctype='multipart/form-data': no file arrives (File uploads). -
Route::formon awebOnlycapability: it answers "There is no capability". UseRoute::action.
- Pages:
Route::page - File uploads: the
filerule -
Validation: the rules of
$rules - Views: forms
- Declarative routes: the complete Bookshelf example
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)