Foundry Virtual Tabletop - API Documentation - Version 14
    Preparing search index...

    Class EmbeddedDataField

    A subclass of foundry.data.fields.DataModelSchemaField used for embedded data models.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    fields model name options parent persisted hierarchical recursive

    Accessors

    fieldPath _defaults hasFormSupport

    Methods

    _applyChangeAdd _cast _cleanType _getField _migrate _updateCommit _updateDiff _validateModel _validateRecursive _validateType [iterator] apply applyChange clean entries extendFields get getField getInitialValue has initialize keys removeFields toFormGroup toInput toObject validate validators values _applyChangeCustom _applyChangeDowngrade _applyChangeMultiply _applyChangeOverride _applyChangeSubtract _applyChangeUpgrade _castChangeDelta _initialize _replaceDataRefs _toInput _validateSpecial _handleValidationFailure expandObject reconstructOperator

    Constructors

    Properties

    fields: DataSchema

    The contained field definitions.

    model: any

    The base DataModel definition which is contained in this field.

    name: string | undefined

    The field name of this DataField instance. This is assigned by SchemaField#initialize.

    options: DataFieldOptions

    The initially provided options which configure the data field

    parent: any

    A reference to the parent schema to which this DataField belongs. This is assigned by SchemaField#initialize.

    persisted: boolean = true

    Is a value of this field written to source data? A Non-persisted value is initialized (with its initial value), and ActiveEffects can use the field for change application.

    hierarchical: boolean = false

    Whether this field defines part of a Document/Embedded Document hierarchy.

    recursive: boolean = true

    Accessors

    • get fieldPath(): string

      A dot-separated string representation of the field path within the parent schema.

      Returns string

    Static_defaults

    • get _defaults(): DataFieldOptions & { nullable: boolean; required: boolean }

      Default parameters for this field type

      Returns DataFieldOptions & { nullable: boolean; required: boolean }

    • get hasFormSupport(): boolean

      Does this form field class have defined form support?

      Returns boolean

    Methods

    _applyChangeAdd

    • _applyChangeAdd(value: any, delta: any, model: any, change: any): any

      Parameters

      • value: any
      • delta: any
      • model: any
      • change: any

      Returns any

    _cast

    _cleanType

    • _cleanType(data: any, options: any, _state: any): any

      Apply any cleaning logic specific to this DataField type.

      Parameters

      • data: any

        A candidate value that has been cast to the appropriate type

      • options: any

        Options for how the field is cleaned

      • _state: any

        Internal state variables which are used during recursion

      Returns any

      The cleaned value

    _getField

    _migrate

    • _migrate(value: any, options: any, _state: any): any

      Parameters

      • value: any
      • options: any
      • _state: any

      Returns any

    _updateCommit

    • _updateCommit(source: any, key: any, value: any, diff: any, options: any): void

      Parameters

      • source: any
      • key: any
      • value: any
      • diff: any
      • options: any

      Returns void

    _updateDiff

    • _updateDiff(key: any, value: any, options: any, state: any): void
      Internal

      Update the source data for a DataModel which includes this DataField. Updates are performed depth-first; validated and recorded from leaf-nodes upwards.

      This method is responsible for preparing and validating the requested update. If the update is valid, it is responsible for updating the pending source copy and recording the diff. If the update is invalid it must avoid recording a diff or staging an update to the source copy. If validation fails, this workflow may optionally permit fallback to a valid initial value.

                                       a partial node of source data, relative to which this field belongs.

      Parameters

      • key: any

        The name of this field within the context of the source data.

      • value: any

        The candidate value that should be applied as an update.

      • options: any

        Options which modify how this update workflow is performed.

      • state: any

        Stateful data that is transacted throughout the model hierarchy during an update operation.

      Returns void

      An error if the requested update cannot be performed.

    _validateModel

    _validateRecursive

    _validateType

    • Iterate over a SchemaField by iterating over its fields.

      Returns Generator<any, void, unknown>

    • Parameters

      • fn: any
      • data: {} = {}
      • options: {} = {}

      Returns {}

    • Apply an ActiveEffectChange to this field.

      Type Parameters

      • T

      Parameters

      • value: T

        The field's current value.

      • model: DataModel

        The model instance.

      • change: EffectChangeData

        The change to apply.

      • options: { replacementData?: Record<string, unknown> } = {}

        Additional options to configure the change application.

        • OptionalreplacementData?: Record<string, unknown>

          Data used to resolve "@" expressions.

      Returns T

      The updated value.

    • Preprocess and clean source data to ensure that it conforms to the correct data type for this field and is ready to be used by data model construction or update operations. Data cleaning is synchronous and automatically applied as the first step of construction and update operations.

      Parameters

      • value: any

        An initial requested value

      • options: {} = {}

        Additional options for how the field is cleaned

      • _state: {} = {}

        Internal state variables which are used during recursion

      Returns any

      The cleaned value

    • Get a DataField instance from the schema by name.

      Parameters

      • fieldName: string

        The field name

      Returns void | DataField

      The DataField instance or undefined

    • Traverse the schema, obtaining the DataField definition for a particular field.

      Parameters

      • pathOrKey: string | string[]

        A field path or property key if options.source is given. Examples: ["abilities", "strength"] or "abilities.strength".

      • Optionaloptions: { source?: object } = {}

        Additional options

        • Optionalsource?: object

          The source data of the field

      Returns DataField | undefined

      The corresponding DataField definition for that field, or undefined

    • Test whether a certain field name belongs to this schema definition.

      Parameters

      • fieldName: string

        The field name

      Returns boolean

      Does the named field exist in this schema?

    • Parameters

      • value: any
      • model: any
      • options: {} = {}

      Returns any

    • An array of field names which are present in the schema.

      Returns string[]

    • Remove fields from this schema definition.

      Parameters

      • fields: string[]

        The fields to remove.

      Returns void

    • Render this DataField as a standardized form-group element.

      Parameters

      • groupConfig: FormGroupConfig = {}

        Configuration options passed to the wrapping form-group

      • inputConfig: FormInputConfig = {}

        Input element configuration options passed to DataField#toInput

      Returns HTMLDivElement

      The rendered form group element

    • Render this DataField as an HTML element.

      Parameters

      Returns HTMLElement | HTMLCollection | HTMLElement[]

      A rendered HTMLElement for the field

      An Error if this DataField subclass does not support input rendering

    • Validate candidate input for this field, ensuring it meets the field requirements.

      This public method validates recursively, testing both the immediate value of this field as well as the validity of any child values for fields with hierarchical data types.

      Parameters

      • value: any

        The candidate value to validate

      • Optionaloptions: DataFieldValidationOptions = {}

        Options which affect validation behavior

      Returns void | DataModelValidationFailure

      A failure that occurred if validation is non-strict. The failure may have been resolved by fallback or dropping invalid elements.

      A failure error type including details of the failure if validation is performed strictly.

    • Iterate over validation functions applied to this field. Validation happens in a depth-first way, for example consider an outerSchema with an innerField:

      Parameters

      Returns Generator<DataFieldValidator, void, unknown>

      outerSchema
        _validateSpecial
        _validateType
        _validateRecursive
        outerSchema.options.validate
          innerField
            _validateSpecial
            _validateType
            innerField.options.validate
            _validateModel
        _validateModel

    Protected_applyChangeCustom

    • _applyChangeCustom(
          value: any,
          delta: any,
          model: DataModel,
          change: EffectChangeData,
      ): any
      Protected

      Apply a custom change to this field.

      Parameters

      • value: any

        The field's current value.

      • delta: any

        The change delta.

      • model: DataModel

        The model instance.

      • change: EffectChangeData

        The original change data.

      Returns any

      The updated value.

    Protected_applyChangeDowngrade

    • _applyChangeDowngrade(
          value: any,
          delta: any,
          model: DataModel,
          change: EffectChangeData,
      ): any
      Protected

      Apply a "downgrade" change to this field.

      Parameters

      • value: any

        The field's current value.

      • delta: any

        The change delta.

      • model: DataModel

        The model instance.

      • change: EffectChangeData

        The original change data.

      Returns any

      The updated value.

    Protected_applyChangeMultiply

    • _applyChangeMultiply(
          value: any,
          delta: any,
          model: DataModel,
          change: EffectChangeData,
      ): any
      Protected

      Apply a "multiply" change to this field.

      Parameters

      • value: any

        The field's current value.

      • delta: any

        The change delta.

      • model: DataModel

        The model instance.

      • change: EffectChangeData

        The original change data.

      Returns any

      The updated value.

    Protected_applyChangeOverride

    • _applyChangeOverride(
          value: any,
          delta: any,
          model: DataModel,
          change: EffectChangeData,
      ): any
      Protected

      Apply an "override" change to this field.

      Parameters

      • value: any

        The field's current value.

      • delta: any

        The change delta.

      • model: DataModel

        The model instance.

      • change: EffectChangeData

        The original change data.

      Returns any

      The updated value.

    Protected_applyChangeSubtract

    • _applyChangeSubtract(
          value: any,
          delta: any,
          model: DataModel,
          change: EffectChangeData,
      ): any
      Protected

      Apply a "subtract" change to this field.

      Parameters

      • value: any

        The field's current value.

      • delta: any

        The change delta.

      • model: DataModel

        The model instance.

      • change: EffectChangeData

        The original change data.

      Returns any

      The updated value.

    Protected_applyChangeUpgrade

    • _applyChangeUpgrade(
          value: any,
          delta: any,
          model: DataModel,
          change: EffectChangeData,
      ): any
      Protected

      Apply an "upgrade" change to this field.

      Parameters

      • value: any

        The field's current value.

      • delta: any

        The change delta.

      • model: DataModel

        The model instance.

      • change: EffectChangeData

        The original change data.

      Returns any

      The updated value.

    Protected_castChangeDelta

    • _castChangeDelta(delta: any, replacementData?: object): any
      Protected

      Cast a change delta into an appropriate type to be applied to this field.

      Parameters

      • delta: any

        The change delta.

      • replacementData: object = {}

        Data used to resolve "@" expressions.

      Returns any

    Protected_initialize

    Protected_replaceDataRefs

    • _replaceDataRefs(
          raw: string,
          data: Record<string, unknown>,
          options?: { strict?: boolean },
      ): string
      Protected

      Recursively replace data references in a string change value.

      Parameters

      • raw: string
      • data: Record<string, unknown>

        An object providing replacements

      • Optionaloptions: { strict?: boolean } = {}

        Additional options to configure the data replacement

        • Optionalstrict?: boolean

          Throw an Error if data replacement fails

      Returns string

      The expression with data references resolved

    Protected_toInput

    • _toInput(config: FormInputConfig): HTMLElement | HTMLCollection | HTMLElement[]
      Protected

      Render this DataField as an HTML element. Subclasses should implement this method rather than the public toInput method which wraps it.

      Parameters

      Returns HTMLElement | HTMLCollection | HTMLElement[]

      A rendered HTMLElement for the field

      An Error if this DataField subclass does not support input rendering

    Protected_validateSpecial

    • _validateSpecial(value: any): boolean | void
      Protected

      Special validation rules which supersede regular field validation. This validator screens for certain values which are otherwise incompatible with this field like null or undefined.

      Parameters

      • value: any

        The candidate value

      Returns boolean | void

      A boolean to indicate with certainty whether the value is valid

      An error with a specific reason the value is invalid

    Static_handleValidationFailure

    • When iterating over the keys and values of an object, reconstruct serialized DataFieldOperator values.

      Parameters

      • data: object
      • k: string
      • v: any

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods