Options
All
  • Public
  • Public/Protected
  • All
Menu

An extension of the base DataModel which defines a Document. Documents are special in that they are persisted to the database and referenced by _id.

memberof

abstract

abstract
param data

Initial data from which to construct the Document

param context

Construction context options

Hierarchy

Index

Constructors

Methods

  • _configure(__namedParameters?: { pack: any }): void
  • override

    Parameters

    • __namedParameters: { pack: any } = {}
      • pack: any

    Returns void

  • getUserLevel(user: BaseUser): number
  • Get the permission level that a specific User has over this Document, a value in CONST.DOCUMENT_OWNERSHIP_LEVELS.

    Parameters

    • user: BaseUser

      The User being tested

    Returns number

    A numeric permission level from CONST.DOCUMENT_OWNERSHIP_LEVELS or null

  • testUserPermission(user: BaseUser, permission: string | number, options?: { exact: boolean }): boolean
  • Test whether a certain User has a requested permission level (or greater) over the Document

    Parameters

    • user: BaseUser

      The User being tested

    • permission: string | number

      The permission level from DOCUMENT_OWNERSHIP_LEVELS to test

    • options: { exact: boolean } = {}

      Additional options involved in the permission test

      • exact: boolean

    Returns boolean

    Does the user have this permission level over the Document?

  • canUserModify(user: BaseUser, action: string, data?: any): boolean
  • Test whether a given User has permission to perform some action on this Document

    Parameters

    • user: BaseUser

      The User attempting modification

    • action: string

      The attempted action

    • data: any = {}

    Returns boolean

    Does the User have permission?

  • clone(data?: any, [context={}]?: DocumentConstructionContext): Document | Promise<Document>
  • Clone a document, creating a new document by combining current data with provided overrides. The cloned document is ephemeral and not yet saved to the database.

    Parameters

    • data: any = {}
    • [context={}]: DocumentConstructionContext = {}

      Additional context options passed to the create method

    Returns Document | Promise<Document>

    The cloned Document instance

  • migrateSystemData(): any
  • For Documents which include game system data, migrate the system data object to conform to its latest data model. The data model is defined by the template.json specification included by the game system.

    Returns any

    The migrated system data object

  • update(data?: any, context?: DocumentModificationContext): Promise<Document>
  • Update this Document using incremental data, saving it to the database.

    see

    Document.updateDocuments

    Parameters

    • data: any = {}
    • context: DocumentModificationContext = {}

    Returns Promise<Document>

    The updated Document instance

  • delete(context?: DocumentModificationContext): Promise<Document>
  • Delete this Document, removing it from the database.

    see

    Document.deleteDocuments

    Parameters

    • context: DocumentModificationContext = {}

    Returns Promise<Document>

    The deleted Document instance

  • getEmbeddedCollection(embeddedName: string): Collection
  • Obtain a reference to the Array of source data within the data object for a certain embedded Document name

    Parameters

    • embeddedName: string

      The name of the embedded Document type

    Returns Collection

    The Collection instance of embedded Documents of the requested type

  • getEmbeddedDocument(embeddedName: string, id: string, [options]?: { strict: boolean }): Document
  • Get an embedded document by it's id from a named collection in the parent document.

    Parameters

    • embeddedName: string

      The name of the embedded Document type

    • id: string

      The id of the child document to retrieve

    • [options]: { strict: boolean } = {}

      Additional options which modify how embedded documents are retrieved

      • strict: boolean

    Returns Document

    The retrieved embedded Document instance, or undefined

  • createEmbeddedDocuments(embeddedName: string, data?: any[], context?: DocumentModificationContext): Promise<Document[]>
  • Create multiple embedded Document instances within this parent Document using provided input data.

    see

    Document.createDocuments

    Parameters

    • embeddedName: string

      The name of the embedded Document type

    • data: any[] = []

      An array of data objects used to create multiple documents

    • context: DocumentModificationContext = {}

    Returns Promise<Document[]>

    An array of created Document instances

  • updateEmbeddedDocuments(embeddedName: string, updates?: any[], context?: DocumentModificationContext): Promise<Document[]>
  • Update multiple embedded Document instances within a parent Document using provided differential data.

    see

    Document.updateDocuments

    Parameters

    • embeddedName: string

      The name of the embedded Document type

    • updates: any[] = []

      An array of differential data objects, each used to update a single Document

    • context: DocumentModificationContext = {}

    Returns Promise<Document[]>

    An array of updated Document instances

  • deleteEmbeddedDocuments(embeddedName: string, ids: string[], context?: DocumentModificationContext): Promise<Document[]>
  • Delete multiple embedded Document instances within a parent Document using provided string ids.

    see

    Document.deleteDocuments

    Parameters

    • embeddedName: string

      The name of the embedded Document type

    • ids: string[]

      An array of string ids for each Document to be deleted

    • context: DocumentModificationContext = {}

    Returns Promise<Document[]>

    An array of deleted Document instances

  • getFlag(scope: string, key: string): any
  • Get the value of a "flag" for this document See the setFlag method for more details on flags

    Parameters

    • scope: string

      The flag scope which namespaces the key

    • key: string

      The flag key

    Returns any

    The flag value

  • setFlag(scope: string, key: string, value: any): Promise<Document>
  • Assign a "flag" to this document. Flags represent key-value type data which can be used to store flexible or arbitrary data required by either the core software, game systems, or user-created modules.

    Each flag should be set using a scope which provides a namespace for the flag to help prevent collisions.

    Flags set by the core software use the "core" scope. Flags set by game systems or modules should use the canonical name attribute for the module Flags set by an individual world should "world" as the scope.

    Flag values can assume almost any data type. Setting a flag value to null will delete that flag.

    Parameters

    • scope: string

      The flag scope which namespaces the key

    • key: string

      The flag key

    • value: any

      The flag value

    Returns Promise<Document>

    A Promise resolving to the updated document

  • unsetFlag(scope: string, key: string): Promise<Document>
  • Remove a flag assigned to the document

    Parameters

    • scope: string

      The flag scope which namespaces the key

    • key: string

      The flag key

    Returns Promise<Document>

    The updated document instance

  • toObject(source?: boolean): any
  • 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

    • source: boolean = true

    Returns any

  • _preCreate(data: any, options: any, user: BaseUser): Promise<void>
  • Perform preliminary operations before a Document of this type is created. Pre-creation operations only occur for the client which requested the operation. Modifications to the pending document before it is persisted should be performed with this.updateSource().

    Parameters

    • data: any

      The initial data object provided to the document creation request

    • options: any

      Additional options which modify the creation request

    • user: BaseUser

      The User requesting the document creation

    Returns Promise<void>

  • _preUpdate(changed: any, options: any, user: BaseUser): Promise<void>
  • Perform preliminary operations before a Document of this type is updated. Pre-update operations only occur for the client which requested the operation.

    Parameters

    • changed: any

      The differential data that is changed relative to the documents prior values

    • options: any

      Additional options which modify the update request

    • user: BaseUser

      The User requesting the document update

    Returns Promise<void>

  • _preDelete(options: any, user: BaseUser): Promise<void>
  • Perform preliminary operations before a Document of this type is deleted. Pre-delete operations only occur for the client which requested the operation.

    Parameters

    • options: any

      Additional options which modify the deletion request

    • user: BaseUser

      The User requesting the document deletion

    Returns Promise<void>

  • _onCreate(data: any, options: any, userId: string): void
  • Perform follow-up operations after a Document of this type is created. Post-creation operations occur for all clients after the creation is broadcast.

    Parameters

    • data: any

      The initial data object provided to the document creation request

    • options: any

      Additional options which modify the creation request

    • userId: string

      The id of the User requesting the document update

    Returns void

  • _onUpdate(changed: any, options: any, userId: string): void
  • Perform follow-up operations after a Document of this type is updated. Post-update operations occur for all clients after the update is broadcast.

    Parameters

    • changed: any

      The differential data that was changed relative to the documents prior values

    • options: any

      Additional options which modify the update request

    • userId: string

      The id of the User requesting the document update

    Returns void

  • _onDelete(options: any, userId: string): void
  • Perform follow-up operations after a Document of this type is deleted. Post-deletion operations occur for all clients after the deletion is broadcast.

    Parameters

    • options: any

      Additional options which modify the deletion request

    • userId: string

      The id of the User requesting the document update

    Returns void

  • canUserCreate(user: BaseUser): boolean
  • Test whether a given User has a sufficient role in order to create Documents of this type in general.

    Parameters

    • user: BaseUser

      The User being tested

    Returns boolean

    Does the User have a sufficient role to create?

  • createDocuments(data?: any[], context?: DocumentModificationContext): Promise<Document[]>
  • Create multiple Documents using provided input data. Data is provided as an array of objects where each individual object becomes one new Document.

    example

    Create a single Document

    const data = [{name: "New Actor", type: "character", img: "path/to/profile.jpg"}];
    const created = await Actor.createDocuments(data);
    example

    Create multiple Documents

    const data = [{name: "Tim", type: "npc"], [{name: "Tom", type: "npc"}];
    const created = await Actor.createDocuments(data);
    example

    Create multiple embedded Documents within a parent

    const actor = game.actors.getName("Tim");
    const data = [{name: "Sword", type: "weapon"}, {name: "Breastplate", type: "equipment"}];
    const created = await Item.createDocuments(data, {parent: actor});
    example

    Create a Document within a Compendium pack

    const data = [{name: "Compendium Actor", type: "character", img: "path/to/profile.jpg"}];
    const created = await Actor.createDocuments(data, {pack: "mymodule.mypack"});

    Parameters

    • data: any[] = []

      An array of data objects used to create multiple documents

    • context: DocumentModificationContext = {}

    Returns Promise<Document[]>

    An array of created Document instances

  • updateDocuments(updates?: any[], context?: DocumentModificationContext): Promise<Document[]>
  • Update multiple Document instances using provided differential data. Data is provided as an array of objects where each individual object updates one existing Document.

    example

    Update a single Document

    const updates = [{_id: "12ekjf43kj2312ds", name: "Timothy"}];
    const updated = await Actor.updateDocuments(updates);
    example

    Update multiple Documents

    const updates = [{_id: "12ekjf43kj2312ds", name: "Timothy"}, {_id: "kj549dk48k34jk34", name: "Thomas"}]};
    const updated = await Actor.updateDocuments(updates);
    example

    Update multiple embedded Documents within a parent

    const actor = game.actors.getName("Timothy");
    const updates = [{_id: sword.id, name: "Magic Sword"}, {_id: shield.id, name: "Magic Shield"}];
    const updated = await Item.updateDocuments(updates, {parent: actor});
    example

    Update Documents within a Compendium pack

    const actor = await pack.getDocument(documentId);
    const updated = await Actor.updateDocuments([{_id: actor.id, name: "New Name"}], {pack: "mymodule.mypack"});

    Parameters

    • updates: any[] = []

      An array of differential data objects, each used to update a single Document

    • context: DocumentModificationContext = {}

    Returns Promise<Document[]>

    An array of updated Document instances

  • deleteDocuments(ids?: string[], context?: DocumentModificationContext): Promise<Document[]>
  • Delete one or multiple existing Documents using an array of provided ids. Data is provided as an array of string ids for the documents to delete.

    example

    Delete a single Document

    const tim = game.actors.getName("Tim");
    const deleted = await Actor.deleteDocuments([tim.id]);
    example

    Delete multiple Documents

    const tim = game.actors.getName("Tim");
    const tom = game.actors.getName("Tom");
    const deleted = await Actor.deleteDocuments([tim.id, tom.id]);
    example

    Delete multiple embedded Documents within a parent

    const tim = game.actors.getName("Tim");
    const sword = tim.items.getName("Sword");
    const shield = tim.items.getName("Shield");
    const deleted = await Item.deleteDocuments([sword.id, shield.id], parent: actor});
    example

    Delete Documents within a Compendium pack

    const actor = await pack.getDocument(documentId);
    const deleted = await Actor.deleteDocuments([actor.id], {pack: "mymodule.mypack"});

    Parameters

    • ids: string[] = []

      An array of string ids for the documents to be deleted

    • context: DocumentModificationContext = {}

    Returns Promise<Document[]>

    An array of deleted Document instances

  • create(data: any, context?: DocumentModificationContext): Promise<Document>
  • Create a new Document using provided input data, saving it to the database.

    see

    Document.createDocuments

    example

    Create a World-level Item

    const data = [{name: "Special Sword", type: "weapon"}];
    const created = await Item.create(data);
    example

    Create an Actor-owned Item

    const data = [{name: "Special Sword", type: "weapon"}];
    const actor = game.actors.getName("My Hero");
    const created = await Item.create(data, {parent: actor});
    example

    Create an Item in a Compendium pack

    const data = [{name: "Special Sword", type: "weapon"}];
    const created = await Item.create(data, {pack: "mymodule.mypack"});

    Parameters

    • data: any
    • context: DocumentModificationContext = {}

    Returns Promise<Document>

    The created Document instance

  • get(documentId: string): any
  • Get a World-level Document of this type by its id.

    Parameters

    • documentId: string

      The Document ID

    Returns any

    The retrieved Document, or null

  • _addDataFieldMigration(data: any, oldKey: string, newKey: string, apply: ((arg0: any, arg1: any) => any)): void
  • Define a simple migration from one field name to another. The value of the data can be transformed during the migration by an optional application function.

    internal

    Parameters

    • data: any

      The data object being migrated

    • oldKey: string

      The old field name

    • newKey: string

      The new field name

    • apply: ((arg0: any, arg1: any) => any)
        • (arg0: any, arg1: any): any
        • Parameters

          • arg0: any
          • arg1: any

          Returns any

    Returns void

  • _onCreateDocuments(documents: Document[], context: DocumentModificationContext): Promise<void>
  • Perform follow-up operations when a set of Documents of this type are created. This is where side effects of creation should be implemented. Post-creation side effects are performed only for the client which requested the operation.

    Parameters

    • documents: Document[]

      The Document instances which were created

    • context: DocumentModificationContext

      The context for the modification operation

    Returns Promise<void>

  • _onUpdateDocuments(documents: Document[], context: DocumentModificationContext): Promise<void>
  • Perform follow-up operations when a set of Documents of this type are updated. This is where side effects of updates should be implemented. Post-update side effects are performed only for the client which requested the operation.

    Parameters

    • documents: Document[]

      The Document instances which were updated

    • context: DocumentModificationContext

      The context for the modification operation

    Returns Promise<void>

  • _onDeleteDocuments(documents: Document[], context: DocumentModificationContext): Promise<void>
  • Perform follow-up operations when a set of Documents of this type are deleted. This is where side effects of deletion should be implemented. Post-deletion side effects are performed only for the client which requested the operation.

    Parameters

    • documents: Document[]

      The Document instances which were deleted

    • context: DocumentModificationContext

      The context for the modification operation

    Returns Promise<void>

  • _logDataFieldMigration(oldKey: any, newKey: any, options?: {}): void
  • Parameters

    • oldKey: any
    • newKey: any
    • options: {} = {}

      Returns void

    • _logV10CompatibilityWarning(options: any): void
    • Parameters

      • options: any

      Returns void

    Accessors

    • get collectionName(): any
    • Returns any

    • get documentName(): any
    • Returns any

    • get id(): string
    • The canonical identifier for this Document.

      Returns string

    • get isEmbedded(): boolean
    • Test whether this Document is embedded within a parent Document

      Returns boolean

    • get database(): DatabaseBackend
    • The database backend used to execute operations and handle results.

      Returns DatabaseBackend

    • get implementation(): Class
    • Return a reference to the configured subclass of this base Document type.

      Returns Class

    • get collectionName(): string
    • The named collection to which this Document belongs.

      Returns string

    • get documentName(): string
    • The canonical name of this Document type, for example "Actor".

      Returns string

    • get hasSystemData(): boolean
    • Does this Document definition include a SystemDataField?

      Returns boolean

    Properties

    metadata: any = ...

    Default metadata which applies to each instance of this Document type.