up.protocol X-Up-Target

HTTP header

The X-Up-Target request and response headers allow the server read or change the target selector for a fragment update.

Server-side code is free to optimize its response by only rendering HTML that matches the selector. For example, you might prefer to not render an expensive sidebar if the sidebar is not targeted.

Unpoly will usually update a different selector in case the request fails. This selector is sent as a different request header, X-Up-Fail-Target.

Detecting the targeted fragment on the server

When the user updates a fragment .menu, Unpoly automatically includes the following request header:

X-Up-Target: .menu

The server chooses to render only the HTML for the updating fragment. It responds with the following HTTP:

Vary: X-Up-Target

<div class="menu">...</div>

Note

Request headers that influenced a response should be listed in a Vary response header. This tells Unpoly to partition its cache for that URL so that each request header value gets a separate cache entries.

Changing the render target from the server

The server may change the render target context by including a CSS selector as an X-Up-Target header in its response.

Content-Type: text/html
X-Up-Target: .selector-from-server

<div class="selector-from-server">
  ...
</div>

The frontend will use the server-provided target for both successful (HTTP status 200 OK) and failed (status 4xx or 5xx) responses.

Rendering nothing

The server may send an X-Up-Target: :none response header with an empty body to skip the current render pass.

Also see skipping unnecessary rendering.

Optional targets

An optional selector part (:maybe suffix) will be omitted from an X-Up-Target header unless it matches in the current page.

Required selector parts are always included in X-Up-Target.

Merging of request targets

When two caching requests are sent to the same URL within the same microtask, only a single request is sent. The request will contain both targets in its X-Up-Target header.

For example, these two render passes render different selectors from /path:

up.render('.foo', { url: '/path', cache: true })
up.render('.bar', { url: '/path', cache: true })

Unpoly will send a single request with both targets:

GET /path HTTP/1.1
X-Up-Target: .foo, .bar