Primeiros passos
Em dez minutos você terá uma página em que um botão pede HTML ao servidor e a resposta troca um pedaço da página. Há dois caminhos de entrada, e os dois chegam ao mesmo lugar:
- Com HTML puro: nenhum código de servidor, só uma pasta de arquivos estáticos.
- Com Go ou Arandu: um handler de verdade, que responde fragmentos e formulários.
Depois, o que ler em seguida. Inglês: Getting started.
O que é o YPY
O YPY é uma biblioteca hipermídia. Um elemento HTML diz, em atributos, qual requisição fazer, quando e onde colocar
a resposta. O servidor responde com HTML, não com JSON. Não há etapa de build para você nem dependências: uma tag
<script>.
<button ypy-get="/hello" ypy-target="#out"
class="rounded bg-sky-600 px-4 py-2 text-white">Say hello</button>
<p id="out" class="mt-4 text-slate-700"></p>Leia em voz alta: ao clicar, faça GET em /hello e ponha a resposta em #out. Sem o script o botão não faz nada,
e por isso a navegação de verdade (links e formulários) deve sempre funcionar sem ele; veja
Melhoria progressiva.
Pegue o arquivo
O build escreve em dist/ os arquivos que você serve:
go run ./cmd/ypy build # precisa de Go 1.26 ou mais novo; escreve dist/| Arquivo | Use quando |
|---|---|
dist/ypy.min.js |
é um projeto novo |
dist/ypy.max.min.js |
é um projeto novo que quer as extensões oficiais (SSE, WebSocket, signals, preload e outras) |
dist/ext/*.min.js |
uma extensão por vez, depois do núcleo: veja Extensões (em inglês) |
dist/ypy.d.ts |
tipos TypeScript de window.ypy |
Copie o arquivo de que precisa para junto das suas páginas. Os nomes de pacote nos registros ainda não foram
publicados, então não há npm install nem link de CDN para indicar aqui.
Caminho A: HTML puro
Você precisa só de uma pasta e de qualquer servidor de arquivos estáticos. Dois arquivos:
index.html
<!doctype html>
<html lang="pt-BR">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>YPY, primeira página</title>
<script src="/ypy.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script> <!-- qualquer CSS serve; o Tailwind é só o exemplo -->
</head>
<body class="mx-auto max-w-md p-8 font-sans">
<h1 class="text-2xl font-semibold">Olá, YPY</h1>
<button ypy-get="/hello.html" ypy-target="#out"
class="mt-4 rounded bg-sky-600 px-4 py-2 text-white">Dizer olá</button>
<div id="out" class="mt-4"></div>
</body>
</html>hello.html (um fragmento: sem <html>, sem <head>, só o pedaço):
<p class="rounded border border-sky-200 bg-sky-50 p-3">Olá, vindo de um arquivo estático.</p>Sirva a pasta e abra:
python3 -m http.server 8080 # ou qualquer servidor estático; depois abra http://localhost:8080Clique no botão: o parágrafo aparece em #out e a barra de endereço não muda. Um arquivo estático não sabe
distinguir uma requisição do YPY de uma comum, então um link para /hello.html abriria o fragmento puro. Para um
primeiro teste serve, e é por isso que um servidor de verdade olha o cabeçalho YPY-Request (próximo caminho).
A tag do Tailwind acima é o CDN de testes, bom para experimentar. Num projeto de verdade compile o seu CSS e acrescente as pastas de templates em
@source; veja Conceitos centrais.
Caminho B: Go e Arandu
O SDK Go (github.com/ypy-develop/go) é o lado do servidor da mesma conversa. Precisa de Go 1.26 ou mais novo e de
nenhuma outra dependência.
go get github.com/ypy-develop/goUm programa completo só com a biblioteca padrão. Ele serve a página, o script e um endpoint que responde de um jeito a uma requisição do YPY e de outro a um navegador:
package main
import (
"fmt"
"html"
"log"
"net/http"
"strings"
"sync"
ypy "github.com/ypy-develop/go"
)
const page = `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Items</title>
<script src="/ypy.min.js"></script>
</head>
<body class="mx-auto max-w-md p-8">
<form ypy-post="/items" ypy-target="#list" ypy-swap="beforeend" method="post" action="/items" class="flex flex-wrap gap-2">%s</form>
<ul id="list" class="mt-4 space-y-1">%s</ul>
</body>
</html>`
// fields is the inside of the form, with an error when there is one. The page and the 422 answer share it.
func fields(value, problem string) string {
invalid, message := "", ""
if problem != "" {
invalid = ` aria-invalid="true" aria-describedby="title-error"`
message = `<p id="title-error" role="alert" class="w-full text-sm text-red-700">` + html.EscapeString(problem) + `</p>`
}
return `<input id="title" name="title" value="` + html.EscapeString(value) + `" required` + invalid +
` class="flex-1 rounded border p-2 aria-invalid:border-red-500" aria-label="New item">` + message +
`<button class="rounded bg-sky-600 px-4 py-2 text-white">Add</button>`
}
type app struct {
mu sync.Mutex
items []string
}
func (a *app) list() string {
a.mu.Lock()
defer a.mu.Unlock()
var sb strings.Builder
for _, it := range a.items {
sb.WriteString(row(it))
}
return sb.String()
}
func row(title string) string {
return `<li class="rounded border p-2">` + html.EscapeString(title) + `</li>`
}
func (a *app) index(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/html; charset=utf-8")
fmt.Fprintf(w, page, fields("", ""), a.list())
}
func (a *app) create(w http.ResponseWriter, r *http.Request) {
title := strings.TrimSpace(r.PostFormValue("title"))
if title == "" {
ypy.ValidationError(w, fields(title, "Write something first.")) // the inside of the form, with its error
return
}
a.mu.Lock()
a.items = append(a.items, title)
a.mu.Unlock()
if !ypy.FromRequest(r).IsYPY {
ypy.SeeOther(w, "/") // no script: post, redirect, get
return
}
ypy.Fragment(w, row(title)) // goes into #list, at the end
}
func main() {
a := &app{}
mux := http.NewServeMux()
mux.HandleFunc("GET /{$}", a.index)
mux.HandleFunc("POST /items", a.create)
mux.Handle("GET /ypy.min.js", http.FileServer(http.Dir("dist")))
log.Fatal(http.ListenAndServe(":8080", ypy.Middleware(mux)))
}Três pontos importam além deste exemplo:
-
Um endpoint, duas respostas.
ypy.FromRequest(r).IsYPYé verdadeiro quando o cliente do YPY fez a requisição. Um navegador sem script (ou um robô de busca) recebe um redirecionamento e uma página inteira; o YPY recebe o fragmento. -
422para formulário inválido,303para o que deu certo. O YPY põe o corpo do 422 dentro do formulário e segue o 303 como qualquer sucesso. Veja Formulários (em inglês). -
ypy.MiddlewareacrescentaVary: YPY-Request. Sem isso, um cache compartilhado pode entregar o fragmento a quem carrega a página.
O mesmo handler nas outras pilhas está nas receitas. Para ver o que o navegador envia e recebe, abra
as ferramentas do desenvolvedor: a requisição leva YPY-Request: true, YPY-Target: ul#list e
YPY-Request-Type: partial.
Numa aplicação Arandu
Uma aplicação Arandu liga o mesmo handler onde a aplicação é montada, em geral bootstrap/app.go:
router.Post("/items", items.Create, ypy.Middleware)O roteador do Hesape recebe handlers e middleware comuns, então nada mais muda. CSRF, sessões e o layout vêm do Hesape; veja a receita do Arandu.
Um projeto escrito antes do YPY
Se você está levando um projeto que já tem marcação hipermídia, não comece aqui. Rode ypy migrate, que o converte
para o YPY e aponta a tag do script para o ypy.min.js: Migração.
O que ler em seguida
| Você quer | Leia |
|---|---|
| entender o vocabulário | Conceitos centrais |
| levar um projeto escrito antes do YPY | Migração |
| reagir ao que acontece na página | Events (em inglês) |
| tratar formulários e validação | Forms (em inglês) |
| deixar seguro | Checklist de segurança |
| deixar rápido | Performance (em inglês) |
| testar o servidor sem navegador | Testing your app (em inglês) |
| copiar um servidor pronto | Receitas: Go e Arandu; Django, Rails e Laravel em inglês |
| achar a página de qualquer tarefa | Índice da documentação |