rfw library

Remote Flutter Widgets

Renders a widget tree described in a file, which you can change at runtime.

There are many ways to use a package such as this one. In general, the approach looks something like this:

The Remote Flutter Widgets comes from the server over the network and into the Runtime. The Runtime also receives the Data model, which is populated both from Client data and from Server data obtained over the network. The Runtime creates Flutter Widgets, which send state updates back to the Runtime, and send user input to the Client logic, which either directly changes the Client data, or sends messages over the network to the Server logic, which then updates the Server data.

The network aspects of this design are out of scope for this package. Remote widget libraries and data should be cached locally, to avoid network issues causing interface failures.

In the extreme, this package can be combined with a local scripting runtime (e.g. https://pub.dev/packages/hetu_script) to run remotely-fetched logic locally:

The Remote Flutter Widgets once again come from the server and follow the same path via the network to the Runtime. The Runtime combines this with the Data model to generate the Flutter Widgets, which send state updates directly back to the Runtime and user input to the Hard-coded client logic. That logic updates the Client data which updates the Data model, but also sends messages to the Scripting engine which is also on the Client. The Scripting engine is configured from Scripts obtained over the network, and generates Script data that also populates the Data model.

Using the RemoteWidget widget

To render a remote widget, the RemoteWidget widget can be used. It takes a DynamicContent instance and a Runtime instance, which must be configured ahead of time.

Best practices for handling remote data

The most efficient way to parse remote data is decodeDataBlob and the most efficient way to parse remote widget libraries is decodeLibraryBlob.

The methods for parsing the text format are not exported by package:rfw/rfw.dart to discourage their use in client-side code.

Server-side Dart

This package can be used in non-Flutter environments by importing package:rfw/formats.dart rather than package:rfw/rfw.dart. In the formats mode, the Runtime and DynamicContent objects, as well as the RemoteWidget widget, are not available, but the parseDataFile and parseLibraryFile methods are. They can be used in conjunction with encodeDataBlob and encodeLibraryBlob (respectively) to generate the binary files used by client-side code.

Classes

AnimationDefaults
Default duration and curve for animations in remote flutter widgets.
AnyEventHandler
Base class for EventHandler and SetStateHandler.
AnyStateReference
Base class for StateReference and BoundStateReference.
ArgsReference
Unbound reference to arguments.
ArgumentDecoders
A set of methods for decoding structured values from a DataSource.
BlobNode
Base class of nodes that appear in the output of decodeDataBlob and decodeLibraryBlob.
BoundArgsReference
Bound reference to arguments.
BoundLoopReference
Bound reference to a Loop.
BoundStateReference
Bound reference to a remote widget's state.
ConstructorCall
Representation of references to widgets in Remote Flutter Widgets library blobs.
DataReference
Reference to the DynamicContent data that is passed into the widget (see Runtime.build's data argument).
DataSource
Interface for LocalWidgetBuilder to obtain data from arguments.
DynamicContent
Configuration data from the remote widgets.
EventHandler
Description of a callback in an RFW widget declaration.
FullyQualifiedWidgetName
The name of a widget used by the RFW package, including its library name.
Import
A library import.
LibraryName
The name of a widgets library in the RFW package.
LocalWidgetLibrary
Widgets defined by the client application. All remote widgets eventually bottom out in these widgets.
Loop
Representation of the ...for construct in Remote Flutter Widgets library blobs.
LoopReference
Unbound reference to a Loop.
Missing
The type of the missing value.
Reference
Base class for various kinds of references in the RFW data structures.
RemoteWidget
Injection point for a remote widget.
RemoteWidgetLibrary
The in-memory representation of the output of parseTextLibraryFile or decodeLibraryBlob.
Runtime
The logic that builds and maintains Remote Flutter Widgets.
SetStateHandler
Description of a state setter in an RFW widget declaration.
SourceLocation
Reference to a location in a source file.
SourceRange
Reference to a range of a source file.
StateReference
Unbound reference to remote widget's state.
Switch
Representation of the switch construct in Remote Flutter Widgets library blobs.
WidgetBuilderArgReference
Reference to the single argument of type DynamicMap passed into the widget builder.
WidgetBuilderDeclaration
Representation of functions that return widgets in Remote Flutter Widgets library blobs.
WidgetDeclaration
A description of a widget in a remote widget library.
WidgetLibrary
Base class for widget libraries.

Constants

dataBlobSignature → const List<int>
The first four bytes of a Remote Flutter Widgets binary data blob.
libraryBlobSignature → const List<int>
The first four bytes of a Remote Flutter Widgets binary library blob.
missing → const Missing
The value used by DynamicContent to represent missing data.

Functions

createCoreWidgets() → LocalWidgetLibrary
A widget library for Remote Flutter Widgets that defines widgets that are implemented on the client in terms of Flutter widgets from the widgets Dart library.
createMaterialWidgets() → LocalWidgetLibrary
A widget library for Remote Flutter Widgets that defines widgets that are implemented on the client in terms of Flutter widgets from the material Dart library.
decodeDataBlob(Uint8List bytes) → Object
Decode a Remote Flutter Widgets binary data blob.
decodeLibraryBlob(Uint8List bytes) → RemoteWidgetLibrary
Decode a Remote Flutter Widgets binary library blob.
deepClone(Object? template) → Object?
Returns a copy of a data structure if it consists of only DynamicMaps, DynamicLists, ints, doubles, bools, and Strings.
encodeDataBlob(Object value) → Uint8List
Encode data as a Remote Flutter Widgets binary data blob.
encodeLibraryBlob(RemoteWidgetLibrary value) → Uint8List
Encode data as a Remote Flutter Widgets binary library blob.

Typedefs

ArgumentDecoder<T> = T Function(DataSource source, List<Object> key)
Signature for methods that decode structured values from a DataSource, such as the static methods of ArgumentDecoders.
DynamicList = List<Object?>
A list whose values are DynamicMap, DynamicList, int, double, bool, string, and BlobNode objects.
DynamicMap = Map<String, Object?>
A map whose keys are strings and whose values are DynamicMap, DynamicList, int, double, bool, string, and BlobNode objects.
HandlerGenerator<T extends Function> = T Function(HandlerTrigger trigger)
Signature of the callback passed to DataSource.handler.
HandlerTrigger = void Function([DynamicMap? extraArguments])
Signature of the callback passed to a HandlerGenerator.
LocalWidgetBuilder = Widget Function(BuildContext context, DataSource source)
Signature of builders for local widgets.
RemoteEventHandler = void Function(String eventName, DynamicMap eventArguments)
Signature of the callback passed to a RemoteWidget.
SubscriptionCallback = void Function(Object value)
Signature for the callback passed to DynamicContent.subscribe.

Exceptions / Errors

ParserException
Indicates that there an error was detected while parsing a file.
RemoteFlutterWidgetsException
Used to indicate that there is an error with one of the libraries loaded into the Remote Flutter Widgets Runtime.