Types Provider

Similar to the Expression Plugin, this plugin adds support for easily exposing new DataTypes, formats, and validations to Player’s content.

Example

Core

Define a new validation type:

import { ValidatorFunction } from "@player-ui/player";

const customValidator: ValidatorFunction = (context, value) => {
  if (value === "bad-value") {
    return {
      message: "This is a bad value.",
    };
  }
};

Create a new DataType that references it:

import { Schema } from "@player-ui/player";

const CustomDataType: Schema.DataType = {
  name: "CustomType",
  validation: [
    {
      type: "custom-validator",
    },
  ],
};

Register it with Player:

import { Player } from "@player-ui/player";
import { TypesProviderPlugin } from "@player-ui/types-provider-plugin";

const player = new Player({
  plugins: [
    new TypesProviderPlugin({
      types: [CustomDataType],
      validations: [["custom-validator", customValidator]],
    }),
  ],
});

Given a data-type reference to CustomType in the content, your new validation will be used:

{
  "schema": {
    "ROOT": {
      "data": {
        "type": "CustomDataType"
      }
    }
  }
}

iOS

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.

Swift Package Manager

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

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

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

import PlayerUITypesProviderPlugin

Swift Usage

Custom Validator

let validationFunction = { context, value, options in
    if value == goodValue {
      return nil // Return nil to pass the validation
    } else {
      return ["message": "This Value is bad!"]
    }
}

let validator = ValidationDeclaration(
  type: "customValidator",
  handler: validationFunction
)

let plugin = TypesProviderPlugin(types: [], validators: [validator], formats: [])

then in the JSON schema for your type:”

"schema": {
    "ROOT": {
      "<yourBinding>": {
        "validation": [
            {"type": "customValidator"}
        ]
      }
    }
  }

Custom Formatter

let formatFunction = {value, options in
  if let stringValue = value as? String {
    return stringValue.replacingOccurrences(of: ".", with: ",") // Turn all periods into commas
  } else {
    return value
  }
}

let formatter = FormatDeclaration(
  name: "customFormatter",
  format: formatFunction,
  deformat: nil
)
let plugin = TypesProviderPlugin(types: [], validators: [], formats: [formatter])

then in the JSON schema for your type:

"schema": {
    "ROOT": {
      "<yourBinding>": {
          "format": {
              "type": "customFormatter"
          }
      }
    }
  }

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:

"format": {
  "type": "customFormatter",
  "character": "X"
}

let formatFunction = {value, options in
  if let stringValue = value as? String {
    let char = options["character"] as? String ?? ","
    return stringValue.replacingOccurrences(of: ".", with: char)
    // Turn all periods into the specified character
  } else {
    return value
  }
}

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 are defined, so when you choose a type like DateType the formatting is already set up.

let type = CustomType(
  type: "CustomType",
  validation: [
    ValidationReference(type: "customValidator")
  ],
  format: FormatReference(type: "customFormatter")
)

// Construct the plugin
let plugin = TypesProviderPlugin(types: [type], validators: [validator], formats: [formatter])

then in your JSON schema:

"schema": {
    "ROOT": {
      "foo": {
        "type": "CustomType"
      }
    }
  }

Options in the CustomType

You can supply options to formatters of your custom type in the ValidationReference or FormatReference:

let type = CustomType(
  type: "CustomType",
  validation: [
    ValidationReference(type: "customValidator")
  ],
  format: FormatReference(type: "customFormatter", options: ["character": "X"])
)