Hypermedia foundations

Return a full page or a fragment

Use ordinary navigation for complete documents and return focused fragments when an HTMX target needs only part of the page.

8 minute lesson

~~~

A public URL should return a complete document when opened directly. An HTMX target usually needs only the relevant fragment.

One route can support both representations:

GET /tasks

if HX-History-Restore-Request is true or HX-Request is absent:
  render the full page containing that fragment
else:
  render the task-list fragment

The fragment might be:

<ul id="task-list">
  <li>Send invoice</li>
</ul>

The full response includes the document shell, title, navigation, and the same list template. Reuse the list renderer so the two paths cannot drift into different markup.

There is one history detail: a request carrying HX-History-Restore-Request: true follows a cache miss and expects enough HTML to restore the page, normally a full document. Do not treat every HX-Request as an identical fragment request.

These headers describe rendering context, not identity. Any client can forge them.

Test /tasks three ways: direct navigation, an HTMX interaction, and browser back after clearing the history cache. Each response should contain the representation its consumer expects.

Lesson completed