How an application fits together

A Pagelove application connects stored documents, views of those documents, and operations that change them. Start with the information people own and the changes they need to make. Then connect pages and controls to those operations.

Consider a task board: people read tasks, change their titles, mark them complete, and add new tasks. The names below are a design example, not resources Pagelove creates for you.

Source, view, and working copy

Part Task-board example Responsibility
Stored source /data/tasks.html, containing a task with id="task-42" The authoritative saved task information. Give each task a stable identity, meaningful properties, an owner, allowed values, and size limits.
Composed view /board.html, which includes task content Presents source information with navigation and controls. Rendering can change the representation.
Browser working model An editable DOM subtree for task 42 Holds the last confirmed representation and local edits. Keep domain fields in semantic HTML rather than maintaining a second editable copy of them in JSON.
Temporary interface state An open editor, focus, an error message, or a saving indicator Helps someone complete the task. Keep it distinct from persisted task information.

The resource path and element selector are separate: /data/tasks.html identifies the document, while #task-42 identifies an element within it. A URL fragment by itself is not an HTTP selector request; use the documented selector range or a supported client helper. Avoid identifying a task only by its current position in a list.

Declare which fields are editable, their types and bounds, and what unknown properties mean. Schemas describe governed data; shape constraints restrict permitted markup. Neither is implied merely by using an id or Microdata.

Reading a page and changing its source

A read addresses a resource. Composition can bring together fragments, templates, and bound values before the browser receives the result. See GET, includes, and stamps.

An editable composed fragment needs retained origin identity. For supported include and stamp write-through, a mutation lands in the origin resource. Authorization is evaluated against the composed page addressed by the request; shape/schema validation and concurrency checks use the origin. Do not assume every element visible in a composed page has a supported source to write back to.

Review access to the final view as well as its sources. Denying visitors a direct source read is not a confidentiality policy for content you deliberately expose through a readable composed page.

Browser DOM changes alone do not save anything. Native DOM methods edit the local document; Pagelove client helpers add explicit remote operations. Choose an operation and target according to their documented contracts:

Operation Meaning
GET Read a document or selected fragment.
PUT Replace the supported document or selected fragment.
POST Append content or create a resource through the applicable endpoint contract.
DELETE Remove the supported document or selected fragment.

Before sending, serialize the intended domain state deliberately. A form control's current value or checked property is not automatically reflected in outerHTML. Write the intended saved representation explicitly, preserving meaningful identity and excluding temporary interface state. Show readable, accessible save and error states, and retain the person's work when saving fails.

Permission, validation, and automation

Authorization rules decide who may perform an operation on its target. Schemas and shapes decide what content the relevant application write path accepts. Allowing a visitor to append a task does not make arbitrary submitted markup safe; a restrictive shape does not make the task private. Define both boundaries, including ownership and permitted transitions.

Triggers run before the request's own operation; processors run after request processing and can change the response. Do not treat a handler chain as one transaction: an action's earlier independent save may survive a later failure, and a processor error can occur after the main save has committed.

WebDAV is trusted authoring with its own authentication. Its whole-document and selector edits deliberately bypass application schemas, constraints, and handlers. Keep those credentials separate from visitor access. Authoring success does not prove that application writes will accept the same content. Authoring still depends on readable runtime metadata and storage: an unreadable local Schema can return 500, even for an attempted repair. See the WebDAV availability limits before relying on authoring as a recovery path.

Saving, conflicts, and incoming changes

Keep these states distinct in the editor:

  1. Confirmed: the representation and validator last established by the authoritative read or write contract.
  2. Draft: local changes based on that confirmed version.
  3. Pending: a frozen submitted change, separate from any newer draft edits.
  4. Accepted, rejected, or conflicting: handle the actual operation result. For supported conditional PUTs, a specific ETag in If-Match guards the version; a 412 requires reconciliation rather than overwriting newer content.
  5. Unknown: a timeout or lost response does not establish whether the save committed. Retain the pending change and draft, re-read, and reconcile before retrying an operation that could duplicate or overwrite work. Matching current content alone does not uniquely identify your operation's acceptance.

The PUT concurrency contract explains validator scope, including composed fragments. Use receipts or retry guarantees only where an operation documents them; there is no universal receipt mechanism to assume.

Server-Sent Events report changes and support reconnection. They do not automatically merge drafts or confirm a particular pending save. Preserve dirty edits when incoming changes arrive, reconcile against confirmed state, and re-fetch after a stream reset. Stop or re-establish subscriptions and save access when the authenticated session changes.

Authoring and releasing the application

Keep application definitions, templates, and styles distinct from mutable user content. Replacing a whole live document during deployment can overwrite tasks added since the author read it. Define what each release owns, coordinate concurrent authoring, and use supported preconditions and migrations where needed.

Now build your first application to try basic reads and writes, then build a blog to connect composition and constrained comments. Those tutorials introduce individual pieces; the ownership, recovery, and release decisions above still need to be made for your application.

Before sharing your app, work through the first deployment checklist and record the observed results.