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.

1{
2  "elements": [
3    {
4      "name": "allTabs",
5      "type": "utam-lightning/pageObjects/lightning/tab",
6      "selector": {
7        "css": "lightning-tab",
8        "returnAll": true
9      },
10      "public": true
11    }
12  ]
13}

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

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

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.

1{
2  "elements": [
3    {
4      "name": "myComponent",
5      "type": "utam-lightning/pageObjects/lightning/myComponent",
6      "selector": {
7        "css": "lightning-my-component:nth-of-type(%d)",
8        "args": [
9          {
10            "name": "index",
11            "type": "number"
12          }
13        ]
14      },
15      "public": true
16    }
17  ]
18}

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

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

Elements nested inside lists

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

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

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

1{
2    "name": "recordCardField",
3    "selector": {
4        "css": "dd.record__card-field",
5        "returnAll": true
6    }
7    "elements": [
8        {
9            "name": "listField",
10            "selector": {
11                "css": "lst-template-list-field"
12            },
13            "type": "utam-lst/pageObjects/templateListField",
14            "public": true
15        }
16    ]
17}

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:

For JavaScript:

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

For Java:

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

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!