# List

Some methods for working with `Lists` in Stadium.

1. [Creating Lists](#creating-lists)
2. [Setting List Types](#setting-list-types)
3. [Adding Static Data](#adding-static-data)
4. [Adding Connector, JSON or Javascript Data](#adding-connector-json-or-javascript-data)
5. [Value Mapping](#value-mapping)
6. [Adding Items to Lists](#adding-items-to-lists)
7. [Removing Items from Lists](#removing-items-from-lists)
8. [Adding Properties to Lists](#adding-properties-to-lists)
9. [Removing Properties from Lists](#removing-properties-from-lists)

## Creating Lists

Lists can be of a specific [type](https://docs.stadium.software/features/types) or of type 'Any'. The type can be selected in the `Item Type` property of a `List`. 'Any' is the default

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-7f09a9caf4cd9a0b016cdf620c85721d16bb79e5%2FListItemTypeProperty.png?alt=media)

If the `ListItemType` property is set to `Any`, then the List will accept any JavaScript array. So, then you can assign an array of values or an array of objects of any complexity.

However, as the type of each item is not known in this case, Stadium will treat each list item as a value. So, when assigning an array of objects, dropdowns in the rest of Stadium will not display the properties of the object.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-859141af39a412293a0d07ede8e1da266d3aeb93%2FStadiumDropDownListTypeAny.png?alt=media)

To access properties of a list of objects, the property can manually be appended to the list item

```javascript
~.AnyList.ListItem.id;
```

## Setting List Types

It is therefore advisable to set the `ListItemType` property to a known type when working with `Lists` of objects. It then becomes necessary to first create a type in the `Types` section in the `ApplicationExplorer` and subsequently select that type in the `ListItemType` property.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-39e499174aafcde4bc8995ec3009faca611a7b8e%2FKnownTypeSelection.png?alt=media)

When a type is defined, various dropdowns in the Stadium Designer will provide an option to select specific properties of the `List`

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-3fe7370af9b54ce5974fa18479c936f35f576be0%2FStadiumDropDownListTypeSpecific.png?alt=media)

## Adding Static Data

Adding static data for Lists of type `Any` can be added opening the `List Editor` on the `List` `Value` property where values can then be added directly into the editor.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-7950e7170d0216d9b15fe1bbb471baecc7f17c73%2FStaticListAnyType.png?alt=media)

Object data for defined types can be added by further opening the `Object Properties Editor` next to items in the `List Editor`.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-e13676df69ec5f572a861f62c9b8078c9afc8243%2FStaticListSpecificType.png?alt=media)

## Adding Connector, JSON or Javascript Data

Connector Data is commonly provided as a JSON List of objects. The `Result` of a query or any other JSON or Javascript array can hence be directly assigned to a `List`. When the `List Item Type` contains all or a subset of the properties of the incoming data the properties will be auto-mapped. For this purpose

1. Create a [type](https://docs.stadium.software/features/types) with properties that match those of the incoming dataset
2. Assign the type to the `Item Type` property of the `List`
3. Assign the data to the `List` `Value` property. Fields will be auto-matched where property names are the same.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-1d1579549a424df31ec06b8d44dd3ad76085f753%2FDefinedConnectorDataType.png?alt=media)

## Value Mapping

Incoming properties can be mapped to `List` properties when names of the properties of the assigned data differ from the `List` `Item Type` properties. For this purpose, select the `Field Mapping` option in the `List` `Value` property dropdown.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-e1b0a944401274f088048d6bcdee19de75c6116e%2FFieldMappingOption.png?alt=media)

The `Mapping Editor` displays information in two columns, the target information on the left and the source on the right.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-f96785ea152824d76768b952232568a933d51fa9%2FMappingEditor.png?alt=media)

The target information column (left) provides the

1. Target List
2. All mappable properties of the Target

The source column (right) provides

1. A dropdown to select the source data `List`
2. Input fields to define the mapping for source List properties. The `MapItem` option in the dropdown represents a `List Item`. Where such an item consists of a known type, the type properties are provided for selection.

## Adding Items to Lists

Adding items into a `List` can be accomplished by using a `Javascript` action.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-ea9b107e90a017d97f1434246751ea25f4e1d420%2FAddToAnyList.png?alt=media)

The JavaScript push function can also add objects to a `List`. Properties are then mapped by name.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-a3d3e857665f7cc46cb6c2e71c745c16be300f14%2FAddToDefinedList.png?alt=media)

```javascript
~.TextValueList.push({"text":"Monday","value":1});
```

Using this method, one `List` can be populated with values from another one in a `ForEach` loop.

![](https://3514041584-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqxH8JA8xG3I22tiZG5H6%2Fuploads%2Fgit-blob-cd77482fed762361b3462e39367df4332299a472%2FAddingInLoop.png?alt=media)

```javascript
~.TextValueList.push({"text":~.ForEach.LoopValue.Name,"value":~.ForEach.LoopValue.CountryCode});
```

## Removing Items from Lists

Individual items can be removed from `Lists` using a variety of different Javascript functions.

**Splice**

Splice modifies the original `List`

```javascript
~.AnyList.splice(1, 0); // Removes 1 element starting from index 0 (the first list item)
```

**Pop**

Removes and returns the last element of a `List`

```javascript
let lastElement = ~.AnyList.pop();
```

**Shift**

Removes and returns the first element of a `List`

```javascript
let firstElement = ~.AnyList.shift();
```

**Delete**

Removes an element at a specific index, but leaves an "empty slot" (the `List` length remains the same, and the value at that index becomes `undefined`)

This example works for a `List` of values

```javascript
delete ~.AnyList[~.AnyList.indexOf("Bob")];
```

This example works for a `List` of objects where the object has a property called 'id' with a unique value

```javascript
delete ~.UsersList[~.UsersList.findIndex(user => user.id === 1)];
```

**Filter**

Creates a new `List` containing only the elements that pass a provided test function. In this case it returns all values that are larger than 3

```javascript
let newList = ~.AnyList.filter(num => num > 3);
```

## Adding Properties to Lists

Adding a property with a distinct value to a `List` of a specific type (a List of objects) can be achieved by looping through the `List`

```javascript
~.UsersList.forEach(obj => {
    obj.age = 26;
});
```

Adding a property with the same value can also be achieved without an explicit loop. This function returns a new `List`

```javascript
const newList = ~.UsersList.map(obj => {
    return { ...obj, isActive: true }; // Creates a new object with existing properties and the new 'isActive' property
});
```

## Removing Properties from Lists

Removing a property from a `List` of a specific type (a List of objects) can be achieved by looping through the `List`

```javascript
~.UsersList.forEach(obj => {
    delete obj.age; 
});
```