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.

CocoaPods

Add the subspec to your Podfile.

pod 'PlayerUI/TypesProviderPlugin'

In your Swift file, import the pod. Only one import is needed for all PlayerUI pods.

import PlayerUI

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"])
)