Document | Foundry Virtual Tabletop - API Documentation

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

Constructors

constructor

new Document(): Document

Inherited from DataModel.constructor
Returns Document

Methods

_configure

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

Inherited from DataModel._configure
override
Parameters
- __namedParameters: { pack: any } = {}
  - pack: any
Returns void

getUserLevel

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

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

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

clone(data?: any, [context={}]?: DocumentConstructionContext): Document | Promise<Document>

Inherited from DataModel.clone

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

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

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

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

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

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

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

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

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

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

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

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

toObject(source?: boolean): any

Inherited from DataModel.toObject

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

Protected _preCreate

_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>

Protected _preUpdate

_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>

Protected _preDelete

_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>

Protected _onCreate

_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

Protected _onUpdate

_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

Protected _onDelete

_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

Static canUserCreate

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?

Static createDocuments

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

Static updateDocuments

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

Static deleteDocuments

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

Static create

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

Static get

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

Static _addDataFieldMigration

_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

Static Protected _onCreateDocuments

_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>

Static Protected _onUpdateDocuments

_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>

Static Protected _onDeleteDocuments

_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>

Static Protected _logDataFieldMigration

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

Parameters
- oldKey: any
- newKey: any
- options: {} = {}
Returns void

Static Protected _logV10CompatibilityWarning

_logV10CompatibilityWarning(options: any): void

Parameters
- options: any
Returns void

Accessors

collectionName

get collectionName(): any

Returns any

documentName

get documentName(): any

Returns any

id

get id(): string

The canonical identifier for this Document.

Returns string

isEmbedded

get isEmbedded(): boolean

Test whether this Document is embedded within a parent Document

Returns boolean

Static database

get database(): DatabaseBackend

The database backend used to execute operations and handle results.

Returns DatabaseBackend

Static implementation

get implementation(): Class

Return a reference to the configured subclass of this base Document type.

Returns Class

Static collectionName

get collectionName(): string

The named collection to which this Document belongs.

Returns string

Static documentName

get documentName(): string

The canonical name of this Document type, for example "Actor".

Returns string

Static hasSystemData

get hasSystemData(): boolean

Does this Document definition include a SystemDataField?

Returns boolean

Properties

Static metadata

metadata: any = ...

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

Hierarchy

Index

Constructors

Methods

Accessors

Properties

Constructors

constructor

Returns Document

Methods

_configure

Parameters

__namedParameters: { pack: any } = {}

pack: any

Returns void

getUserLevel

Parameters

user: BaseUser

Returns number

testUserPermission

Parameters

user: BaseUser

permission: string | number

options: { exact: boolean } = {}

exact: boolean

Returns boolean

canUserModify

Parameters

user: BaseUser

action: string

data: any = {}

Returns boolean

clone

Parameters

data: any = {}

[context={}]: DocumentConstructionContext = {}

Returns Document | Promise<Document>

migrateSystemData

Returns any

update

Parameters

data: any = {}

context: DocumentModificationContext = {}

Returns Promise<Document>

delete

Parameters

context: DocumentModificationContext = {}

Returns Promise<Document>

getEmbeddedCollection

Parameters

embeddedName: string

Returns Collection

getEmbeddedDocument

Parameters

embeddedName: string

id: string

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

strict: boolean

Returns Document

createEmbeddedDocuments

Parameters

embeddedName: string

data: any[] = []

context: DocumentModificationContext = {}

Returns Promise<Document[]>

updateEmbeddedDocuments

Parameters

embeddedName: string

updates: any[] = []

context: DocumentModificationContext = {}

Returns Promise<Document[]>

deleteEmbeddedDocuments

Parameters

embeddedName: string

ids: string[]

context: DocumentModificationContext = {}

Returns Promise<Document[]>

getFlag

Parameters

scope: string