You should get to know TextEditor.enrichHTML(). This function takes text or HTML that would be displayed and “Foundy-izes” it. You can see this most typically in places like descriptions of Actors and Journal Entries, chat messages, etc.. This is the function that translates things like @UUID[Actor.GQO6txTySEXZjitR]{Joe}to a link to a pretty link to the actor, or [[2d6]] into a link you can click to automatically roll dice.
This function runs a number of default enrichers that provide the built in transforms that foundry core uses, but you can also customize it to do your own.
There are 5 default enrichers:
You can easily prevent any of these default behaviors:
TextEditor.enrichHTML(content: string, options: { secrets: boolean, documents: boolean, links: boolean, embeds: boolean, rolls: boolean, rollData, …})
rollData is an object or function that provides extra context for inline rolls (beyond the scope of this article).
Simply pass in an options object with the enrichers you don't want set to false. They all default to true.
In addition to the default enrichers, you can easily add your own. A couple things are important to note:
Custom enrichers are configured with an object with the format:
enricherConfig = {
pattern: RefExp,
enricher: (match: RegExpMatchArray, options: Record<string, any>)=>Promise<HTMLElement | null>,
replaceParent: boolean,
};pattern is a regular expression that is what you want to search for (and replace) in the text passed to enrichHTML.
enricher is your function that will be called for each match; it will be passed any options that are passed into enrichHTML so you can add your own custom options.
if replaceParent is true, not only the text will be replaced, but the parent element that it is in. This would let you, for example, add a class to a button (parent) that had specific text displayed in it.
enrichershould simply return a DOM HTML element that will be inserted in place of the matched text.
To use your custom enricher, you simply add it to CONFIG.TextEditor.enrichers
CONFIG.TextEditor.enrichers.push(enricherConfig);It will then we used for every call to TextEditor.enrichHTML.
Warning! Best practice is to only add your enrichers in for calls to enrichHTML that you are making and then immediately remove them so that other parts of Foundry don't unexpectedly see your modifications (unless that's specifically what you're intending). An easy way to do this is to create your own function that you use instead of
TextEditor.enrichHTML
Example of a custom enrichment function
export const myEnrichHTML = async(text: string): Promise<string> => {
const enricherConfig = {
pattern: myRegex,
enricher: myEnricherFn,
replaceParent: false, // or true, as you need
};
// add your enricher
CONFIG.TextEditor.enrichers.push(enricherConfig);
// call enrichHTML
const enrichedText = await TextEditor.enrichHTML(text || '', {
// any options you want to pass in for your enricher or to disable defaults
});
// remove your enricher
CONFIG.TextEditor.enrichers = CONFIG.TextEditor.enrichers
.filter((f): boolean => (f!=enricherConfig));
return enrichedText;
}Then you'd just call myEnrichHTML whenever you wanted to apply your custom setup.