diff --git a/docs/site/pages/plugins/beacon.mdx b/docs/site/pages/plugins/beacon.mdx index 7b6f9e527..ab0213ed9 100644 --- a/docs/site/pages/plugins/beacon.mdx +++ b/docs/site/pages/plugins/beacon.mdx @@ -32,6 +32,8 @@ interface DefaultBeacon { } ``` +## Usage + @@ -94,6 +96,15 @@ This will add additional React Context to the running player for the producers f +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/BeaconPlugin' +``` + +### Swift Usage + To receive Beacon events from Player in iOS, add the `BeaconPlugin` to your plugin array: ```swift @@ -102,7 +113,7 @@ var body: some View { flow: flow, plugins: [ BeaconPlugin { (beacon: DefaultBeacon) in - // Process beacon into the format you need for Segment/Trinity and send it on + // Process beacon into the format you need for your analytics platform } ] ) @@ -264,6 +275,8 @@ export const Component = (props) => { +The SwiftUIBeaconPlugin attaches a BeaconContext to the root of the SwiftUI view tree as an environment value, so when included any asset can use that context to send a beacon, if the context is in the environment: + ```swift struct ActionAssetView: View { @ObservedObject var viewModel: AssetViewModel @@ -275,4 +288,4 @@ struct ActionAssetView: View { ``` - \ No newline at end of file + diff --git a/docs/site/pages/plugins/check-path.mdx b/docs/site/pages/plugins/check-path.mdx index 8a20154c0..dec30f3e8 100644 --- a/docs/site/pages/plugins/check-path.mdx +++ b/docs/site/pages/plugins/check-path.mdx @@ -63,6 +63,34 @@ const rp = new ReactPlayer({ This will automatically create the underlying _core_ version of the `CheckPathPlugin` to be made available via `React` Context for the hooks. + + + +### CocoaPods + +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/SwiftUICheckPathPlugin' +``` + +### Swift Usage + +This plugin takes no parameters, and the configuration comes from content, it can just be added to the plugin array: + +```swift +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + SwiftUICheckPathPlugin() + ], + result: $resultBinding + ) +} +``` + + @@ -149,6 +177,30 @@ export const MyAsset = ({ id }) => { ``` + + +### Swift Usage + +The SwiftUICheckPathPlugin attaches the `BaseCheckPathPlugin` named `checkPath` to the root of the SwiftUI view tree as an environment value, so when included any asset can use that environment value to access the base functionality + +```swift + +struct MyAsset: View { + @ObservedObject var viewModel: AssetViewModel + @Environment(\.checkPath) var checkPath + + var body: some View { + let isInForm = checkPath?.hasParentContext(id: viewModal.data.id, query: "form") + if isInForm { + SelectChoice() + } else { + RadioGroup() + } +} + +``` + + diff --git a/docs/site/pages/plugins/common-expressions.mdx b/docs/site/pages/plugins/common-expressions.mdx index e1fd256b8..17b2566e6 100644 --- a/docs/site/pages/plugins/common-expressions.mdx +++ b/docs/site/pages/plugins/common-expressions.mdx @@ -9,6 +9,64 @@ This plugin exposes some basic expressions into Player content. It also serves as a good reference to adding your own custom expressions into Player. +## Usage + + + + +Install the plugin: + +```bash +yarn add @player-ui/common-types-plugin +``` + +Add it to Player: +```js +import CommonExpressionsPlugin from '@player-ui/common-expressions-plugin'; + +const commonExpressionsPlugin = new CommonExpressionsPlugin(); +const player = new Player({ plugins: [commonExpressionsPlugin] }); + +// Start your flow +player.start(myFlow); +``` + +This will allow any included expressions or custom expressions to be used in the content + + + + + +### CocoaPods + +Add the subspec to your `Podfile` + +```ruby + +pod 'PlayerUI/CommonExpressionsPlugin' + +``` + +### Swift Usage + +This plugin takes no parameters, and the configuration comes from content, it can just be added to the plugin array: + +```swift + +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + CommonExpressionsPlugin() + ], + result: $resultBinding + ) +} +``` + + + + --- ## General diff --git a/docs/site/pages/plugins/common-types.mdx b/docs/site/pages/plugins/common-types.mdx index 456fc0777..881d7ba8b 100644 --- a/docs/site/pages/plugins/common-types.mdx +++ b/docs/site/pages/plugins/common-types.mdx @@ -9,7 +9,65 @@ This plugin exposes some basic `DataTypes`, `validations`, and `formats` into Pl It also serves as a good reference to adding your own custom types into Player. ---- +## Usage + + + + +Install the plugin: + +```bash +yarn add @player-ui/common-types-plugin +``` + +Add it to Player: +```js +import CommonTypesPlugin from '@player-ui/common-types-plugin'; + +const commonTypesPlugin = new CommonTypesPlugin(); +const player = new Player({ plugins: [commonTypesPlugin] }); + +// Start your flow +player.start(myFlow); +``` + +This will allow any `DataTypes`, `formats`, `validations` and custom data types to be used in the content + + + + + +### CocoaPods + +Add the subspec to your `Podfile` + +```ruby + +pod 'PlayerUI/CommonTypesPlugin' + +``` + +### Swift Usage + +This plugin takes no parameters, and the configuration comes from content, it can just be added to the plugin array: + +```swift + +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + CommonTypesPlugin() + ], + result: $resultBinding + ) +} +``` + + + + + ## Formats @@ -313,4 +371,4 @@ Options: > A value representing a phone number * **validations**: `phone` -* **format**: `phone` (`(###) ###-####`) \ No newline at end of file +* **format**: `phone` (`(###) ###-####`) diff --git a/docs/site/pages/plugins/computed-properties.mdx b/docs/site/pages/plugins/computed-properties.mdx index c7c4b0dcc..709887501 100644 --- a/docs/site/pages/plugins/computed-properties.mdx +++ b/docs/site/pages/plugins/computed-properties.mdx @@ -25,6 +25,33 @@ const player = new Player({ ``` + + + +### CocoaPods + +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/ComputedPropertiesPlugin' +``` + +### Swift Usage + +This plugin takes no parameters, and the configuration comes from content, it can just be added to the plugin array: + +```swift +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + ComputedPropertiesPlugin() + ], + result: $resultBinding + ) +} +``` + ## Expression Data Type @@ -62,4 +89,4 @@ Any data-lookup for that binding path will evaluate the given expression and ret Using the above schema, any reference to `{{foo.computedValue}}` will compute the `1 + 2 + 3` expression and use that as the underlying value for that path. -Any write or set operation to `{{foo.computedValue}}` will result in a thrown exception for writing to a read-only path. \ No newline at end of file +Any write or set operation to `{{foo.computedValue}}` will result in a thrown exception for writing to a read-only path. diff --git a/docs/site/pages/plugins/console-logger.mdx b/docs/site/pages/plugins/console-logger.mdx index b8458f0cb..d50835e00 100644 --- a/docs/site/pages/plugins/console-logger.mdx +++ b/docs/site/pages/plugins/console-logger.mdx @@ -34,23 +34,28 @@ consoleLogger.setSeverity('warn'); -Add the subspec: +### CocoaPods +Add the subspec to your `Podfile` ```ruby pod 'PlayerUI/PrintLoggerPlugin' ``` -Construct the plugin: +### Swift Usage ```swift -SwiftUIPlayer( - flow: flow, - plugins: [PrintLoggerPlugin()], - result: $result -) +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + PrintLoggerPlugin() + ], + result: $resultBinding + ) +} ``` -To change the severity: +To change the severity, supply it as an argument to the constructor: ```swift PrintLoggerPlugin(level: .warn) ``` diff --git a/docs/site/pages/plugins/expression.mdx b/docs/site/pages/plugins/expression.mdx index feec6e1d8..778a6e24f 100644 --- a/docs/site/pages/plugins/expression.mdx +++ b/docs/site/pages/plugins/expression.mdx @@ -52,7 +52,14 @@ Any calls to `myCustomFunction()` within the flow will utilize the newly registe -### Use +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/ExpressionPlugin' +``` + +### Swift Usage The ExpressionPlugin lets you register custom expressions to run native code: @@ -71,7 +78,7 @@ let expressionPlugin = ExpressionPlugin(expressions: [ } ]) ``` -### Arguments +#### Arguments Arguments can be passed to custom expressions, and your handler receives the arguments as an array of Any: diff --git a/docs/site/pages/plugins/external-action-view-modifier.mdx b/docs/site/pages/plugins/external-action-view-modifier.mdx index 380d0b0b6..4c1240656 100644 --- a/docs/site/pages/plugins/external-action-view-modifier.mdx +++ b/docs/site/pages/plugins/external-action-view-modifier.mdx @@ -7,7 +7,14 @@ platform: ios This plugin is used to handle EXTERNAL states, allowing you to asynchronously tell Player when, and what to transition with once you have finished processing the external state request. -## Example +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/ExternalActionViewModifierPlugin' +``` + +### Swift Usage For an example flow with an external state such as: @@ -43,7 +50,7 @@ For an example flow with an external state such as: } ``` -The plugin can be declared to handle this external state: +The plugin can be declared to handle this external state by showing some user interface, and letting the user trigger the transition to the next state: ```swift let plugin = ExternalActionViewModifierPlugin { state, options, transition in @@ -55,10 +62,18 @@ let plugin = ExternalActionViewModifierPlugin { stat ) } -let player = SwiftUIPlayer(flow: json, plugins: [plugin]) +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + plugin + ], + result: $resultBinding + ) +} ``` -## ExternalStateViewModifier +#### ExternalStateViewModifier `ExternalStateSheetModifier` is a provided modifier to present the external content with the `.sheet` SwiftUI ViewModifier, however, you can easily define your own. diff --git a/docs/site/pages/plugins/external-action.mdx b/docs/site/pages/plugins/external-action.mdx index 420f63ab7..9b26ca89f 100644 --- a/docs/site/pages/plugins/external-action.mdx +++ b/docs/site/pages/plugins/external-action.mdx @@ -48,6 +48,15 @@ This will transition any `EXTERNAL` state in Player's navigation, with a `ref` p +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/ExternalActionPlugin' +``` + +### Swift Usage + For an example flow with an external state such as: ```json @@ -82,7 +91,7 @@ For an example flow with an external state such as: } ``` -The plugin can be declared to handle this external state: +The plugin can be declared to handle this external state, whether that means integrating an existing platform native experience, or doing headless processing: ```swift let plugin = ExternalActionPlugin { state, options, transition in @@ -96,7 +105,15 @@ let plugin = ExternalActionPlugin { state, options, transition in transition(transitionValue ?? "Next") } -let player = Player(plugins: [plugin]) +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + plugin + ], + result: $resultBinding + ) +} ``` diff --git a/docs/site/pages/plugins/metrics.mdx b/docs/site/pages/plugins/metrics.mdx index 0d4cdee03..4a61ae00f 100644 --- a/docs/site/pages/plugins/metrics.mdx +++ b/docs/site/pages/plugins/metrics.mdx @@ -68,22 +68,31 @@ const player = new ReactPlayer({ -The `ios` version of the Metrics Plugin will track initial render time for each view in a flow. Due to current SwiftUI limitations, update time can't be tracked yet. It should be used in conjunction with a core plugin that utilizes the events. +The `ios` version of the Metrics Plugin will track initial render time for each view in a flow. Due to current SwiftUI limitations, update time can't be tracked yet. It can be used in conjunction with a core plugin that utilizes the events, through `findPlugin`, or standalone. + +### CocoaPods +Add the subspec to your `Podfile` -Add the subspec: ```ruby pod 'PlayerUI/MetricsPlugin' +``` -Construct the plugin: - +### Swift Usage ```swift -SwiftUIPlayer( - flow: flow, - plugins: [MetricsPlugin()], - result: $result -) +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + // Tracking render time can be controlled with a parameter + MetricsPlugin(trackRenderTime: true) { timing, nodeMetrics, flowMetrics in + // Handle metrics payload + log(timing.duration ?? -1) + } + ], + result: $resultBinding + ) +} ``` - diff --git a/docs/site/pages/plugins/partial-match-fingerprint.mdx b/docs/site/pages/plugins/partial-match-fingerprint.mdx index 27387b042..67c0ed8c9 100644 --- a/docs/site/pages/plugins/partial-match-fingerprint.mdx +++ b/docs/site/pages/plugins/partial-match-fingerprint.mdx @@ -1,6 +1,6 @@ --- title: Partial Match -platform: core +platform: core, ios --- # Partial Match Plugin @@ -43,4 +43,27 @@ Query the plugin for matches: const value = matchPlugin.get('asset-id') // 'ABC' ``` + + +This plugin is used by `BaseAssetRegistry` to handle matching resolved asset nodes with their native implementation, to decode for rendering. It is unlikely to be needed to be used directly in iOS use cases. + +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI' +``` + +### Swift Usage +```swift +let plugin = PartialMatchFingerprintPlugin() + +// iOS usage links the array position of a registered asset to its requested match object +// The JavaScript part of this plugin will populate matches when the view is resolving +plugin.register(match: ["type": "text"], index: 1) + +// get the index for the asset with matching ID if it was resolved in the core plugin +plugin.get(assetId: "test") +``` + \ No newline at end of file diff --git a/docs/site/pages/plugins/pub-sub.mdx b/docs/site/pages/plugins/pub-sub.mdx index d724d53b7..0061bc2ab 100644 --- a/docs/site/pages/plugins/pub-sub.mdx +++ b/docs/site/pages/plugins/pub-sub.mdx @@ -38,8 +38,16 @@ pubsub.unsubscribe(token); -If your content uses the `@[ publish() ]@` expression for actions, you can subscribe to these events by adding the `PubSubPlugin` to your plugin array: +If your content uses the `@[ publish() ]@` expression for actions, you can subscribe to these events by using the `PubSubPlugin`. +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/PubSubPlugin' +``` + +### Swift Usage ```swift let eventHandler: (String, AnyType?) -> Void = { (eventName, eventData) in // Handle event @@ -47,12 +55,25 @@ let eventHandler: (String, AnyType?) -> Void = { (eventName, eventData) in let plugin = PubSubPlugin([("eventName", eventHandler)]) ``` -If your content uses a different name for publishing (such as publishEvent) you can customize the expression name that the plugin uses: +If your content uses a different name for publishing (such as `publishEvent`) you can customize the expression name that the plugin uses: ```swift let plugin = PubSubPlugin([("eventName", eventHandler)], options: PubSubPluginOptions(expressionName: "publishEvent")) ``` +Then, just include it in your `plugins` to a Player instance: +```swift +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + plugin + ], + result: $resultBinding + ) +} +``` + _Note: AnyType is a custom enum type to handle the arbitrary types that can be received from these events, as the data is set in your Player Content, ensure that it matches either String, [String], or [String: String]._ diff --git a/docs/site/pages/plugins/stage-revert-data.mdx b/docs/site/pages/plugins/stage-revert-data.mdx index 8eab2303a..3275dfdc9 100644 --- a/docs/site/pages/plugins/stage-revert-data.mdx +++ b/docs/site/pages/plugins/stage-revert-data.mdx @@ -1,6 +1,6 @@ --- title: Stage Revert Data -platform: core +platform: core,ios --- # Stage Rvert Data @@ -44,4 +44,27 @@ const player = new Player({ ``` + + +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/StageRevertDataPlugin' +``` + +### Swift Usage +This plugin takes no parameters, and the configuration comes from content, it can just be added to the plugin array: +```swift +var body: some View { + SwiftUIPlayer( + flow: flow, + plugins: [ + StageRevertDataPlugin() + ], + result: $resultBinding + ) +} +``` + \ No newline at end of file diff --git a/docs/site/pages/plugins/swiftui-pending-transaction.mdx b/docs/site/pages/plugins/swiftui-pending-transaction.mdx index 472067428..cceb54f61 100644 --- a/docs/site/pages/plugins/swiftui-pending-transaction.mdx +++ b/docs/site/pages/plugins/swiftui-pending-transaction.mdx @@ -7,6 +7,12 @@ platform: ios The `SwiftUIPendingTransactionPlugin` allows you to register pending transactions (callbacks) in the userInfo on the decoder. Users can decide when to register, commit and clear transactions based on the use case. Anytime there is a scenario where we want a native transaction to happen while a view update is taking place, we can make use of this plugin. Below is an example used in the sample app where we can see this take place: +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/SwiftUIPendingTransactionPlugin' +``` ## **The Issue:** diff --git a/docs/site/pages/plugins/transition.mdx b/docs/site/pages/plugins/transition.mdx index a0b768ad8..c7c26a38b 100644 --- a/docs/site/pages/plugins/transition.mdx +++ b/docs/site/pages/plugins/transition.mdx @@ -7,18 +7,19 @@ platform: ios The `TransitionPlugin` allows for specifying transitions for when Player loads a flow, and for transition between views in the same flow. -## Usage - -Add the optional subspec to your Podfile or podspec: +### CocoaPods +Add the subspec to your `Podfile` ```ruby pod 'PlayerUI/TransitionPlugin' ``` + +### Swift Usage ```swift SwiftUIPlayer(flow: flowString, plugins: [TransitionPlugin(popTransition: .pop)], result: $resultBinding) ``` -## Customizing Transitions +#### Customizing Transitions To specify different transition, just supply a `PlayerViewTransition` to the plugin initializer: @@ -34,7 +35,7 @@ let plugin = TransitionPlugin( ) ``` -## Default Transitions +#### Default Transitions By default there are 5 transitions included with the `SwiftUIPlayer`: diff --git a/docs/site/pages/plugins/types-provider.mdx b/docs/site/pages/plugins/types-provider.mdx index ea38634a9..809dc613e 100644 --- a/docs/site/pages/plugins/types-provider.mdx +++ b/docs/site/pages/plugins/types-provider.mdx @@ -76,12 +76,21 @@ Given a data-type reference to `CustomType` in the content, your new validation -A wrapper is provided for the types-provider plugin for Core Player. This allows the use of Swift code to create custom types, validators, and formatters. +The swift `TypesProviderPlugin` enables adding custom data types, formatters and validation purely through swift code. While in general, the recommendation would be to share a single JavaScript implementation to multiple platforms, some use cases may need a native integration. -## Custom Validator +### CocoaPods +Add the subspec to your `Podfile` + +```ruby +pod 'PlayerUI/TypesProviderPlugin' +``` + +### Swift Usage + +#### Custom Validator ```swift -let validationFunction = {context, value, options in +let validationFunction = { context, value, options in if value == goodValue { return nil // Return nil to pass the validation } else { @@ -111,7 +120,7 @@ then in the JSON schema for your type:'' } ``` -## Custom Formatter +#### Custom Formatter ```swift let formatFunction = {value, options in @@ -144,7 +153,7 @@ then in the JSON schema for your type: } ``` -### Formatting Options +##### Formatting Options The second parameter passed to the format/deformat functions is for additional options, it is of type `[String: Any]` and contains any other keys that were passed alongside the `type` of the formatter: @@ -167,7 +176,7 @@ let formatFunction = {value, options in } ``` -## Custom Types +#### Custom Types Just as you can define custom formats and validation, you can define a custom type that encapsulates that functionality into a type, to avoid the need to keep specifying options, this is how the [common-types](./plugins/common-types) are defined, so when you choose a type like `DateType` the formatting is already set up. @@ -196,7 +205,7 @@ then in your JSON schema: } ``` -### Options in the CustomType +##### Options in the CustomType You can supply options to formatters of your custom type in the `ValidationReference` or `FormatReference`: