Skip to content

The PageResponse

Superglue JSON responses come in 4 varieties.

  • SaveResponse The main response type used to persist the page state
  • GraftResponse Used by digging to update an existing page
  • StreamResponse Used for streaming responses
  • StreamMessage The message format used for Super Turbo Streams

[superglue_rails] and its generators would build these responses for you. The following is for reference:

The SaveResponse

Superglue expects your JSON responses to contain the following attributes. If you used Superglue's generators, this would be all set for you in application.json.props.

{
  data: {
    ...
  },
  componentIdentifier,
  defers,
  assets,
  csrfToken,
  action,
  path,
  renderedAt,
  fragments,
  restoreStrategy,
  slices
}

data

Your page's content. What you create with index.json.props, show.json.props, etc.

componentIdentifier

A string to instruct Superglue which component to render. The generated application.json.props will set this to the active_template_virtual_path (added by props_template), but you can customize this to fit your needs.

# application.json.props
json.componentIdentifier active_template_virtual_path

You can control which componentIdentifier will render which component in the page_to_page_mapping.js.

defers

The parts of your page that have been marked for deferment.

assets

An array of asset fingerprint strings. Used by Superglue to detect the need to refresh the browser due to new assets. You can control the refresh behavior in application_visit.js:

/**
  * The assets fingerprints changed, instead of transitioning
  * just go to the URL directly to retrieve new assets
  */
if (meta.needsRefresh) {
  window.location.href = meta.pageKey
  return meta
}

csrfToken

The authenticity token that Superglue will use for non-GET request made by using visit or remote thunks. This includes forms that have the data-sg-visit or data-sg-remote attribute.

Tip

Form's build with form_props will also have their own CSRF_TOKEN generated

action

Set to savePage for SaveResponse

renderedAt

An UNIX timestamp representing the time the response was rendered.

fragments

An array of paths identifying the location of all fragments in data. In application.json.props this is set to json.fragments!.

restoreStrategy

By specifying the restore strategy used (fromCacheOnly, revisitOnly, or fromCacheAndRevisitInBackground), you can control what superglue does when encountering the page again when pressing the back or forward browser navigation buttons.

  • fromCacheAndRevisitInBackground will transition to the cached page, then issue a visit in the background, redirecting and replacing history if needed. This is the option set in application.json.props when using the generators.
  • revisitOnly will always issue a visit request in the background before
  • fromCacheOnly will only restore the page from cache transitioning

slices

An object merged with the initialState when implementing buildStore inside of application.js. You can use this as the initial state for redux slices. Take advantage of the SAVE_RESPONSE to continually update your slice every time superglue receives a new page request.

GraftResponse

A response for when digging is used, i.e, props_at is part of the request parameter. The response is made of the following attributes:

componentIdentifier, assets, csrfToken, fragments, defers, slices, renderedAt

data

The found content node from digging

path

path is a keypath to the requested node. It would typically look like this: data.metrics.pageVisits. Superglue uses this path to immutably graft a node from the response to the client-side store.

If a fragment is encountered while digging, we reset the path to an empty array and populate the fragmentContext before continuing.

fragmentContext

Ultimately, the last id of the fragment that we encountered while digging for content. This is because fragments are denormalized.

action

action would be set to graft for GraftResponse

StreamResponse

Use for Super Turbo Stream responses to update fragments. The response is made of the following attributes:

Note

Deferments are disabled for StreamResponse and StreamMessage

assets, csrfToken, fragments, slices, renderedAt

data

An array of StreamMessages to be processed one at a time.

action

action would be set to handleStreamResponse for StreamResponse

StreamMessage

The format used for Super Turbo Streams.

data

The content rendered by a partial.

fragmentIds

A list of fragmentIds that the data targets.

handler

One of append, prepend, or save

options

Additional options passed to the handler function