The map() function

Unit introduction

Welcome to the second unit of the “Using get() and map() functions” course.

Let’s build on the knowledge from unit 1. You’ve looked at the get() function, which returns a value from an array.

You’ll be introduced to a new function in this unit that works really well with get() - the map() function. By the end of this unit you will know:

• what the map() function does, and why this differs from get()
• how to use map() to simplify an array

What is the map() function?

The map() function is an array function that allows you to extract values from an existing array, and then transform them to create a new array. It will always return an array with either a single or multiple element(s), and no longer a collection.

The function starts with map(). Every item contained between the parentheses ( and ) will form the basis of what you want the function to achieve. The arguments of the map() function are separated with ;.

The map() function is conceptually composed of:

• Array (A): The array you are iterating over.
• What you want to get (B): This is the key you want to extract from each item in the array.
• Filter name (C): This is the key for filtering that you want to use to select specific items.
• Filter value (D): These are the possible value(s) for filtering that the filter key must match.

Think of this as saying: “Array A, give me the value of the item B, where the item named C has the value of D”.

What is the map() function?

+pets(array)
- 1 (collection)
  - pet_name: Pearl
  - animal_type: cat
  - cute: yes
- 2 (collection)
  - pet_name: Dakota
  - animal_type: dog
  - cute: yes

↓

`map(pets;pet_name;cute;yes)`

=

+pets(array)
- 1 Pearl
- 2 Dakota

Think of the map() function like a filter, combined with an array aggregator, which behaves differently:

• a filter will pass bundles through your scenario between modules based on the criteria that you set (e.g. “cute = yes”)
• an array aggregator will create a new array, based on the conditions that you set within the aggregated fields box.

The map() function performs a similar action as both of these at the same time, creating an output based on the specified fields in the input.

The map() function usage

The two main reasons of using the map() function alone is to simplify and filter the values of an array.

By default, map() will always simplify the array. But the filter part is optional.

Let’s explore the following scenario and see where the map() function could be useful. Arthur runs a sports shop online, selling football kits, and wants to create an array to organize his data by item types.

The items listed in the array of each of his clothing items are:

• team_name <text>
• size <text>
• color <type>
• sleeves <text>
• in_stock <boolean>
• barcode_number <number>

Let’s look at the 2 main uses of the map() function.

Simplify

In this example, Arthur wants to simplify the values of his array, so he has a summary of each kit.

Using map(clothing;team_name) his array will go from this:

• team_name <text>
• size <text>
• color <date>
• sleeves <text>
• in_stock <boolean>
• barcode_number <number>

To this:

• team_name <text>
• size <text>
• color <date>
• sleeves <text>
• in_stock <boolean>
• barcode_number <number>

Filter

Using the filter option, Arthur could choose to use map(clothing;team_name;in_stock;true) to create an array that would show only the array items that reflect the in_stock = true status.

For example if 6 of the 12 items he sold were in stock, his array would appear like this:

1. Real Makedrid
2. Makecelona
3. Makeventus
4. AC Makelan
5. Makechester United
6. Paris Saint GerMake

How is mapping different from using a filter?

Let’s look at the actions a filter and the map() function will achieve.

Filter

A filter is used between modules, when bundles are moved along a scenario. It will pass only the bundles that meet the criteria set on the filter. E.g. “IF COLOR = Black”. The structure and contents of the bundle remain the same.

map() function

The filter aspect of the map() function acts differently. It will look at each element in an array based on the criteria that is set, and then map any matching element into a new simple array.

This is really useful within scenarios, as you may have a lot of complex arrays which contain information that you don’t need, and you want to work with simpler arrays.

Note that the filter part of map() is optional.

ACTIVITY LANDING

Let’s see this in action now, using the same JSON used in the previous unit. Work through each stage before you continue.

The aim of this scenario is to create an array using the map() function, which will output 2 separate variables based on the criteria that you set. An example of this function might look like map( 1.shopping_basket ).

Before you start, select how you would like to build this:

• Use a blueprint for this scenario.
• Build the scenario yourself.

BLUEPRINT PATH

Let’s see the map() function in action now, using the same JSON used in the previous unit. Work through each stage before you continue.

You can download a zip or a JSON version of the blueprint that you’ll use for this exercise. Create a new scenario, then click … > Import blueprint. This loads a single pre-configured module: JSON→Parse JSON. This will contain the details of the order.

Right-click the module and select Run this module only. This will generate the bundle that will be used for the map() function. Add a new module to this, search for Tools, and then select the Set multiple variables module.

Click +Add item. This will create a new variable. Type “List of Black Items” under Variable name. In this scenario, the aim of the map() function is to provide a list of all the black items from the order. In the Variable value field, start by either typing map(), or inserting map() from the Functions for working with arrays tab.

After map(), add the shopping_basket:items[] item. Add a ; and type item_name. Remember that with these array functions, you do not map the field, but type the raw name. This tells the function that you want to display the item name. Add another ; and type item_color. Add ; and type “Black”. Close the function with the parentheses ). Then, click OK to save.

We will explore the rationale behind this function type on the next page.

Click Run once to execute this scenario and see the result. The scenario will parse the JSON into a bundle containing a collection (shopping_basket) with items (array). The map() function will search the items array and create a new array, containing the item name and the item color for any items that contain the word “Black”. This is the map() function in action.

BUILD YOURSELF PATH

Let’s see this in action now, using the same JSON used in the previous unit. Work through each stage before you continue.

1. Create a new scenario and name it Make Intermediate 2-2.
2. Click on the add module (+), search for the JSON module and then select Parse JSON.
3. Ignore the Data structure field, and click on the JSON string field. Paste the JSON into the JSON string field.
4. Right-click the module and select Run this module only. This will generate the bundle that will be used for the map() function.
5. Add a new module to this, search for Tools, and then select the Set multiple variables module.
6. Click +Add item. This will create a new variable.
7. Type List of Black Items under Variable name.
8. In this scenario, the aim of the map() function is to provide a list of all the black items from the order. Start by either typing map(, or inserting map from the Functions for working with arrays tab.
9. After map(, add the shopping_basket:items[] item.
10. Add a ; and type item_name. Remember that with these array functions, you do not map the field, but type the Raw name. This tells the function that you want to display the item name.
11. Add another ; and type item_color.
12. Add ; and type Black. Close the function with ).
13. Click OK.
14. Click Run Once to execute this scenario to see the result.

The scenario will parse the JSON into a bundle containing a collection (Shopping Basket) with Items (Array). The map() function will search the items array and create a new array, containing the item name, and the item color for any items that contain the word Black.

This is the map() function in action.

map() structure

Let’s delve into what is happening within this function. The map() function is structured as follows:

map( 1.shopping_basket.items ; item_name ; item_color ; Black )

The map() Function Syntax

The function starts with map(). Every item contained between parenthesis ( and ) will form the basis of what you want the function to achieve.

This will be composed of the:

• mapped item from the array
• key
• key for filtering
• possible value(s) for filtering

The properties within map() are separated with the semicolon ;.

Mapped Array

The first part, 1.shopping_basket.items, is the mapped field from the array that we want to filter from.

Notice that instead of shopping_basket, the mapped array is shopping_basket.items. The . reflects the position of the mapped array within the collection.

The Key

The next step specifies the key, which dictates the values that will form the output array.

In this example, item_name will display all of the values of item_name, which meet the item_color condition of Black. The results will be “T-shirt with print” and “Sports socks”.

If item_name was changed to item_price, the result would instead display “20” and “9”.

Remember, the key has to be typed based on the raw name, rather than mapping the item itself. All of the raw name values are case sensitive.

Key for Filtering

After the key, item_color is the key for filtering.

Remember that the main purpose of map() is to simplify, while the filter aspect is optional.

If the purpose of the key is to show item_name as a result, then the key for filtering is the condition. The condition used in this example is item_color. This is similar to using a filter, and saying IF key for filtering = Black.

Note: The key for filtering values must be an exact, case-sensitive match.

Possible Value(s) for Filtering

The last part of the function, Black, is the possible value(s) for filtering.

In this example, we are asking for any item_color that matches Black to be created in the new array.

You can add more values for filtering here, by adding a comma , between the values for filtering. For example Black,White.

GET-MAP

Let’s compare map() and get().

get()

The get() function extracts an item from a list. In the example, it gets the 4th item in the array and outputs it into a collection.

map()

The map() function provides a simple array. In the example, it maps all black items.