types
References
FetchArgs
Re-exports FetchArgs
GraftingSuccessAction
Re-exports GraftingSuccessAction
GraftingErrorAction
Re-exports GraftingErrorAction
Visit
Re-exports Visit
VisitProps
Re-exports VisitProps
Remote
Re-exports Remote
RemoteProps
Re-exports RemoteProps
BeforeSave
Re-exports BeforeSave
ApplicationRemote
Re-exports ApplicationRemote
ApplicationVisit
Re-exports ApplicationVisit
Interfaces
ParsedResponse
Properties
Defer
Defer is a node in the page response thats been intentionally filled with empty or placeholder data for the purposes of fetching it later.
You would typically use it with props_template for parts of a page that you know would be slower to load.
Properties
url
string
A url with props_at keypath in the query parameter to indicate how to dig for the data, and where to place the data.
type
"auto" | "manual"
When set to auto Superglue will automatically make the request using the url. When set to manual, Superglue does nothing, and you would need to manually use remote with the url to fetch the missing data.
path
string
A keypath indicates how to dig for the data and where to place the data.
successAction
string
a user defined action for Superglue to dispatch when auto deferement is successful
failAction
string
a user defined action for Superglue to dispatch when auto deferement failed
GraftResponse<T>
The GraftResponse is a protocol, a shape that is responsible for partial updates using props_template's digging functionality in Superglue. Its meant to be implemented by the server and if you are using superglue_rails, the generators would have generated a props_template layout and view that would shape the graft responses for you.
Type Parameters
Properties
Fragment
A Fragment identifies a cross cutting concern, like a shared header or footer.
Properties
type
string
A user supplied string identifying a fragment. This is usually created using props_template
SuperglueState
A read only state that contains meta information about the current page.
Properties
currentPageKey
string
search
Record<string, undefined | string>
The query string object of the current url.
RootState<T>
The root state for a Superglue application. It occupies 2 keys in your app.
Type Parameters
Indexable
[name: string]: unknown
Properties
Meta
Meta is passed to the Promise when visit or remote resolves and contains additional information for navigation.
Extended by
Properties
pageKey
string
The URL of the response converted to a pageKey. Superglue uses this to persist the VisitResponse to store, when that happens.
VisitMeta
Meta is passed to the Promise when visit or remote resolves and contains additional information for navigation.
Extends
Properties
pageKey
string
The URL of the response converted to a pageKey. Superglue uses this to persist the VisitResponse to store, when that happens.
needsRefresh
boolean
true when assets locally are detected to be out of date
Handlers
Properties
HistoryState
The state that is saved to history.state. Superglue stores information about the current page so that it can restore the page state when navigating back
Properties
superglue
true
Is always true so superglue can differentiate pages that have superglue enabled or not
BasicRequestInit
A variation of RequestInit except the headers must be a regular object
Extends
RequestInit
Properties
headers?
{}
A Headers object, an object literal, or an array of two-item arrays to set request's headers.
RequestInit.headers
NavigationContextProps
Superglue comes with a Navigation component that provides a context with access to Visit, Remote and other useful tooling.
You can also use this to build your own <Link> component.
Properties
pageKey
string
The pagekey that's being used to render the current page component. Useful when used in combination with Remote to create requests that target the current page.
search
Record<string, undefined | string>
The current pageKey (current url) query params as an object.
NavigationProviderProps
This is the navigation component that gets used by ApplicationProps. The component takes a mapping of page components and swaps them when navigating and passes NavigateTo to all page components.
Properties
initialPageKey
string
The PageKey that's to be used when first rendering. Used to determine the initial page component to show.
BuildStore()
Provide this callback to ApplicationProps returning a Redux store for Superglue to use. This would be setup and generated for you in store.js. We recommend using using Redux toolkit's configureStore to build the store.
BuildStore(
initialState:RootState<JSONMappable>,reducer: {superglue:superglueReducer;pages:pageReducer; }):SuperglueStore
Provide this callback to ApplicationProps returning a Redux store for Superglue to use. This would be setup and generated for you in store.js. We recommend using using Redux toolkit's configureStore to build the store.
Parameters
reducer
object
A preconfigured reducer
Returns
Defined in
BuildVisitAndRemote()
Provide this callback to ApplicationProps returning a visit and remote function. These functions will be used by Superglue to power its UJS attributes and passed to your page components and NavigationContextProps. You may customize this functionality to your liking, e.g, adding a progress bar.
BuildVisitAndRemote(
navigatorRef:RefObject<null| {navigateTo:NavigateTo; }>,store:SuperglueStore): {visit:ApplicationVisit;remote:ApplicationRemote; }
Provide this callback to ApplicationProps returning a visit and remote function. These functions will be used by Superglue to power its UJS attributes and passed to your page components and NavigationContextProps. You may customize this functionality to your liking, e.g, adding a progress bar.
Parameters
Returns
{visit: ApplicationVisit;remote: ApplicationRemote; }
Defined in
SetupProps
Properties
initialPage
The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb template, e.g., index.html.erb
path
string
The path of the current page. It should equal to the location.pathname + location.search + location.hash
store
The exported store from store.js. If you used the generators it would contain slices for superglue, pages, and the flash.
buildVisitAndRemote
A factory function that will return a visit and remote function. All of Superglue and UJS will use these functions. You should customize the function, for example, to add a progress bar.
history?
History
An optional history object https://github.com/remix-run/history. If none is provided Superglue will create one for you.
navigatorRef
RefObject<null | {navigateTo: NavigateTo; }>
A ref object created from the Application component that will be passed to buildVisitAndRemote
ApplicationProps
Props for the Application component
Extends
ComponentPropsWithoutRef<"div">
Properties
initialPage
The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb template, e.g., index.html.erb
path
string
The path of the current page. It should equal to the location.pathname + location.search + location.hash
buildVisitAndRemote
A factory function that will return a visit and remote function. All of Superglue and UJS will use these functions. You should customize the function, for example, to add a progress bar.
mapping
Record<string, ComponentType<{}>>
A mapping between your page props and page component. This is setup for you in page_to_page_mapping.
history?
History
An optional history object https://github.com/remix-run/history. If none is provided Superglue will create one for you.
store
The exported store from store.js. If you used the generators it would contain slices for superglue, pages, and the flash.
Type Aliases
PageKey
PageKey:
string
A PageKey is a combination of a parsed URL's pathname + query string. No hash.
Example
/posts?foobar=123Defined in
RestoreStrategy
RestoreStrategy:
"fromCacheOnly"|"revisitOnly"|"fromCacheAndRevisitInBackground"
Defines the behavior when navigating to a page that is already stored on the client. For example, when navigating back.
When the page already exists in the store:
fromCacheOnly- Use the cached page that exists on the store, only.revisitOnly- Ignore the cache and make a request for the latest page. If the response was 200, the NavigationAction would benoneas we don't want to push into history. If the response was redirected, the NavigationAction would be set toreplace.fromCacheAndRevisitInBackground- Use the cache version of the page so superglue can optimistically navigate to it, then make an additional request for the latest version.
Defined in
NavigationAction
NavigationAction:
"push"|"replace"|"none"
A NavigationAction is used to tell Superglue to history.push, history.replace or do nothing.
Defined in
ComponentIdentifier
ComponentIdentifier:
string
An identifier that Superglue will uses to determine which page component to render with your page response.
Defined in
Keypath
Keypath:
string
A keypath is a string representing the location of a piece of data. Superglue uses the keypath to dig for or update data.
Examples
Object access
data.header.avatarArray access
data.body.posts.0.titleArray with lookahead
data.body.posts.post_id=foobar.titleDefined in
JSONPrimitive
JSONPrimitive:
string|number|boolean|null|undefined
A JSON Primitive value
Defined in
JSONObject
JSONObject: {}
A JSON Object
Index Signature
[key: string]: JSONValue
Defined in
JSONMappable
JSONMappable:
JSONValue[] |JSONObject
A JSON Object or an array of values
Defined in
JSONKeyable
JSONKeyable:
JSONObject[] |JSONObject
A array of JSON key value objects or a JSON Object
Defined in
JSONValue
JSONValue:
JSONPrimitive|JSONMappable
A primitive or a mappable object
Defined in
VisitResponse<T>
VisitResponse<
T>: {data:T;componentIdentifier:ComponentIdentifier;assets:string[];csrfToken:string;fragments:Fragment[];defers:Defer[];slices:JSONObject;renderedAt:number;restoreStrategy:RestoreStrategy; }
The VisitResponse is a protocol, a shape that is responsible for full page visits in Superglue. Its meant to be implemented by the server and if you are using superglue_rails, the generators would have generated a props_template layout and view that would shape the visit responses for you.
Type Parameters
Type declaration
Defined in
Page<T>
Page<
T>:VisitResponse<T> & {savedAt:number; }
A Page is a VisitResponse that's been saved to the store
Type declaration
Type Parameters
Defined in
PageResponse
PageResponse:
GraftResponse|VisitResponse
A PageResponse can be either a GraftResponse or a VisitResponse. Its meant to be implemented by the server and if you are using superglue_rails, the generators will handle both cases.
Defined in
AllPages<T>
The store where all page responses are stored indexed by PageKey. You are encouraged to mutate the Pages in this store.
Type Parameters
Defined in
VisitCreator()
VisitCreator: (
input:string|PageKey,options:VisitProps) =>VisitMetaThunk
VisitCreator is a Redux action creator that returns a thunk. Use this to build the Visit function. Typically its already generated in application_visit.js
Parameters
input
string | PageKey
options
Returns
Defined in
RemoteCreator()
RemoteCreator: (
input:string|PageKey,options:RemoteProps) =>MetaThunk
RemoteCreator is a Redux action creator that returns a thunk. Use this to build the Remote function. Typically its already generated in application_visit.js
Parameters
input
string | PageKey
options
Returns
Defined in
Dispatch
Dispatch:
ThunkDispatch<RootState,undefined,Action>
Defined in
SuperglueStore
SuperglueStore:
EnhancedStore<RootState,Action,Tuple<[StoreEnhancer<{dispatch:Dispatch; }>,StoreEnhancer]>>
A Store created with Redux Toolkit's configureStore setup with reducers from Superglue. If you are using superglue_rails this would have been generated for you in store.js and setup correctly in application.js
Defined in
UJSHandlers()
UJSHandlers: (
{ ujsAttributePrefix, visit, remote, store, }: {ujsAttributePrefix:string;visit:ApplicationVisit;remote:ApplicationRemote;store:SuperglueStore; }) =>Handlers
Parameters
{ ujsAttributePrefix, visit, remote, store, }
object
{ ujsAttributePrefix, visit, remote, store, }.ujsAttributePrefix
string
{ ujsAttributePrefix, visit, remote, store, }.visit
{ ujsAttributePrefix, visit, remote, store, }.remote
{ ujsAttributePrefix, visit, remote, store, }.store
Returns
Defined in
SaveAndProcessPageThunk
SaveAndProcessPageThunk:
ThunkAction<Promise<void>,RootState,undefined,Action>
Defined in
MetaThunk
MetaThunk:
ThunkAction<Promise<Meta>,RootState,undefined,Action>
Defined in
VisitMetaThunk
VisitMetaThunk:
ThunkAction<Promise<VisitMeta>,RootState,undefined,Action>
Defined in
DefermentThunk
DefermentThunk:
ThunkAction<Promise<void[]>,RootState,undefined,Action>
Defined in
NavigateTo()
NavigateTo: (
path:Keypath,options: {action:NavigationAction; }) =>boolean
Passed to every page component and also available as part of a NavigationContext:
import { NavigationContext } from '@thoughtbot/superglue';
const { navigateTo } = useContext(NavigationContext)Manually navigate using pages that exists in the store and restores scroll position. navigateTo is what Visit in your application_visit.js ultimately calls.
If there is an existing page in your store navigateTo will restore the props, render the correct component, and return true. Otherwise, it will return false. This is useful if you want to restore an existing page before making a call to visit or remote.
Parameters
options
object
-
Returns
boolean
true if the navigation was a success, false if the page was not found in the store.
Defined in
Last updated
Was this helpful?