hotlayout_flutter library

HotLayout for Flutter: draws server-driven screens published by the HotLayout builder.

This is the only public library of the package. A host needs four things, and each has one entry here:

All four may change while the user is in the flow: new data, a new version of the same document and a new theme are drawn at once, and the screen stack stays (see ScreenFlow.doc).

A complete host is in the package's example/.

Everything under src/ that is not exported here is internal and may change without notice.

Classes

BundledDocumentSource
A document from the app's assets.
ButtonAction
What a button or a list row does when tapped.
CloseAction
close: asks the host to close the flow. The reader leaves the screen stack alone.
DeeplinkAction
deeplink: url is the STRING that passed appLink, scheme is its scheme.
DocumentLoad
A document together with the answer to "where did it come from".
DocumentLocalization
The languages of a document and their translations.
DocumentSource
A place a document can be loaded from.
DocumentTransport
The network port. Implement it to read documents and themes through your own HTTP stack (authentication, certificate pinning, a shared client).
HostActionCall
One press handed to the host, as HostActions gives it to a handler.
HostActions
The host's actions, routed by type: pass handle to renderDocument as onRecordAction.
HotlayoutReport
Something the renderer ignored, replaced or refused on its own.
HttpDocumentTransport
IgnoredInputReport
A part of the document, of the bound data or of a request to the host was ignored because it does not have the shape the contract promises: a node of an unknown type, a token the theme does not have, a picture address the image policy refused, a write path the document had no right to name, a list cut by the budget. The rest of the screen is drawn.
IncompatibleDocumentReport
The document was NOT drawn: its schema major differs from the reader's, or the version is garbage.
InvalidActionParam
A catalog action whose parameter failed its form: the host RECEIVES it (it may know more than the document), but it has no standard, and runStandardAction never executes it.
InvalidThemeValuesReport
Values of the theme that do not have the shape of the theme schema were ignored or replaced.
LocaleResolution
The one answer to "which language is this document shown in" for one requested locale.
LocalizedStrings
The translations of one language, as renderScreen takes them. Obtain it from UiDocument.stringsFor.
NewerMinorDocumentReport
The document comes from a newer minor version: it is drawn, unknown widgets and tokens are skipped.
OpenUrlAction
openUrl: url is the STRING that passed httpsUrl, byte for byte.
PublishedDocumentSource
A published document read over HTTP, with a bundled copy as the fallback.
RendererLabels
Texts of the renderer's own surfaces. Pass to renderDocument or renderScreen as labels.
RenderTheme
One theme: the values behind the token names a document refers to.
ScreenEntry
One screen of a document: { screenId, name, root }.
ScreenFlow
The widget behind renderDocument: a document's stack of screens.
ScreenFlowController
A handle on the screen stack of one ScreenFlow, for a host that drives "back" itself — its own toolbar button, its own gesture, or a navigation setup in which the system back event does not reach the flow.
ScreenShown
The "screen shown" event (x-screenShown): the shown screen is the top of the stack, and the event fires when the top becomes a different FRAME. There is no "hidden" event.
StandardAction
A standard action whose parameters PASSED the check. This is what runStandardAction executes; the reader itself executes nothing.
ThemeContract
A set of themes: token names and the values behind them.
ThemeFallbackReport
The theme could not be read and the built-in theme is used.
ThemeLoad
A theme contract together with the answer to "where did it come from".
TrackEvent
The analytics event of a press (action.track), as the host receives it.
UiDocument
A document: a set of screens built from widgets, as published by the HotLayout builder.
UiNode
A node of a parsed document. Opaque to hosts: hand a screen to renderScreen or a document to renderDocument.
UnknownEntryReport
entry names an entry point the document does not have; the initial screen is shown.
UnknownThemeIdReport
The theme set does not have the theme that was asked for; another one is used.

Enums

ActionParamProblem
Why a parameter value failed its form (x-actions.problems).
DocumentLoadStatus
Why the document that is on screen is the one on screen.
HapticWord
The words of the field.
HostActionMiss
Why HostActions did not perform an action.
HotlayoutTransitions
Whether the screen flow animates its changes of screen.
ScreenPresentationToken
How a screen is presented (since 8.12.0): as a page that replaces the previous screen, or as a modal sheet laid over it.
ScreenShownCause
Why a screen was shown (x-screenShown.causes).
ThemeLoadStatus
Why the theme in use is the one in use.
VersionVerdict
Whether a reader can read a document or a theme of a given version.

Constants

kDocumentFetchTimeout → const Duration
Default timeout of PublishedDocumentSource: five seconds.
kIconSetVersion → const String
The version of the icon drawings built into this renderer (iconSetVersion of contract/icons.json). Independent of the document contract version: a redrawn icon changes only this.
kSupportedSchemaVersion → const String
The document contract version this renderer understands.
kSupportedThemeContractVersion → const String
The theme contract version this renderer understands.
kThemeFetchTimeout → const Duration
Default timeout of ThemeLoad.fromNetwork: three seconds.

Functions

directionOfLocale(String? locale) → TextDirection
The writing direction of a language tag, from CLDR data (package:intl).
isRtlLocale(String? locale) → bool
Whether locale is written right to left. See directionOfLocale.
renderDocument(UiDocument doc, {required RenderTheme theme, required Map<String, Object?> data, String? entry, String? locale, DateTime? now, SduiActionCallback? onAction, SduiRecordActionCallback? onRecordAction, SduiTrackCallback? onTrack, SduiHapticCallback? onHaptic, ValueChanged<ScreenEntry>? onScreenChanged, SduiScreenShownCallback? onScreenShown, ScreenScopeResolver? scopeFor, SduiValueWrite? onWrite, bool autofill = true, ImageUrlResolver? resolveImageUrl, int maxDownloadBytes = kDefaultMaxDownloadBytes, Object? writablePaths, RendererLabels labels = const RendererLabels(), ScreenFlowController? controller, ScreenFlowBackCallback? onSystemBack, bool handleSystemBack = true, HotlayoutTransitions transitions = HotlayoutTransitions.platform, HotlayoutReportCallback? onReport}) → Widget
Draws a document: its screens, the navigation between them and its modal sheets.
renderScreen(ScreenEntry screen, {required RenderTheme theme, required Map<String, Object?> data, Map<String, String> params = const {}, Map<String, Object?>? record, Map<String, Object?> session = const {}, ScreenScopeResolver? scopeFor, LocalizedStrings strings = LocalizedStrings.none, String? locale, DateTime? now, SduiActionCallback? onAction, SduiRecordActionCallback? onRecordAction, SduiTrackCallback? onTrack, SduiHapticCallback? onHaptic, SduiValueWrite? onWrite, bool autofill = true, ImageUrlResolver? resolveImageUrl, int maxDownloadBytes = kDefaultMaxDownloadBytes, Object? writablePaths, RendererLabels labels = const RendererLabels(), HotlayoutReportCallback? onReport}) → Widget
Draws one screen without navigation, for a host that keeps the stack of screens itself.
runStandardAction(ButtonAction action, {void openUrl(String url)?, Iterable<String>? deeplinkSchemes, void openDeeplink(String url)?, VoidCallback? close}) → bool
Performs the STANDARD action the host got in its onAction, with the executors the host passes in. Call it from your own callback; the renderer never calls it.

Typedefs

DocumentResponse = ({String body, int statusCode})
What the renderer needs from an HTTP answer: the status code and the body decoded as UTF-8.
HostActionHandler = FutureOr<void> Function(HostActionCall call)
Handles one app-specific action. May be asynchronous: a redeem that writes to a database returns its Future.
HotlayoutReportCallback = void Function(HotlayoutReport report)
The host callback for reports (onReport).
ScreenFlowBackCallback = bool Function()
Called when the system back button (or gesture) arrives while the document has a screen to go back to. Return true when the host handled the event itself (the stack is then left alone); return false to let the flow go one screen back.
ScreenScopeRequest = ({Map<String, String> params, Object? Function(String path) read, Map<String, Object?>? record})
What the host is told when a screen asks for its data: the parameters the navigation passed, record — the record the screen was opened with (a flat map of data paths, null when it was opened without one: a button outside a list, an entry point), and read — a lookup of a path in the data without the screen scope, where the record is already the strongest layer.
ScreenScopeResolver = Map<String, Object?> Function(ScreenScopeRequest request)
Supplies the data of one screen from its navigation parameters.
SduiActionCallback = void Function(ButtonAction action, String nodeId)
Receives every action the renderer did not perform itself, together with the id of the node that was tapped.
SduiHapticCallback = void Function(HapticWord word, String nodeId, Map<String, Object?>? record)
Receives the haptic request of a press (action.haptic, schema 9.25.0): once per press, BEFORE the analytics event and the action of the same press, also for the none action. The reader never vibrates by itself: the host decides what the word means (HapticFeedback.lightImpact and the like) and whether to do it at all, with the settings of the user. nodeId and record are the same as in SduiTrackCallback.
SduiRecordActionCallback = void Function(ButtonAction action, String nodeId, Map<String, Object?>? record)
Receives every action the renderer did not perform itself, together with the id of the node that was tapped and the record of that node (schema 9.2.0, actionRecord: 'node-record-scope').
SduiScreenShownCallback = void Function(ScreenShown shown)
Receives the "screen shown" event (ScreenShown): exactly once per show, after the frame, never from build.
SduiTrackCallback = void Function(TrackEvent event, String nodeId, Map<String, Object?>? record)
Receives the analytics event of a press (action.track, schema 9.8.0, actionTrack: 'once-per-press-before-action'): once per press, BEFORE anything else the press causes — before the action is performed or handed to the host, and for the none action too. nodeId and record are the same as in SduiRecordActionCallback.
SduiValueWrite = void Function(String path, Object value)
Receives a value the user changed in a bound input: a String from a TextField (and from a ChoiceGroup), a bool from a Switch or a Checkbox (9.13.0), a num from a number TextField (9.14.0: an int for a whole value, a double otherwise; an empty String when the field was cleared or holds something that is not a number). Called on every change, at once and without throttling — throttling a network behind it is the host's job.