Skip to main content

Recipe: Client approval

A review page for one client who has no Playbook account: a grid of the work with each item's state, and a detail view to approve it or ask for changes, undo that, and leave a note for the team. The app is behind a password; the client signs in with a personal PIN from the owner, on the password page or in the page itself. Anyone with only the password can look but not decide. Light and dark themes follow the visitor's system, with a toggle.

For a team or a client who has a Playbook account and is invited to the board, use the review recipe instead: it writes as the signed-in person and adds real comments.

When to use it​

  • One outside person or a small group approves work: a campaign, a logo round, product shots, a photo selection.
  • Access is password, sign-up is pin: the owner adds each guest and hands them a PIN, so every decision has a name on it. A PIN shown once can be replaced with New PIN in the Guests panel, which ends the old one.
  • Give each client their own board and app. Guests act on everything on the app's board; nothing limits a guest to "their own" items.

How the board drives it​

  • A select field Review holds each item's state, with the options Needs review, Approved and Changes requested. Create it once with create_custom_field before the first deploy; an item with no value counts as needing review. Fields belong to the whole workspace: check list_custom_fields first. If Review exists with other options too, keep them all in the list you pass (it replaces the options and clears the missing ones from every asset), or pick another name and change FIELD and playbook.json.
  • An item's title and description are its name and caption. The board's title and description are the page's heading and introduction.
  • approve and request_changes run only while Review is Needs review or empty, and set it. undo_approve and undo_request set it back, only for the guest who decided and only while nobody has changed it since. An action undoes exactly one other action, so each decision has its own undo.
  • note is a record action: one note per guest and item, which a new note replaces. Request changes asks for a note first and sends both.
  • The team sees each decision on the item in Playbook, and each note in Developer → Custom apps → Guests → Answers, or with list_app_answers. notify: true emails the app's creator, at most every 10 minutes.

Add the client​

After the deploy, add a guest with create_app_guest (or POST /v1/{workspace}/hosted_apps/{slug}/guests, or Add guest in the Guests panel). The answer carries the PIN, once. Send the client the app's address and their PIN: the PIN alone opens the app, typed on the password page under "Have a personal PIN?". Give the password only to people who should look without deciding; they can still enter a PIN in the page later.

The files​

playbook.json:

{
"guests": { "signup": "pin" },
"guest_actions": {
"approve": {
"label": "Approve",
"when": { "Review": ["Needs review", null] },
"set": { "Review": "Approved" },
"notify": true
},
"request_changes": {
"label": "Request changes",
"when": { "Review": ["Needs review", null] },
"set": { "Review": "Changes requested" },
"notify": true
},
"undo_approve": {
"label": "Undo approval",
"undoes": "approve",
"set": { "Review": "Needs review" }
},
"undo_request": {
"label": "Undo change request",
"undoes": "request_changes",
"set": { "Review": "Needs review" }
},
"note": {
"label": "Note to the team",
"record": true,
"input": { "note": true },
"notify": true
}
}
}

index.html:

<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Review</title>
<script>
// The visitor's theme, set before the page paints.
try { const theme = localStorage.getItem(`theme:${location.pathname}`); if (theme) document.documentElement.dataset.theme = theme } catch {}
</script>
<link rel="icon" href="data:," />
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600&family=Instrument+Serif&display=swap" />
<link rel="stylesheet" href="styles.css" />
</head>
<body>
<header class="top">
<p class="who" id="who"></p>
<button type="button" class="theme" id="theme" aria-label="Switch between light and dark"><svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="8" fill="none" stroke="currentColor" stroke-width="1.8" /><path d="M12 4a8 8 0 0 1 0 16z" fill="currentColor" /></svg></button>
</header>

<section class="hero">
<h1 id="title">Loading…</h1>
<p class="subtitle" id="subtitle"></p>
<p class="progress" id="progress"></p>
<form class="pin" id="pin" hidden>
<label for="pin-code">Your PIN lets you approve and leave notes. It came with the link.</label>
<div class="pin-row">
<input id="pin-code" autocomplete="one-time-code" autocapitalize="characters" spellcheck="false" placeholder="XXXX XXXX" required />
<button type="submit" class="solid" id="pin-send">Sign in</button>
</div>
<p class="error" id="pin-error" role="alert"></p>
</form>
</section>

<main class="grid" id="grid" aria-live="polite"></main>
<p class="notice" id="notice" hidden>The work did not load. Reload the page to try again.</p>

<dialog class="detail" id="detail" aria-labelledby="d-title">
<figure class="stage"><img id="d-image" alt="" /></figure>
<div class="panel">
<button type="button" class="close" id="d-close" aria-label="Close">×</button>
<h2 id="d-title"></h2>
<p class="caption" id="d-caption"></p>
<p class="state" id="d-state"></p>
<div class="decide" id="d-decide">
<button type="button" class="solid approve" id="d-approve">Approve</button>
<button type="button" class="ghost" id="d-changes">Request changes</button>
</div>
<p class="decided" id="d-decided" hidden><span id="d-decided-text"></span> <button type="button" class="link" id="d-undo">Undo</button></p>
<form class="note" id="d-note">
<label for="d-note-text">A note for the team</label>
<textarea id="d-note-text" rows="3" maxlength="500" placeholder="What should change, or what you love"></textarea>
<div class="note-row">
<span class="sent" id="d-note-sent"></span>
<button type="submit" class="ghost" id="d-note-send">Send note</button>
</div>
</form>
<p class="error" id="d-error" role="alert"></p>
</div>
</dialog>

<p class="toast" id="toast" role="status" hidden></p>

<script type="module" src="app.js"></script>
</body>
</html>

styles.css:

/* Light by default, dark when the system asks for it, and either one when the
visitor picks it (data-theme on <html>, set by the toggle). */
:root {
color-scheme: light;
--bg: #f7f7f5;
--card: #ffffff;
--ink: #17181c;
--soft: #4a4c55;
--muted: #7c7f89;
--line: rgba(23, 24, 28, 0.1);
--field: #f1f1ef;
--waiting: #7c7f89;
--approved: #17803d;
--on-approved: #ffffff;
--changes: #c2410c;
--error: #b42318;
--shadow: rgba(23, 24, 28, 0.14);
--focus: rgba(23, 24, 28, 0.45);
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light']) {
color-scheme: dark;
--bg: #101113; --card: #18191c; --ink: #f1f1f3; --soft: #c3c5cc; --muted: #8d909a; --line: rgba(255, 255, 255, 0.1);
--field: #101113; --waiting: #8d909a; --approved: #4ade80; --on-approved: #05210f; --changes: #fb923c; --error: #f97066;
--shadow: rgba(0, 0, 0, 0.5); --focus: rgba(241, 241, 243, 0.5);
}
}
:root[data-theme='dark'] {
color-scheme: dark;
--bg: #101113; --card: #18191c; --ink: #f1f1f3; --soft: #c3c5cc; --muted: #8d909a; --line: rgba(255, 255, 255, 0.1);
--field: #101113; --waiting: #8d909a; --approved: #4ade80; --on-approved: #05210f; --changes: #fb923c; --error: #f97066;
--shadow: rgba(0, 0, 0, 0.5); --focus: rgba(241, 241, 243, 0.5);
}

* { box-sizing: border-box; }
[hidden] { display: none !important; }
body { margin: 0; min-height: 100vh; background: var(--bg); color: var(--ink); font: 16px/1.5 'Instrument Sans', system-ui, sans-serif; -webkit-font-smoothing: antialiased; }
button, input, textarea { font: inherit; color: inherit; }
button { cursor: pointer; }
:focus-visible { outline: 2px solid var(--focus); outline-offset: 2px; }

.solid, .ghost { min-height: 44px; padding: 0 20px; border-radius: 99px; font-weight: 600; white-space: nowrap; }
.solid { border: 0; background: var(--ink); color: var(--bg); }
.ghost { border: 1px solid var(--line); background: var(--card); }
.solid:disabled, .ghost:disabled { opacity: 0.5; cursor: default; }
.link { padding: 0; border: 0; background: none; color: var(--muted); text-decoration: underline; text-underline-offset: 3px; }
.theme { display: grid; place-items: center; width: 36px; height: 36px; padding: 0; border: 1px solid var(--line); border-radius: 50%; background: var(--card); color: var(--soft); }
.theme svg { width: 16px; height: 16px; }

.top { display: flex; justify-content: flex-end; align-items: center; gap: 14px; padding: 18px 28px 0; }
.who { margin: 0; color: var(--muted); font-size: 14px; }
.who b { color: var(--ink); font-weight: 600; }

.hero { max-width: 760px; padding: 44px 28px 32px; }
h1 { margin: 0; font: 400 clamp(40px, 6.5vw, 72px)/1 'Instrument Serif', Georgia, serif; letter-spacing: -0.01em; }
.subtitle { margin: 14px 0 0; color: var(--soft); font-size: 18px; white-space: pre-line; }
.subtitle:empty { display: none; }
.progress { margin: 18px 0 0; color: var(--muted); font-size: 15px; }
.progress b { color: var(--ink); font-weight: 600; }
.pin { margin-top: 24px; padding: 18px; border: 1px solid var(--line); border-radius: 16px; background: var(--card); }
.pin label { display: block; color: var(--soft); font-size: 15px; }
.pin-row { display: flex; gap: 8px; margin-top: 12px; }
.pin input { flex: 1; min-width: 0; min-height: 44px; padding: 0 16px; border: 1px solid var(--line); border-radius: 99px; background: var(--field); font-size: 18px; letter-spacing: 0.12em; text-transform: uppercase; outline: none; }
.pin input:focus { border-color: var(--focus); }
.pin .error { margin-top: 10px; }

.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 18px; padding: 0 28px 72px; }
.tile { display: flex; flex-direction: column; gap: 10px; padding: 0; border: 0; background: none; text-align: left; }
.tile-image { width: 100%; aspect-ratio: 4 / 3; overflow: hidden; border-radius: 14px; background: var(--field); }
.tile-image img { display: block; width: 100%; height: 100%; object-fit: cover; transition: transform 0.4s ease; }
.tile:hover img { transform: scale(1.03); }
.tile-meta { display: flex; justify-content: space-between; align-items: baseline; gap: 10px; }
.tile-title { font-weight: 500; }
.badge { flex: none; display: inline-flex; align-items: center; gap: 6px; color: var(--waiting); font-size: 13px; }
.badge::before { content: ''; width: 7px; height: 7px; border-radius: 50%; background: currentColor; }
.badge.approved { color: var(--approved); }
.badge.changes { color: var(--changes); }
.empty, .notice { color: var(--muted); }
.notice { padding: 0 28px; }

.detail { width: 100%; max-width: none; height: 100%; max-height: none; margin: 0; padding: 0; border: 0; background: var(--bg); color: var(--ink); }
.detail[open] { display: grid; grid-template-columns: 1fr minmax(320px, 400px); }
.detail::backdrop { background: transparent; }
.stage { display: flex; align-items: center; justify-content: center; min-height: 0; margin: 0; padding: 32px; }
.stage img { display: block; max-width: 100%; max-height: 100%; border-radius: 12px; box-shadow: 0 24px 60px var(--shadow); }
.panel { position: relative; display: flex; flex-direction: column; gap: 14px; overflow-y: auto; padding: 56px 28px 28px; border-left: 1px solid var(--line); background: var(--card); }
.close { position: absolute; top: 14px; right: 16px; width: 36px; height: 36px; border: 1px solid var(--line); border-radius: 50%; background: none; font-size: 22px; line-height: 1; }
.panel h2 { margin: 0; font: 400 34px/1.05 'Instrument Serif', Georgia, serif; overflow-wrap: anywhere; }
.caption { margin: 0; color: var(--soft); white-space: pre-line; }
.caption:empty { display: none; }
.state { margin: 0; }
.decide { display: flex; flex-wrap: wrap; gap: 8px; }
.decide .approve { background: var(--approved); color: var(--on-approved); }
.decided { margin: 0; color: var(--soft); }
.note { display: flex; flex-direction: column; gap: 8px; margin-top: 8px; padding-top: 18px; border-top: 1px solid var(--line); }
.note label { font-weight: 600; font-size: 14px; }
.note textarea { padding: 12px 14px; resize: vertical; border: 1px solid var(--line); border-radius: 14px; background: var(--field); outline: none; }
.note textarea:focus { border-color: var(--focus); }
.note-row { display: flex; justify-content: space-between; align-items: center; gap: 10px; }
.sent { color: var(--muted); font-size: 14px; }
.error { margin: 0; color: var(--error); font-size: 14px; }
.error:empty { display: none; }

.toast { position: fixed; z-index: 20; bottom: 24px; left: 50%; margin: 0; padding: 10px 18px; transform: translateX(-50%); border-radius: 99px; background: var(--ink); color: var(--bg); font-weight: 600; }

@media (max-width: 760px) {
.top { padding: 14px 16px 0; }
.hero { padding: 28px 16px 24px; }
.pin-row { flex-direction: column; }
.grid { grid-template-columns: repeat(2, 1fr); gap: 16px 10px; padding: 0 16px 48px; }
.tile-meta { flex-direction: column; gap: 2px; }
.detail[open] { grid-template-columns: 1fr; grid-template-rows: 42% 1fr; }
.stage { padding: 16px; }
.panel { padding: 20px 16px 24px; border-left: 0; border-top: 1px solid var(--line); border-radius: 18px 18px 0 0; }
.close { top: 12px; right: 12px; }
.panel h2 { padding-right: 44px; font-size: 28px; }
}

@media (prefers-reduced-motion: reduce) {
*, *::before, *::after { transition: none !important; }
}

app.js:

// Work for one client to approve, behind a password (access `password`). The
// owner adds the client as a guest and hands them a PIN. With it, the client
// approves or asks for changes (state actions on a select field) and leaves a
// note on any item (a record action). Visitors with only the password look.

const FIELD = 'Review'
const APPROVED = 'Approved'
const CHANGES = 'Changes requested'
const UNDO = { approve: 'undo_approve', request_changes: 'undo_request' }
const NOTE = 'note'

const $ = (id) => document.getElementById(id)
const plain = (html) => new DOMParser().parseFromString(html || '', 'text/html').body.textContent.trim()
const el = (tag, className, text) => {
const node = document.createElement(tag)
if (className) node.className = className
if (text) node.textContent = text
return node
}

// Every call goes to the app's own address. Busy or cold reads (429, 5xx) are
// retried twice. A refusal throws its message, with its code and status.
async function call(path, { method = 'GET', body, tries = 3 } = {}) {
const response = await fetch(path, {
method,
headers: body ? { 'Content-Type': 'application/json' } : {},
body: body && JSON.stringify(body),
}).catch(() => null)
const status = response?.status ?? 0
if (method === 'GET' && tries > 1 && (status === 0 || status === 429 || status >= 500)) {
const wait = Number(response?.headers.get('Retry-After')) || 2
await new Promise((resolve) => setTimeout(resolve, wait * 1000))
return call(path, { method, body, tries: tries - 1 })
}
const answer = response ? await response.json().catch(() => ({})) : {}
if (response?.ok) return answer
throw Object.assign(new Error(answer.error || 'That did not go through. Try again.'), { code: answer.code, status })
}

const REFUSALS = {
condition_failed: 'This was decided a moment ago. Close and open it again to see how.',
not_your_run: 'This can no longer be undone: the team has changed it since.',
}

let items = []
let me = null // the guest: { name, runs }, or null for a visitor with the password only
let open = null
const decisions = {} // by asset token: 'approve' or 'request_changes', the guest's own current decision
const notes = new Set() // tokens where the guest has a current note

// The guest's current decision is still on the item (a run stops being current
// once anyone changes what it wrote), so it wins over a read that may be cached.
const stateOf = (item) => {
if (decisions[item.token]) return decisions[item.token] === 'approve' ? 'approved' : 'changes'
const value = item.fields?.[FIELD]
if (value === APPROVED) return 'approved'
if (value === CHANGES) return 'changes'
return 'waiting'
}
const LABELS = { waiting: 'Needs review', approved: 'Approved', changes: 'Changes requested' }

function toast(text) {
$('toast').textContent = text
$('toast').hidden = false
clearTimeout(toast.timer)
toast.timer = setTimeout(() => ($('toast').hidden = true), 2400)
}

// `runs` lists the guest's current runs of every action, undo actions included:
// keep the decisions and the notes.
function setGuest(guest) {
me = guest
for (const token of Object.keys(decisions)) delete decisions[token]
notes.clear()
for (const run of guest?.runs || []) {
if (run.action in UNDO) decisions[run.asset] = run.action
if (run.action === NOTE) notes.add(run.asset)
}
$('pin').hidden = !!me
$('who').replaceChildren()
if (!me) return
const out = el('button', 'link', 'Sign out')
out.type = 'button'
out.addEventListener('click', async () => {
await call('playbook/guest/signout', { method: 'POST', body: {} }).catch(() => {})
setGuest(null)
render()
})
$('who').append('Reviewing as ', el('b', '', me.name), ' · ', out)
}

function badge(item) {
const state = stateOf(item)
return el('span', `badge ${state}`, LABELS[state])
}

function render() {
const waiting = items.filter((item) => stateOf(item) === 'waiting').length
$('progress').replaceChildren(
...(items.length
? waiting
? [el('b', '', String(waiting)), ` of ${items.length} still need your review.`]
: [`All ${items.length} reviewed. Thank you.`]
: [])
)
$('grid').replaceChildren(
...(items.length
? items.map((item) => {
const tile = el('button', 'tile')
tile.type = 'button'
const frame = el('span', 'tile-image')
frame.style.backgroundColor = item.average_color || ''
const image = el('img')
const thumbs = [...item.thumbnails].sort((a, b) => a.width - b.width)
image.src = (thumbs.find((t) => t.width >= 520) || thumbs.at(-1)).url
image.alt = ''
image.loading = 'lazy'
frame.append(image)
const meta = el('span', 'tile-meta')
meta.append(el('span', 'tile-title', item.title), badge(item))
tile.append(frame, meta)
tile.addEventListener('click', () => show(item))
return tile
})
: [el('p', 'empty', 'Nothing to review yet.')])
)
}

function renderDetail() {
const item = open
const state = stateOf(item)
const mine = decisions[item.token]
$('d-state').replaceChildren(badge(item))
// Deciding takes a PIN and an item still waiting; undoing, the guest's own decision.
$('d-decide').hidden = !me || state !== 'waiting'
$('d-decided').hidden = !mine
$('d-decided-text').textContent = mine === 'approve' ? 'You approved this.' : 'You asked for changes.'
$('d-note').hidden = !me
$('d-note-sent').textContent = notes.has(item.token) ? 'Your note is with the team. A new one replaces it.' : ''
}

function show(item) {
open = item
$('d-image').src = item.display_url
$('d-image').alt = item.title || ''
$('d-title').textContent = item.title
$('d-caption').textContent = plain(item.description)
$('d-note-text').value = ''
$('d-error').textContent = ''
renderDetail()
$('detail').showModal()
}

async function act(action, body = {}) {
const item = open
const buttons = $('detail').querySelectorAll('button:not(.close)')
buttons.forEach((button) => (button.disabled = true))
$('d-error').textContent = ''
try {
const result = await call(`playbook/guest/actions/${action}`, { method: 'POST', body: { asset: item.token, ...body } })
// The answer is the item as it is now: reads stay cached for minutes, so
// keep it instead of reading the board again.
Object.assign(item, result.asset)
return true
} catch (error) {
if (error.status === 401) {
// The PIN was reset or the guest removed: back to the PIN form.
setGuest(null)
$('detail').close()
}
$('d-error').textContent = REFUSALS[error.code] || error.message
return false
} finally {
buttons.forEach((button) => (button.disabled = false))
if (open === item) renderDetail()
render()
}
}

// The note goes first: if it is refused, nothing is decided without it.
async function decide(action) {
const note = $('d-note-text').value.trim()
if (note) {
if (!(await act(NOTE, { note }))) return
notes.add(open.token)
$('d-note-text').value = ''
}
if (!(await act(action))) return
decisions[open.token] = action
renderDetail()
render()
toast(action === 'approve' ? 'Approved' : 'Changes requested')
}

$('d-approve').addEventListener('click', () => decide('approve'))
$('d-changes').addEventListener('click', () => {
if ($('d-note-text').value.trim()) return decide('request_changes')
$('d-error').textContent = 'Say what should change in the note, then press Request changes again.'
$('d-note-text').focus()
})
$('d-undo').addEventListener('click', async () => {
const action = decisions[open.token]
if (await act(UNDO[action])) {
delete decisions[open.token]
renderDetail()
render()
toast('Undone')
}
})
$('d-note').addEventListener('submit', async (event) => {
event.preventDefault()
const note = $('d-note-text').value.trim()
if (!note) return $('d-note-text').focus()
if (await act(NOTE, { note })) {
notes.add(open.token)
$('d-note-text').value = ''
renderDetail()
toast('Note sent')
}
})
$('d-close').addEventListener('click', () => $('detail').close())

$('pin').addEventListener('submit', async (event) => {
event.preventDefault()
$('pin-send').disabled = true
$('pin-error').textContent = ''
try {
await call('playbook/guest/pin', { method: 'POST', body: { pin: $('pin-code').value } })
setGuest(await call('playbook/guest/me'))
render()
} catch (error) {
$('pin-error').textContent = error.status === 401 ? 'That PIN is not right. Check it and try again.' : error.message
} finally {
$('pin-send').disabled = false
}
})

// Light or dark: the visitor's pick, kept per app, else the system's.
$('theme').addEventListener('click', () => {
const root = document.documentElement
const dark = root.dataset.theme ? root.dataset.theme === 'dark' : matchMedia('(prefers-color-scheme: dark)').matches
root.dataset.theme = dark ? 'light' : 'dark'
try {
localStorage.setItem(`theme:${location.pathname}`, root.dataset.theme)
} catch {}
})

async function allAssets() {
const all = []
for (let page = 1; ; page++) {
const { data, pagy } = await call(`playbook/api/assets?per_page=100&page=${page}`)
all.push(...data)
if (!pagy || pagy.current_page >= pagy.total_pages) return all
}
}

try {
const app = await call('playbook/app')
const [{ data: board }, assets, guest] = await Promise.all([
call(`playbook/api/boards/${app.board}`),
allAssets(),
call('playbook/guest/me').catch(() => null), // 401: password only, no PIN yet
])
items = assets.filter((asset) => !asset.is_group && asset.thumbnails?.length)
document.title = board.title
$('title').textContent = board.title
$('subtitle').textContent = plain(board.description)
setGuest(guest)
render()
} catch {
$('title').textContent = ''
$('notice').hidden = false
}

Make it yours​

Change:

  • FIELD, APPROVED and CHANGES in app.js, and the same names in playbook.json: they must match the field and its options exactly, as list_custom_fields spells them.
  • The PIN form's words in index.html: say where the PIN came from.
  • Colours. The tokens at the top of styles.css: the light set on :root, the dark set twice below it. Change both together.
  • Type. The Google Fonts link in index.html, the font on body, and the serif on headings.

Keep:

  • runs from guests/me read for both decisions and notes, and the guest's current decision trusted over the board's state: a run stays current only while nobody changes what it wrote, while a read can be up to five minutes old.
  • The item from each action's answer kept on the page instead of reading the board again.
  • not_your_run explained: the team changed the item since, so the client's undo no longer applies.
  • A 401 from a guest action sending the client back to the PIN form: their PIN was replaced or they were removed.
  • Names and notes shown with textContent, never innerHTML.

Check it​

Add yourself as a guest with create_app_guest. Open the app 390 px wide and 1280 px wide, in both themes. Enter the password, look around, then enter the PIN in the page. Approve an item and undo it; request changes on another, which asks for a note first. Reload: your decisions are still yours to undo. Open a new window and enter the PIN on the password page instead. In Playbook, check the Review field and the note in the Guests panel, then set the items back.