Class RegionBehaviorTypeAbstract

_source

parent

StaticLOCALIZATION_PREFIXES

class MyDataModel extends foundry.abstract.DataModel {
  static defineSchema() {
    return {
      foo: new foundry.data.fields.StringField(),
      bar: new foundry.data.fields.NumberField()
    };
  }
  static LOCALIZATION_PREFIXES = ["MYMODULE.MYDATAMODEL"];
}

Hooks.on("i18nInit", () => {
  // Foundry will attempt to automatically localize models registered for a document subtype, so this step is only
  // needed for other data model usage, e.g. for a Setting.
  Localization.localizeDataModel(MyDataModel);
});
Copy

{
  "MYMODULE": {
    "MYDATAMODEL": {
      "FIELDS" : {
        "foo": {
          "label": "Foo",
          "hint": "Instructions for foo"
        },
        "bar": {
          "label": "Bar",
          "hint": "Instructions for bar"
        }
      }
    }
  }
}
Copy

invalid

• get invalid(): boolean

  Is the current state of this DataModel invalid? The model is invalid if there is any unresolved failure.

  Returns boolean

schema

• get schema(): DataModelSchemaField

  Define the data schema for this document instance.

  Returns DataModelSchemaField

validationFailures

• get validationFailures(): {
      fields: DataModelValidationFailure
      | null;
      joint: DataModelValidationFailure | null;
  }

  An array of validation failure instances which may have occurred when this instance was last validated.

  Returns {
      fields: DataModelValidationFailure | null;
      joint: DataModelValidationFailure | null;
  }

Staticschema

• get schema(): DataModelSchemaField

  Returns DataModelSchemaField

clone

• clone(
      data?: object,
      context?: DataModelConstructionContext,
  ):
      | DataModel<object, DataModelConstructionContext>
      | Promise<DataModel<object, DataModelConstructionContext>>

  Clone a model, creating a new data model by combining current data with provided overrides.

  Parameters

  • Optionaldata: object = {}

    Additional data which overrides current document data at the time of creation

  • Optionalcontext: DataModelConstructionContext = {}

    Context options passed to the data model constructor

  Returns
      | DataModel<object, DataModelConstructionContext>
      | Promise<DataModel<object, DataModelConstructionContext>>

  The cloned instance

getFieldForProperty

• getFieldForProperty(key: string | string[]): DataField | undefined

  Traverse the data model instance, obtaining the DataField definition for a field of a particular property.

  Parameters

  • key: string | string[]

    A property key like ["abilities", "strength"] or "abilities.strength"

  Returns DataField | undefined

  The corresponding DataField definition for that field, or undefined

onEmbed

• onEmbed(element: HTMLDocumentEmbedElement): void

  Specific callback actions to take when the embedded HTML for this Document has been added to the DOM.

  Parameters

  • element: HTMLDocumentEmbedElement

    The embedded document HTML

  Returns void

prepareBaseData

• prepareBaseData(): void

  Prepare data related to this DataModel itself, before any derived data (including Active Effects) is computed. This is especially useful for initializing numbers, arrays, and sets you expect to be modified by active effects.

  Called before ClientDocument#prepareBaseData in ClientDocument#prepareData.

  Returns void

  Example

  prepareBaseData() {
    // Ensures an active effect of `system.encumbrance.max | ADD | 10` doesn't produce `NaN`
    this.encumbrance = {
      max: 0
    }
    // If you need to access the owning Document, `this.parent` provides a reference for properties like the name
    // or embedded collections, e.g. `this.parent.name` or `this.parent.items`
  }
  Copy

prepareDerivedData

• prepareDerivedData(): void

  Apply transformations or derivations to the values of the source data object. Compute data fields whose values are not stored to the database.

  Called before ClientDocument#prepareDerivedData in ClientDocument#prepareData.

  Returns void

  Example

  prepareDerivedData() {
    this.hp.bloodied = Math.floor(this.hp.max / 2);
  
    // this.parent accesses the Document, allowing access to embedded collections
    this.encumbrance.value = this.parent.items.reduce((total, item) => {
      total += item.system.weight;
      return total;
    }, 0)
  }
  Copy

reset

• reset(): void

  Reset the state of this data instance back to mirror the contained source data, erasing any changes.

  Returns void

toEmbed

• toEmbed(config: DocumentHTMLEmbedConfig, options?: any): Promise<any>

  Convert this Document to some HTML display for embedding purposes.

  Parameters

  • config: DocumentHTMLEmbedConfig

    Configuration for embedding behavior.

  • Optionaloptions: any = {}

    The original enrichment options for cases where the Document embed content also contains text that must be enriched.

  Returns Promise<any>

toJSON

• toJSON(): object

  Extract the source data for the DataModel into a simple object format that can be serialized.

  Returns object

  The document source data expressed as a plain object

toObject

• toObject(source?: boolean): object

  Copy and transform the DataModel into a plain object. Draw the values of the extracted object from the data source (by default) otherwise from its transformed values.

  Parameters

  • Optionalsource: boolean = true

    Draw values from the underlying data source rather than transformed values

  Returns object

  The extracted primitive object

updateSource

• updateSource(changes?: object, options?: DataModelUpdateOptions): object

  Update the DataModel locally by applying an object of changes to its source data. The provided changes are expanded, cleaned, validated, and stored to the source data object for this model. The provided changes argument is mutated in this process. The source data is then re-initialized to apply those changes to the prepared data. The method returns an object of differential changes which modified the original data.

  Parameters

  • changes: object = {}

    New values which should be applied to the data model

  • options: DataModelUpdateOptions = {}

    Options which determine how the new data is merged

  Returns object

  An object containing differential keys and values that were changed

  Throws

  An error if the requested data model changes were invalid

validate

• validate(options?: DataModelValidationOptions): boolean

  Validate the data contained in the document to check for type and content. This method is intended to validate complete model records, verifying both individual field validation as well as joint model validity.

  For validating sets of partial model changes, it is preferred to call DataModel#updateSource as a dryRun. This method provides a convenience alias for such a workflow if changes are provided.

  Warning: if fallback handling is allowed, this process will mutate provided changes or model source data.

  Parameters

  • options: DataModelValidationOptions = {}

    Options which modify how the model is validated

  Returns boolean

  Whether the data source or proposed change is reported as valid. A boolean is always returned if validation is non-strict.

  Throws

  An error thrown if validation is strict and a failure occurs.

StaticcleanData

• cleanData(
      data?: object,
      options?: DataModelCleaningOptions,
      _state?: Partial<data.types.DataModelUpdateState>,
  ): object

  Clean a data source object to conform to a specific provided schema.

  Parameters

  • Optionaldata: object = {}

    Provided model data that requires cleaning

  • Optionaloptions: DataModelCleaningOptions = {}

    Options that configure how data cleaning is performed

  • Optional_state: Partial<data.types.DataModelUpdateState> = {}

    Internal options used during cleaning recursion

  Returns object

  Cleaned data which is suitable for validation and usage

Static AbstractdefineSchema

• defineSchema(): DataSchema

  Define the data schema for models of this type. The schema is populated the first time it is accessed and cached for future reuse.

  The schema, through its fields, provide the essential cleaning, validation, and initialization methods to turn the _source values into direct properties of the data model. The schema is a static property of the model and is reused by all instances to perform validation.

  The schemas defined by the core software in classes like foundry.documents.BaseActor are validated by the server, where user code does not run. However, almost all documents have a flags field to store data, and many have a system field that can be configured to be a foundry.abstract.TypeDataModel instance. Those models are not constructed on the server and rely purely on client-side code, which means certain extra-sensitive fields must be also be registered through your package manifest. foundry.packages.types.ServerSanitizationFields

  Returns DataSchema

  Example

  class SomeModel extends foundry.abstract.DataModel {
    static defineSchema() {
      return {
        foo: new foundry.data.fields.StringField()
      }
    }
  }
  
  class AnotherModel extends SomeModel {
    static defineSchema() {
      // Inheritance and object oriented principles apply to schema definition
      const schema = super.defineSchema()
  
      schema.bar = new foundry.data.fields.NumberField()
  
      return schema;
    }
  }
  Copy

StaticfromJSON

• fromJSON(json: string): DataModel<object, DataModelConstructionContext>

  Create a DataModel instance using a provided serialized JSON string.

  Parameters

  • json: string

    Serialized document data in string format

  Returns DataModel<object, DataModelConstructionContext>

  A constructed data model instance

StaticfromSource

• fromSource(
      source: object,
      context?: Omit<DataModelConstructionContext, "strict"> & DataModelFromSourceOptions,
  ): DataModel<object, DataModelConstructionContext>

  Create a new instance of this DataModel from a source record. The source data is presumed trustworthy and is not strictly validated unless explicitly requested.

  Parameters

  • source: object

    Initial document data which comes from a trusted source.

  • Optionalcontext: Omit<DataModelConstructionContext, "strict"> & DataModelFromSourceOptions = {}

    Model construction context

  Returns DataModel<object, DataModelConstructionContext>

StaticmigrateData

• migrateData(
      source: object,
      options?: Readonly<DataModelCleaningOptions>,
      _state?: data.types.DataModelUpdateState,
  ): object

  Migrate candidate source data for this DataModel which may require initial cleaning or transformations.

  Parameters

  • source: object

    Candidate source data for the module, before further cleaning

  • Optionaloptions: Readonly<DataModelCleaningOptions>

    Additional options for how the field is cleaned

  • Optional_state: data.types.DataModelUpdateState

    Internal state variables which are used during recursion

  Returns object

  Migrated source data, ready for further cleaning

StaticmigrateDataSafe

• migrateDataSafe(
      source: object,
      options?: Readonly<DataModelCleaningOptions>,
  ): object

  Wrap data migration in a try/catch which attempts it safely.

  Parameters

  • source: object

    Candidate source data for the module, before further cleaning

  • Optionaloptions: Readonly<DataModelCleaningOptions> = {}

    Additional options for how the field is cleaned

  Returns object

  Migrated source data, ready for further cleaning

StaticshimData

• shimData(data: object, options?: { embedded?: boolean }): object

  Take data which conforms to the current data schema and add backwards-compatible accessors to it in order to support older code which uses this data.

  Parameters

  • data: object

    Data which matches the current schema

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

    Additional shimming options

    • Optionalembedded?: boolean

      Apply shims to embedded models?

  Returns object

  Data with added backwards-compatible properties, which is the same object as the data argument

StaticvalidateJoint

• validateJoint(data: object): void

  Evaluate joint validation rules which apply validation conditions across multiple fields of the model. Field-specific validation rules should be defined as part of the DataSchema for the model. This method allows for testing aggregate rules which impose requirements on the overall model.

  Parameters

  • data: object

    Candidate data for the model

  Returns void

  Throws

  An error if a validation failure is detected