Components

Introduction

LRE greatly enhances the components from the original ones. While it keeps the same behavior in order to be transparent with your existing system, it adds many methods and features globally to all components, and some specific feature for some specific components.

realId

component.realId(): string

This method simply returns the component id if it is not in a repeater. Inside a repeater, this method return an string which pattern is repeaterId.entryId.componentId. This id can be use with sheet.get()

dynamic setters : value(), text(), visible()

This is one of the major and more powerful feature in LRE : you can define a dynamic value to a component by passing a component, a function or a Data Provider. it will automatically handles the changes that can affect the final value of the component.

The methods that are dynamic are value(), text() and visible(). You can still pass a string, a number, an array or an object to these functions like with Let's Role, they can also receive the three following argument types.

This feature allows you to write code that is closer to the rules you want to code. By example, for a basic rule like "The Final Force attribute is equal to the Force Base + the Race Force Bonus". If you want that the value of a label called finalForce changes as soon as you change the inputs baseForce or raceForce, you will have to write the following code

const baseForce = sheet.get("baseForce");
const raceForce = sheet.get("raceForce");
const computeFinalForce = function () {
    const finalForce = sheet.get("finalForce");
    finalForce.value(baseForce.value() + raceForce.value());
};
baseForce.on("update", computeFinalForce);
raceForce.on("update", computeFinalForce);
computeFinalForce();

With LRE, you can write the following code that is more straightforward

const finalForce = sheet.get("finalForce");
finalForce.value(function () {
    const baseForce = sheet.get("baseForce");
    const raceForce = sheet.get("raceForce");

    return baseForce.value() + raceForce.value();
});

This short and simple example shows that you can write code close to the computed formula logic : you define how the value is computed instead of saying what a value is used for. In complex rule system, dynamic values can greatly facilitate the your script coding and debugging.

Dynamic arg : Component

You can link a component value to an other component value. As soon as the second component is modified, the first will be modified as well. The following code will immediately set the value of agilityBonus in the label lockPickingAgilityBonus. Moreover, if agilityBonus is changed, lockPickingAgilityBonus will be changed.

sheet.get("lockPickingAgilityBonus").value(sheet.get("agilityBonus"));

The magic behind it : LRE detect that a component A is given as a value to component B, then it will grab the component A value to assign it to the component B, and add an update event to the component A that set the value of the component B.

Dynamic arg : Function

You can use a function to set the value of a component (or other properties) with the returned value. LRE will execute the function in a mocked environment that blocks you from changing any component, open a prompt or roll a dice. The function should only be intended to compute a value.

sheet.get("totalLockPicking").value(function () {
    let total = sheet.get("baseLockPicking");
    if (sheet.get("checkboxLockPickingSpecialty").value()) {
        total += 1;
    }
    const bonusMalus = sheet.get("bonusmalusLockPicking");
    if (bonusMalus.hasClass("bonus")) {
        total += bonusMalus.value();
    } else {
        total -= bonusMalus.value();
    }
    total += sheet.get("repeaterItems").provider().sum("lockPickingBonus");
    return total;
});

The code above will compute the value of totalLockPicking based on the following (imaginary) rules :

• the character has a lock picking base value
• the character can have +1 at lock picking if the player has chosen it as a specialty
• you can add or subtract the value of the bonus/malus
• then you must take into account the lock picking bonuses from the character items.

LRE will run this function again and set to the called method (value(), visible(), ...) as soon as baseLockPicking, checkboxLockPickingSpecialty, bonusmalusLockPicking have their value changed, but as well when bonusmalusLockPicking classes are changed, or if you make any change in the repeater repeaterItems (see the doc for Repeaters for more details about the sum() method)

Dynamic arg : Data Provider

You can also pass a Data provider as a value of a component. If you use it, you could then use the two following component methods : valueProvider() (the provider passed to the component value()) and valueData (the complete data associated to the value).

values are converted

As soon as you activate lre.autoNum() or lre.autoTransl(), the component.value() method will return you a transform value : a text input containing a numeric value will return a number, a general text can be automatically translated using _().

Additional data

Inspired from good-old JQuery method, and the HTML-dom attribute, LRE provides a way to attach additional data to a component.

component.data(dataId: string, data?: any: persistent: boolean = false);

This method allows you to set and get a data of any type identified by a string as first parameter.

component.data("dataName", "dataValue"); // set the value
log(component.data("dataName")); // get the value

The third parameter is a boolean and, when it is true, the data will be stored for this sheet and will be reloaded every time you open the sheet. When this third parameter is false (default value), the component data will be lost as soon as you quit the table.

Class enhancement : classes can be saved, toggled

One of the most common question concerning the system builder is "why do the classes I set to a component lost when I reload the table ?".

Many have made some specific code to compute the classes on sheet init. LRE provides a very simple way to do that simply :

component.autoLoadSaveClasses()

If you call this method on a component, every class changes you'll apply in your script will be restored at the last known state before quitting. There is no magic in it, so keep in mind the classes will be applied on sheet init, it won't be immediate (and it can't).

Some customs events

LRE Component has to more event aliases

• data-updated : as soon as you add, update or remove a data on the component
• class-updated : as soon as you add or remove a class by script on the component

Example

component.on("data-updated", function (cmp) {
    log("The data of " + component.realId() + " has been changed");
});

Others methods

• repeater(newRepeater) : this is a feature from LRE. Returns the repeater containing the component, or undefined
• entry(newEntry) : this is a feature from LRE. Returns the entry (repeater element) containing the component, or undefined
• parent(newParent) : it can receive an argument to manually define a parent component to the component. It always returns the component parent() set by this method.
• knownChildren() : returns an array of Components that have been found previously inside the component
• exists() : returns true if the component actually exists
• dataProvider() : Returns a Data Provider linked to the component value
• toggle() : show or hide the component if it is respectively hidden or visible