Expression

This plugin assists with exposing custom expressions to Player content. See ExpressionEvaluator for the runtime engine these handlers are registered with.

Usage

Core

Define handlers for the expressions you wish to add:

import {
  ExpressionHandler,
  ExpressionContext,
} from "@player-ui/expression-plugin";

const customExpressionHandler: ExpressionHandler = (ctx: ExpressionContext) => {
  return "Hello World!";
};

Register with Player. Subsequent registrations of an expression with the same name will override previous values.

import { Player } from "@player-ui/player";
import { ExpressionPlugin } from "@player-ui/expression-plugin";

const player = new Player({
  plugins: [
    new ExpressionPlugin([["myCustomFunction", customExpressionHandler]]),
  ],
});

Any calls to myCustomFunction() within the flow will utilize the newly registered expression:

{
  "asset": {
    "id": "sample",
    "type": "text",
    "value": "@[ myCustomFunction() ]@"
  }
}

Android

The ExpressionPlugin enables consumers to register custom expressions in native JVM code. Simply supply a map of expression name to handler on instantiation, and the expressions will be available within the content. Handlers receive arguments are as a List<Any?> and are permitted to return Any?.

Usage

In build.gradle

implementation "com.intuit.playerui.plugins:expression:$PLAYER_VERSION"

In Player constructor

import com.intuit.playerui.plugins.expression.ExpressionPlugin

val expressionPlugin = ExpressionPlugin(
     "hello" to { args: List<Any?> ->
        when (val name = args.firstOfNull()) {
            null -> "goodbye"
            else -> "hello $name"
        }
    }
)
AndroidPlayer(expressionPlugin)

In Player content

{
  "id": "hello-world-text",
  "type": "text",
  "value": "@[hello('world')]@"
}

iOS

Swift Package Manager

Add the product to the appropriate target's dependencies in your Package.swift.

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "PlayerUIExpressionPlugin", package: "playerui-swift-package"),
    ]
)

In your Swift file, import the sub-package. A different import is needed for each PlayerUI sub-package.

import PlayerUIExpressionPlugin

Swift Usage

The ExpressionPlugin lets you register custom expressions to run native code:

{
  "id": "textAsset",
  "type": "text",
  "value": "@[ myExpression() ]@"
}

let expressionPlugin = ExpressionPlugin(expressions: [
  "myExpression": { _ in
      return "Some Value"
  }
])

Arguments

Arguments can be passed to custom expressions, and your handler receives the arguments as an array of Any:

{
  "id": "textAsset",
  "type": "text",
  "value": "@[ myExpression('world') ]@"
}

let expressionPlugin = ExpressionPlugin(expressions: [
  "myExpression": { (args: [Any]) -> Any? in
      guard let string = args.first as? String else { return nil }
      return "Hello " + string
  }
])