FormStepExternalWidget
Stentor API Reference / stentor-models/src / FormStepExternalWidget
Interface: FormStepExternalWidget
Defined in: packages/stentor-models/src/Form/FormStep.ts:32
A step that mounts a third-party widget by injecting its script and letting it render into an anchor element. Used for booking handoffs where the partner ships a JS embed rather than an iframe URL or a server API.
Extends
Properties
externalWidget
externalWidget:
object
Defined in: packages/stentor-models/src/Form/FormStep.ts:33
anchorId
anchorId:
string
id of the element the third-party script mounts into, e.g. "airo-anchor". The widget renders an empty div with this id.
scriptSrc
scriptSrc:
string
https URL of the third-party embed script.
configGlobal
configGlobal:
string
Name of the global the script reads its configuration from, e.g. "airoBookingForm".
The widget assigns config to window[configGlobal] before appending the script.
config
config:
Record<string,string|number|boolean>
The configuration the third-party script consumes. Keys and values are provider-specific. May be merged at runtime with values returned by the server on form submit.
Values are deliberately restricted to primitives rather than unknown: this step is
authored by hand as JSON (in Studio), so the config must stay flat and
JSON-serializable, which is also how the embeds we target declare their own globals.
A provider needing a nested config would be a deliberate widening of this type, not
something to work around at the call site.
Note this describes the authored config only. The object a consumer actually
assigns to window[configGlobal] additionally carries a function at
successCallbackKey, so consumers model the runtime object with their own
type rather than reusing this one.
successCallbackKey?
optionalsuccessCallbackKey?:string
Optional key on config that the widget populates with a success callback
function, e.g. "apptScheduledCallback". The provider invokes it when the
visitor completes the booking.
cacheBust?
optionalcacheBust?:boolean
When true, a cache-busting query parameter is appended to scriptSrc.
Required by some providers (CostGuide documents ?v=<timestamp>).
renderTimeoutMs?
optionalrenderTimeoutMs?:number
How long to wait for the anchor to receive child nodes before treating the mount as a no-render (e.g. the provider found no matching contractor and rendered nothing). Defaults to a consumer-chosen value.
fallbackStep?
optionalfallbackStep?:string
Name of the step to advance to when the widget fails to render or reports no match, so the visitor is not left at a dead end.
name
name:
string
Defined in: packages/stentor-models/src/Form/FormStep.ts:95
Inherited from
title?
optionaltitle?:string
Defined in: packages/stentor-models/src/Form/FormStep.ts:96
Inherited from
subtitle?
optionalsubtitle?:string
Defined in: packages/stentor-models/src/Form/FormStep.ts:102
Optional supporting line rendered beneath title.
Consumers decide placement; the form widget renders it in the step's intro block.
Inherited from
fields
fields:
FormField[]
Defined in: packages/stentor-models/src/Form/FormStep.ts:106
The fields that are part of the form.
Inherited from
condition?
optionalcondition?:string
Defined in: packages/stentor-models/src/Form/FormStep.ts:108
Inherited from
nextAction?
optionalnextAction?:"next"|"submit"|"omit"
Defined in: packages/stentor-models/src/Form/FormStep.ts:116
The action to take when the user clicks the next button.
"next": move to the next step "submit": force "Next" instead of "Submit" (server generated next step). "omit": don't show the next button (for instance final "Thank you screen")
Inherited from
previousAction?
optionalpreviousAction?:"submit"|"omit"|"previous"
Defined in: packages/stentor-models/src/Form/FormStep.ts:124
The action to take when the user clicks the previous button.
"previous": move to the previous step "submit": force "Previous" instead of "Submit" (server generated previous step). "omit": don't show the previous button (for instance first step)
Inherited from
nextLabel?
optionalnextLabel?:string
Defined in: packages/stentor-models/src/Form/FormStep.ts:128
The label to use for the next button, defaults to "Next".
Inherited from
previousLabel?
optionalpreviousLabel?:string
Defined in: packages/stentor-models/src/Form/FormStep.ts:132
The label to use for the previous button, defaults to "Previous".
Inherited from
final?
optionalfinal?:boolean
Defined in: packages/stentor-models/src/Form/FormStep.ts:136
Inherited from
crmSubmit?
optionalcrmSubmit?:boolean
Defined in: packages/stentor-models/src/Form/FormStep.ts:139
Inherited from
warnBeforeUnload?
optionalwarnBeforeUnload?:boolean
Defined in: packages/stentor-models/src/Form/FormStep.ts:151
Beta
Warn the user before unloading the page if there are unsaved changes.
This is especially helpful when either crmSubmit is true or final is true, to prevent users from accidentally losing their data.
This will trigger a browser dialog when the user attempts to close the tab or navigate away which does not work on all browsers.
This is a beta feature and may change in future releases.
Inherited from
warnBeforeUnloadMessage?
optionalwarnBeforeUnloadMessage?:string
Defined in: packages/stentor-models/src/Form/FormStep.ts:160
Beta
Custom message to display in the unload warning dialog. This is used when the use attempts to hit the 'X' button on the form when they have unsaved changes.
This is a beta feature and may change in future releases.
Note: Most browsers do not display custom messages anymore, but having this property allows for future compatibility and clarity.
Inherited from
FormStep.warnBeforeUnloadMessage
fullBleed?
optionalfullBleed?:boolean
Defined in: packages/stentor-models/src/Form/FormStep.ts:166
Render this step edge-to-edge, suppressing the container's horizontal gutters. Third-party embeds frequently require the full container width.