Element Lists

Multiple elements

When a selector includes "returnAll": true, the generated method returns a list.

In the DOM, a parent can contain multiple instances of a nested element, like lightning-tab components inside a lightning-tabset. If the selector has a returnAll property set to true, the method returns a list of instances found at run time.

{
    "elements": [
        {
            "name": "allTabs",
            "type": "utam-lightning/pageObjects/lightning/tab",
            "selector": {
                "css": "lightning-tab",
                "returnAll": true
            },
            "public": true
        }
    ]
}

From the previous JSON, UTAM generates this public method, which returns a list of the page objects of the given type.

public List<Tab> getAllTabs() {
    // return list of instances found in runtime
    // throw exception if nothing found
}

Indexes

To get one of the instances by its index, add :nth-of-type(%d) to the injected selector and the args property with an index parameter. :nth-of-type(%d) is 1-based, not 0-based.

{
    "elements": [
        {
            "name": "myComponent",
            "type": "utam-lightning/pageObjects/lightning/myComponent",
            "selector": {
                "css": "lightning-my-component:nth-of-type(%d)",
                "args": [
                    {
                        "name": "index",
                        "type": "number"
                    }
                ]
            },
            "public": true
        }
    ]
}

The generated method finds all the custom elements inside the parent and returns one by index.

public MyComponent getMyComponent(int index) {
    // return nth instance
    // if nothing found, or index is out of bounds, throw exception
}

Elements nested inside lists

Sometimes a list element can have nested element, in the example below it's <lst-template-list-field> inside <dd>:

<template for:each="{fields}" for:item="field">
    <dd key="{field.key}" class="record__card-field">
        <lst-template-list-field field="{field}"></lst-template-list-field>
    </dd>
</template>

The UTAM grammar allows you to include nested elements within lists:

{
    "name": "recordCardField",
    "selector": {
        "css": "dd.record__card-field",
        "returnAll": true
    }
    "elements": [
        {
            "name": "listField",
            "selector": {
                "css": "lst-template-list-field"
            },
            "type": "utam-lst/pageObjects/templateListField",
            "public": true
        }
    ]
}

Because "recordCardField" is a list, the UTAM compiler will automatically generate a getter method with an index parameter in order to access the "listField" nested element.

Here's what the generated code might look like:

1. For JavaScript:

/**
* @param _recordCardFieldIndex index of parent element
*/
getListField(_recordCardFieldIndex: number): Promise<(_TemplateListField)>;

2. For Java:

/**
* @param _recordCardFieldIndex index of parent element
*/
TemplateListField getListField(_recordCardFieldIndex: integer);