Finding elements

There are scenarios in which your Actions may need to obtain a reference (address) to a specific element within your Loopic Composition. This can be particularly useful when implementing middleware logic that involves modifying an element's properties or accessing its underlying DOM node reference.

Each element within Loopic is equipped with a unique key property, serving as the element's "ID" within the composition. To ensure composition-wide uniqueness, these keys must be distinct.

Within the Actions framework, you can retrieve a reference to a designated element by utilizing the findElementByKey method. This method is conveniently accessible through the Composition object. When invoked, findElementByKey undertakes a comprehensive search across all elements present within the composition, including those within nested compositions. The objective is to locate and return the specific element identified by the provided key.

Action example

const elementObject = this.findElementByKey("_title");

Nested compositions

In cases where an element in the outermost Composition shares its key with an element within a nested composition, Loopic grants priority to the outermost element. However, if you wish to explicitly query elements within the nested composition, you can use the same findElementByKey method. Instead of specifying only the key, provide the path to the nested key using dot notation (ensure the key for the Composition element is set).

This enables accurate querying of nested composition elements, even when conflicts arise.

Action example

const elementObject = this.findElementByKey("_nestedComposition._title");

Repetitive groups

Querying elements within nested compositions may also be useful if you have many instances (nested compositions) of the same composition. For example, if you have a team list of 5 first name (_firstName) and last name (_lastName) Text elements, you can move those 2 elements in the Nested composition and make 5 copies of it. Then, you can assign a unique key for each Nested composition (for example, _player1, player2, _player3, etc.) and easily query a reference for each first/last name Text element object.

Action example

const player1FirstName = this.findElementByKey("_player1_._firstName");
const player1LastName = this.findElementByKey("_player1_._lastName");
const player2FirstName = this.findElementByKey("_player2_._firstName");
const player2LastName = this.findElementByKey("_player2_._lastName");
const player3FirstName = this.findElementByKey("_player3_._firstName");
const player3LastName = this.findElementByKey("_player3_._lastName");
// Etc...

This approach can be employed whenever you encounter repetitive groups of elements. Additionally, it proves especially beneficial when dealing with element keys that require re-addressing. For instance, if your CG engine sends data with keys such as _p1FirstName, _p1LastName, _p2FirstName, _p2LastName, and so on (keys that do not match your composition's existing structure) — this technique offers a solution.

Action example

loopic.useOnUpdate(`_p1FirstName`, (key, value, next) => {
  const player1FirstName = this.findElementByKey("_player1_._firstName");
  player1FirstName.setContent(value);
});

loopic.useOnUpdate(`_p1LastName`, (key, value, next) => {
  const player1LastName = this.findElementByKey("_player1_._lastName");
  player1LastName.setContent(value);
});

// Etc.

If you combine this technique with the for loop, you can make your entire code much shorter.

Action example with loop

for (let playerNumber = 1; playerNumber <= 5, playerNumber++) {
    loopic.useOnUpdate(`_p${playerNumber}FirstName`, (key, value, next) => {
        const firstNameElement = this.findElementByKey(`_player${plyaerNumber}_._firstName`);
        firstNameElement.setContent(value);
    });

    loopic.useOnUpdate(`_p${playerNumber}LastName`, (key, value, next) => {
        const LastNameElement = this.findElementByKey(`_player${plyaerNumber}_._lastName`);
        LastNameElement.setContent(value);
    });
}