fantasycalendar / FoundryVTT-Tagger

Other
6 stars 4 forks source link

Tagger

Latest Release Download Count Forge Installs Foundry Core Minimum Version Foundry Core Verified Version Latest Version


Fantasy Computerworks Logo

A module made by Fantasy Computerworks.

Other works by us:

Like what we've done? Buy us a coffee!

Buy Me a Coffee at ko-fi.com


What is Tagger?

This module allows you to put unique tags on objects in scenes and use Tagger's powerful API to quickly retrieve them.

Supported Modules

Download

https://github.com/fantasycalendar/FoundryVTT-Tagger/releases/latest/download/module.json

Or if you want to try experimental features:

https://raw.githubusercontent.com/fantasycalendar/FoundryVTT-Tagger/next/module.json

Dialogs

All major PlaceableObjects' configuration dialogues (such as actor prototype tokens, tokens, tiles, walls, lights, etc), now has a "Tags" field.

Each tag is separated by a comma.

img.png

Documentation

Functions

Tagger.getByTag(inTags, inOptions)Array

Gets PlaceableObjects with matching tags provided to the method

Tagger.hasTags(inObject, inTags, inOptions)Boolean

Verifies whether a given PlaceableObject or Document has the tags given

Tagger.getTags(inObject)Array

Gets all tags from a given PlaceableObject or Document

Tagger.setTags(inObjects, inTags)Promise

Set the tags on an PlaceableObject or Document, completely overwriting existing tags on the object

Tagger.toggleTags(inObjects, inTags)Promise

Toggles the tags on an PlaceableObject or Document. If a tag is present, it will be removed. If it not present, it will be added.

Tagger.addTags(inObjects, inTags)Promise

Adds tags to an object

Tagger.removeTags(inObjects, inTags)Promise

Removes tags from an object

Tagger.clearAllTags(inObjects)Promise

Removes all tags from PlaceableObjects

Tagger.applyTagRules(inObjects)Promise

Applies all tag rules to every tag found on the given PlaceableObjects

Tag Rules

Tag rules that are applied on object creation.

Tagger.getByTag(inTags, inOptions) ⇒ Array

Examples:

// Find objects whose tags contain "tag_to_find"
const objects = Tagger.getByTag("tag_to_find");

// Find objects with JUST and ONLY the tag "tag_to_find"
const objects = Tagger.getByTag("tag_to_find", { matchExactly: true });

Gets PlaceableObjects with matching tags provided to the method

Returns: Array - Returns an array of filtered Documents based on the tags

Param Type Description
inTags String/RegExp/Array.<String/RegExp> An array of tags or a string of tags (separated by commas) that will be searched for
inOptions Object An optional object that can contain any of the following:
- matchAny {Boolean} - whether the PlaceableObjects can contain any of the provided tags
- matchExactly {Boolean} - whether the tags on the PlaceableObjects must contain ONLY the tags provided
- caseInsensitive {Boolean} - whether the search is case insensitive (capitals vs lowercase is not considered)
- allScenes {Boolean} - whether to search in all scenes, this will return an object with the key as the scene ID, and an array for objects found within that scene
- objects {Array} - an array of PlaceableObjects to test
- ignore {Array} - an array of PlaceableObjects to ignore
- sceneId {String} - a string ID for the scene to search in

Tagger.hasTags(inObject, inTags, inOptions) ⇒ Boolean

Examples:

// Whether the selected token has the tag "tag_to_find"
const objects = Tagger.hasTags(token, "tag_to_find");

// Whether the token has a tag that resembles "tag_to_find" or "TAG_TO_FIND" or "tAg_To_FiNd"
const objects = Tagger.hasTags(token, "TAG_to_FIND", { caseInsensitive: true });

Verifies whether a given PlaceableObject or Document has the tags given

Returns: Boolean - Returns a boolean whether the object has the given tags

Param Type Description
inObject PlaceableObject A PlaceableObject, or an array of PlaceableObjects to check for tags on
inTags String/Array An array of tags or a string of tags (separated by commas) that will be searched for
inOptions Object An optional object that can contain any of the following:
- matchAny {Boolean} - whether the PlaceableObjects can contain any of the provided tags
- matchExactly {Boolean} - whether the tags on the PlaceableObjects must contain ONLY the tags provided
- caseInsensitive {Boolean} - whether the search is case insensitive (capitals vs lowercase is not considered)

Tagger.getTags(inObject) ⇒ Array

Examples:

// If the token has several tags, this method will return all of those tags as an array
const tags = Tagger.getTags(token);

Gets all tags from a given PlaceableObject or Document

Returns: Array - An array of tags from the Document

Param Type Description
inObject PlaceableObject The PlaceableObject or Document get tags from

Tagger.setTags(inObjects, inTags) ⇒ Promise

Examples:

// Sets the tags on the token to be ONLY "tag_to_set"
await Tagger.setTags(token, "tag_to_set");

// You can also set multiple tags with an array
await Tagger.setTags(token, ["tag_to_set", "tag_to_also_set"]);

// Or as a string with each tag separated with a comma
await Tagger.setTags(token, "tag_to_set, tag_to_also_set");

Set the tags on an PlaceableObject or Document, completely overwriting existing tags on the object

Returns: Promise - A promise that will resolve when the PlaceableObjects' tags have been updated

Param Type Description
inObjects PlaceableObject/Array A PlaceableObject, or an array of PlaceableObjects to set tags on
inTags String/Array An array of tags or a string of tags (separated by commas) that will override all tags on the PlaceableObjects

Tagger.toggleTags(inObjects, inTags) ⇒ Promise

Examples:

// If the token had the tag "tag_to_toggle", it no longer has it
await Tagger.toggleTags(token, "tag_to_toggle");

// You can also toggle multiple tags with an array
await Tagger.toggleTags(token, ["tag_to_toggle", "tag_to_also_toggle"]);

// Or as a string with each tag separated with a comma
await Tagger.toggleTags(token, "tag_to_toggle, tag_to_also_toggle");

Toggles the tags on an PlaceableObject or Document. If a tag is present, it will be removed. If it not present, it will be added.

Returns: Promise - A promise that will resolve when the PlaceableObjects' tags have been updated

Param Type Description
inObjects PlaceableObject/Array A PlaceableObject, or an array of PlaceableObjects to set tags on
inTags String/Array An array of tags or a string of tags (separated by commas) that will override all tags on the PlaceableObjects

Tagger.addTags(inObjects, inTags) ⇒ Promise

Example:

// Adds "tag_to_add" to the token's existing tags
await Tagger.addTags(token, "tag_to_add");

Adds tags to an object

Returns: Promise - A promise that will resolve when the PlaceableObjects' tags have been updated

Param Type Description
inObjects PlaceableObject/Array A PlaceableObject, or an array of PlaceableObjects to add tags to
inTags String/Array An array of tags or a string of tags (separated by commas) that will be added to the PlaceableObjects

Tagger.removeTags(inObjects, inTags) ⇒ Promise

Example:

// Removes "tag_to_remove" from the token's tags
await Tagger.removeTags(token, "tag_to_remove");

Removes tags from an object

Returns: Promise - A promise that will resolve when the PlaceableObjects' tags have been updated

Param Type Description
inObjects PlaceableObject/Array A PlaceableObject, or an array of PlaceableObjects to remove tags from
inTags String/Array An array of tags or a string of tags (separated by commas) that will be removed from the PlaceableObjects

Tagger.clearAllTags(inObjects) ⇒ Promise

Example:

// Clears all tags from the given object
await Tagger.clearAllTags(token);

Removes all tags from PlaceableObjects

Returns: Promise - A promise that will resolve when the PlaceableObjects' tags have been updated

Param Type Description
inObjects PlaceableObject/Array The PlaceableObjects to remove all tags from

Tagger.applyTagRules(inObjects) ⇒ Promise

Example:

// If the token has a tag that looks like this: "test_{#}_tag", running this method:
await Tagger.applyTagRules(token);
// The tag will now be "test_1_tag", but the number depends on how many other objects in the scene that also has that same tag

Applies all tag rules to every tag found on the given PlaceableObjects

Returns: Promise - A promise that will resolve when the PlaceableObjects' tags have been updated

Param Type Description
inObjects PlaceableObject/Array The PlaceableObjects to apply tag rules to

Tag Rules

Tag Rule Description
{#} The {#} gets replaced with an unique number, and the number depends on how many other objects in the scene also has that tag
{id} The {id} gets replaced with an unique ID