Get started with ArcGIS Arcade

As an electricity researcher, you are interested in comparing your country’s electricity consumption with that of other countries around the world. You'll use ArcGIS Arcade to accomplish this. Arcade is a flexible expression language that allows you to work with data in real time in ArcGIS. You can use Arcade to style and label your map, create informative pop-ups, and perform field calculations on your data. This tutorial will introduce you to the language, while walking you through techniques for leveraging Arcade expressions in Map Viewer. Arcade will help you answer questions about your data, such as, how do countries compare on electricity consumption? And how many 60-watt light bulbs can each power plant around the world power?

This tutorial was last tested on January 3, 2024.

View final result

Requirements

• User, Publisher, or Administrator role in an ArcGIS organization (see options for software access)

Style a layer using Arcade

You'll create an Arcade expression and use it to style a layer in your map. The Arcade expression will calculate the annual electricity consumption per capita. It will start with the annual electricity consumption in each country and divide it by the country's total population. This calculation is important for a meaningful comparison of electricity consumption, given the wide range of population counts across countries worldwide. You will then style the world countries layer using the resulting annual electricity consumption per capita values.

First, you'll add the layers to the map and choose a different basemap.

Add layers and change the basemap

You'll create a new map in Map Viewer. Then, you'll add two layers, Global Power Plants and World Countries Electricity Consumption, to the new map, and you'll change the basemap.

Note:

Map Viewer is the next-generation mapmaking tool for ArcGIS Online. It aims to inspire experimentation and creativity while providing an enhanced experience for key map authoring workflow's.

1. Sign in to your ArcGIS organizational account.

   Note:

   If you don't have an organizational account, see options for software access.

2. On the ribbon, click Map.

   

   Note:

   Depending on your organizational and user settings, you may have opened Map Viewer Classic. ArcGIS Online offers two map viewers for viewing, using, and creating maps. For more information on the map viewers available and which to use, please see this FAQ.

   This tutorial uses Map Viewer.

3. If necessary, in the pop-up window, click Open in Map Viewer, or on the ribbon, click Open in Map Viewer.

   Map Viewer opens.

   

   You'll now add the first layer, Global Power Plants, to the map.

4. In the Layers pane, click Add.

   

5. Click My Content and choose ArcGIS Online.

   

6. In the search bar, type global power plants owner:Learn_ArcGIS.

   The Global Power Plants layer appears in the search results.

7. For the Global Power Plants search result, click the Add button.

   

   The layer appears on the map.

   

   The layer is a comprehensive inventory of power plants around the world, symbolized by electricity type. You'll now add the second layer you'll use in this workflow.

8. In the search bar, copy and paste the following text: electricity consumption owner:Learn_ArcGIS.
9. For the World Countries Electricity Consumption search result, click Add.

   The layer appears on the map.

   

   The layer contains population and electricity consumption information about every world country.

   

   The layer is drawn on top of the Global Power Plants layer, partially covering it, so you'll change the order of the layers.

10. In the Add layer pane, click the Back button to return to the Layers pane.

    

11. In the Layers pane, drag the World Countries Electricity Consumption layer below the Global Power Plants layer.

    The power plant features are now visible on top of the countries layer.

    

    There are many power plants close together in certain countries across the world. To better visualize the distribution of power plants, you'll enable clustering on the layer.

12. In the Layers pane, click the Global Power Plants layer to select it.
13. In the Settings (light) toolbar, click Aggregation.

    

14. In the Aggregation pane, turn on Enable aggregation.

    

    Clustering is enabled by default.

15. For Clustering, click on Options.

    

    The Clustering pane appears.

16. In the Clustering pane, for Cluster radius, drag the slider closer to Low. For Size range, drag the right slider to the left.

    

    The power plants layer is now symbolized with clusters. As you zoom in and out, the clusters are reconfigured to adapt to the current scale. Each cluster is labeled with the number of power plants it represents.

    You'll now choose a different basemap so the power plant features stand out better on the map. Since the points in this layer are represented with bright symbols, you can create contrast by putting them against a dark and neutral basemap.

17. Click back and close the Aggregation pane.

    

18. On the Contents (dark) toolbar, click Basemap. In the Basemap pane, choose Dark Gray Canvas.

    

    The basemap updates on the map.

    

19. Close the Basemap pane.

    You'll now collapse the Contents toolbar to have more to view for the map.

20. At the bottom of the Contents toolbar, click Collapse.

    

    Next, you'll save the map.

21. On the collapsed Contents toolbar, click Save and open and choose Save as.

    

22. In the Save map window, enter the following information:
    • For Title, type Global Power Generation and Consumption, followed by your initials.
    • For Tags, type electricity consumption, power plants and press Enter after each tag.
    • For Summary, type This map shows power plants around the world, categorized by electricity type.

    

23. Click Save.

Explore the data and the Arcade expression editor

Next, you'll explore the Arcade expression editor and use it to style the World Countries Electricity Consumption layer. Your goal is to easily compare annual electricity consumption in every country. To do so, you'll build an Arcade expression that returns the annual electricity consumption per capita by dividing the annual electricity consumption (in kilowatt-hours) by the total population. This will enable a meaningful comparison of electricity consumption across countries with widely different population counts.

Note:

This type of computation is called normalization: for each country, you will normalize electricity consumption by the total population.

Before you start building your Arcade expression, you'll examine the layer's attribute table.

1. On the Contents toolbar, click the Layers button.

   

2. In the Layers pane, for the World Countries Electricity Consumption layer, click the Options button and click Show table.

   

   The attribute table appears.

   Note:

   For more screen space, you can close the Properties pane.

   

   The table includes the COUNTRY field listing the country names, an Annual Electricity Consumption field with values in kilowatt-hours (kWh), and a Pop field, containing the total population for each country. These are the attributes you'll use in the Arcade expression.

   Note:

   Kilowatt-hours are a common measure of electricity usage over time. If you take a close look at your monthly electricity bill, your monthly usage is likely shown in kilowatt-hours.

   You will now become familiar with Arcade. It is a portable, lightweight, and secure expression language written for use in ArcGIS. Like other expression languages, it can perform mathematical operations, manipulate text, and evaluate logical statements. Arcade was designed specifically for creating custom visualizations and labeling on the fly in ArcGIS. It allows users to manipulate existing data and derive new insights through authoring, sharing, and executing custom expressions in ArcGIS Pro, ArcGIS Runtime, ArcGIS Online, ArcGIS Enterprise, and the ArcGIS API for JavaScript.

   In Map Viewer, Arcade is useful when working with data in pop-ups and labels, and when styling a layer. You can build and apply Arcade expressions using the Arcade expression editor. You'll now open and explore the expression editor. Because your goal is to style the World Countries Electricity Consumption layer, you'll open the expression editor through the Styles pane for that layer.

3. In the Layers pane, ensure the World Countries Electricity Consumption layer is selected and on the Settings toolbar, click Styles.

   

4. In the Styles pane, under Choose attributes, click Expression.

   

   The Arcade expression editor window appears.

5. Click the expand icon to view the side tabs.

   

   Review the different sections of the editor window. The expression window is where you build the expression. The Profile variables and Functions tabs are where you find the elements you'll use in the expression. The Help tab opens the Arcade help webpage.

   

6. Review the Profile variables tab.

   This tab offers a list of predefined variables, including attribute fields and geometry for the layer features.

7. Click the Functions tab.

   This tab lists all the Arcade functions. You can click the information button to the right of each function to access the function's integrated help on parameters, syntax, and usage.

8. Click the Help tab.

   This tab links to the Arcade documentation.

9. Click the Run button.

   

   The Output, Console and Log tabs appear. Once you've created your expression, you can use the Run button to test the output of your expression. For now, you have not written any Arcade code, so the Output and Log tabs do not contain much.

Create an Arcade expression for electricity consumption per capita

You'll now start building your Arcade expression to style the World Countries Electricity Consumption layer. You'll first define a variable to access the Annual Electricity Consumption (KwH) attribute field.

1. In the expression window, delete the first three lines, which are not needed.
2. Type (or copy and paste) var annualConsumptionKwh = .

   

   AnnualConsumptionKwh is the name of the new variable. Using var <variableName> initializes variables in memory for later use in the expression. You'll specify the variable value in the next step.

3. Click the Profiles variables tab. In the Profiles variables pane, click the arrow next to $feature.

   

4. Under Values, click the $feature.Annual_Electricity_Consumption_ variable.

   

   The string is copied in the expression window, completing your first line of code.

   Note:

   Annual_Electricity_Consumption_ is the name of the attribute, whereas Annual Electricity Consumption is the alias, a more user-friendly way of referring to the attribute.

5. In the expression window, press Enter to start the next line of the expression.

   

   Any further reference to the variable annualConsumptionKwh will access the Annual Electricity Consumption (KwH) attribute value for every feature in the layer (in this case, that's every world country).

   You'll now test the first line of your expression. A convenient way to test a variable is to ask Arcade to return its value. You can do that by using a return statement.

6. In the Expression window, type return annualConsumptionKwh, and press Enter.

   

7. Click the Run button.

   On the Output tab, the value 157200000 appears and Number is the data type.

   

   Note:

   To make testing expressions easier, the Arcade expression editor uses the layer's first feature (ordered by object ID) to populate the attributes with sample values. The first feature of the World Countries Electricity Consumption layer happens to be American Samoa, with an annual electric consumption of 157,200,000 kWh, and a population of 46,366.

   The result returned for your expression is indeed the annual electric consumption value for American Samoa: 157,200,000 (kWh). This is the value you expected, so your code functions as intended.

   Next, you'll define a variable to access the population field.

8. In the expression window, at the end of the first line of code, press Enter to add a new line. Type var population =.
9. If necessary, on the Profile variables tab, click the arrow next to $feature tab. Under Values select $feature.POP to add the population attribute value to the expression.

   You'll now use the return statement to test that new variable.

10. In the return line, replace annualConsumptionKwh with population.

    

    Note:

    The previous attribute used the ["field"] notation because it contained underscores. The POP field does not contain underscores, so Arcade uses a simpler notation. An advantage of adding an attribute through the Profile variables tab, instead of typing it, is that it chooses the correct format for you. It also avoids any misspellings.

11. Click Run.

    The Output is 46366, which is indeed the population value for American Samoa. Your code continues to behave as expected.

    The next step is to calculate the electricity consumption per capita. To do this, you'll use the values stored in the two variables and divide the annual electricity consumption by the population. You'll store the result in a third variable named consumptionPerCapita.

12. In the expression window, press Enter to add a new line before the line return population. Type var consumptionPerCapita = annualConsumptionKwh / population.
13. In the return line, replace population with consumptionPerCapita.

    

14. Click Run.

    The Output is 3390.415390587931, which is indeed the result of 157,200,000 divided by 46,366.

    To test a greater variety of cases, you can reassign the variable population with a literal number.

15. In the expression window, press Enter to add a new line after the line var population = $feature.POP. Type population = 40000.

    

16. Click Run.

    The result updates to 3930, which is indeed the result of 157,200,000 divided by 40,000.

17. Similarly, you can test your expression with different values for the annual electricity consumption and population fields.
18. Delete the population = 40000 line of code.

    Note:

    The return statement is not used only for testing—this is how the final result of the expression will be made available for use in the map. For instance, now that the final result is returned in your expression, you'll be able to use it to style the countries layer.

    The final expression is shown below.

    
    // Set variables
    var annualConsumptionKwh = $feature["Annual_Electricity_Consumption_"]
    var population = $feature.POP
    
    // Calculate the electricity consumption per capita
    var consumptionPerCapita = annualConsumptionKwh / population
    
    // Return the consumption per capita
    return consumptionPerCapita

    To make your code more readable, comments have been added.

    Note:

    To make your code more readable and easier to maintain in the future, it is a good idea to add comments, designated by // at the start of the line. Comments are ignored by Arcade and are only meant for the people who will read the code.

    You'll now give your expression a name. It is important to give the expression a meaningful name, because it will essentially function like the name of a new field in the layer. It will be used in the map's legend and will also help identify the expression later, when you reference it or if it needs to be edited.

19. Click the Edit button next to New expression.

    

    Note:

    You can also click the expression directly to edit the title.

20. In the New Expression text box, type Electricity consumption per capita (kWh), and click outside the text box.

    

21. Click Done.

    The Arcade editor window closes, and the expression is added to the list of attributes that can be used to style the World Countries Electricity Consumption layer.

22. From the Contents toolbar, click Save and open and choose Save.

    Saving the map will save anything that you have done in the map, including any expressions you have created.

Style the layer

You are now ready to style the World Countries Electricity Consumption layer using the Arcade expression you just created.

1. In the Styles pane, review the current settings.

   In the Styles pane, the new expression, Electricity consumption per capita (kWh) was applied automatically to symbolize the World Countries Electricity Consumption layer. By default, the drawing style Counts and Amounts (size) is selected.

   

   Since the layer is difficult to see, you'll temporarily turn off the Global Power Plants layer.

2. In the Layers pane, for Global Power Plants, click the visibility button to turn the layer off.

   

   The electricity consumption per capita for each country is represented by dots of different sizes.

   

   Note:

   Since each country has different total electricity consumption and population field values, the per capita result is different for each one, even though the Arcade expression is the same. This is what makes Arcade so powerful—it can look at the field values of specific features to return new values for each one on the fly. Another feature of Arcade that is demonstrated here is that you don't need to own the original data layers to generate new derived information.

   To better see the countries layer in conjunction with the power plants layer, you'll use a different symbolization.

3. In the Styles pane, choose the Counts and Amounts (color) drawing style.

   

   An intuitive, colorblind-friendly color ramp that is good for dark backgrounds is automatically selected for the Counts and Amounts style. The countries with low electric consumption per capita appear in dark blue, and the ones with high electric consumption per capita appear in bright turquoise blue.

   

   Note:

   When the background of your map is dark, the lowest values are shown in a darker color and the highest values are shown in a lighter or brighter value. This helps the highest numbers stand out.

4. Click Done to close the Styles pane.
5. In the Layers pane, turn the Global Power Plants layer back on.

   

   With the new styling, it is now possible to visualize both layers at the same time.

   You'll disable the informational pop-ups of the countries layer so that users can select the power plants features easily.

6. In the Layers pane, ensure the World Countries Electricity Consumption layer is selected and on the Settings toolbar, click Pop-ups.

   

7. In the Pop-ups pane, turn off the Enable pop-ups. Close the Pop-ups pane.

   

8. Save the map.

   Your map has now a visually intuitive style that shows patterns in electricity consumption per capita and power production around the world.

9. Review the map's content.

   

   You can compare your country to others at a glance. There is greater per capita electricity usage in highly industrialized countries in Western Europe and North America, as well as in major electricity-producing Gulf states. You can see that the countries with higher per capita electricity consumption tend to have a higher concentration of power plants, which makes sense. In developing countries, there are fewer power plants and lower electricity usage per capita.

You've created a map and visualized power plants with a cluster symbolization. You then used an Arcade expression to visualize annual electric consumption per capita across the world.

Configure a pop-up using Arcade

Previously, you became familiar with Arcade and used an Arcade expression to symbolize the world countries layer. Next, you'll use an Arcade expression to display the data from the power plants layer in an informational pop-up. This will enable you to better understand power plant electricity production.

Explore the Global Power Plants attributes and pop-ups

First, you'll explore Global Power Plants attributes and look at the layer's pop-ups.

In the Global Power Plants layer, there is an attribute that gives the estimated annual power generation for each power plant, expressed in gigawatt-hours (gWh). The name of that attribute is estimated_generation_gwh. This is useful, but you would like to express the power generation value as something easier to understand for the general public: the number of 60-watt light bulbs that the power plant could power for a year. You'll use an Arcade expression to make that conversion, and you'll display the new value in a sentence in the layer's pop-up. Because some of the power plants are missing a value for the estimated_generation_gwh attribute, you'll also need to handle those absent values in the Arcade expression.

First, you'll examine the attribute table for the power plants layer.

1. If necessary, sign in to ArcGIS Online. On the toolbar, click Content, and browse to the Global Power Generation and Consumption map you created in module 1.

   

2. Click the option menu next to the Global Power Generation and Consumption web map, and choose Open in Map Viewer.

   

3. In the Layers pane, for the Global Power Plants layer, click the Options button and click Show table.
4. In the Global Power Plants attribute table, review the fields. Use the horizontal scroll bar to see all the fields.

   

   Among the several attributes of that layer, notice the following:

   • The country_long field indicates the name of the country where the power plant is located.
   • The name field contains the name of the power plant.
   • The fuel field indicates the type of the power plant.

   Note:

   You may need to widen the column to see the entire attribute field alias.

5. Scroll to the last column of the table, estimated_generation_gwh.

   As mentioned, this field contains the estimated annual power generation for the power plant, expressed in gigawatt-hours (gWh). A gigawatt-hour is a million times the electricity of a kilowatt-hour.

6. Close the Global Power Plants attribute table.

   Next, you'll explore the pop-ups for the layer.

7. On the map, zoom in to an area of interest.

   Note:

   Since you have enabled clustering on the Global Power Plants layer, you'll need to zoom the map until the clusters dissolve into single features to see the individual feature's pop-up.

8. On the map, select a Global Power Plants feature to view the original pop-up for the layer.

   

The pop-up already displays some helpful information, mentioning the type of the power plant and its capacity. You will supplement the pop-up with an additional piece of information: the power plant's annual power generation.

Convert power generation units with Arcade

You'll now open the Arcade expression editor window to build the new expression. Because your goal is to customize the pop-up, you'll open the expression editor through the Pop-ups configuration pane.

1. In the Layers pane, ensure the Global Power Plants layer is selected.

   

2. On the Settings (light) toolbar, click Pop-ups. In the Pop-ups pane, click Attribute expressions.

   

   You'll now create the new Arcade expression.

3. Click Add Expression to open the Arcade expression editor window.

   

   The editor window appears.

   Note:

   The Global Power Plants layer already has an existing expression, Pop-up color. It is used to generate the symbolization colors based on the fuel type.

   You'll name your expression.

4. Edit the title of the expression to be Estimated Annual Generation in Lightbulbs.

   

   You'll now start building your Arcade expression. First, you'll create a variable, yearLightbulbPower, that contains the number of kilowatt-hours of electricity required to power a 60-watt light bulb for a year.

   A 60-watt incandescent light bulb uses 60 watt-hours or .06 kilowatt-hours of electricity for each hour it's on. To find the kilowatt-hours of electricity required to power a 60-watt light bulb for a year, you'll multiply .06 kilowatt-hours by 24 hours, and then by 365 days.

5. In the expression window, delete the three lines of comments.
6. Type (or copy and paste) var yearLightbulbPower = 0.06 * 24 * 365.

   Next, you will add a return statement to test the variable.

7. Press Enter and type return yearLightbulbPower.

   

   Next, you will run your code.

8. Click the Run button.

   On the Output tab, the value is 525.6. This is indeed the result of 0.06 * 24 * 365, so your code is functioning as expected.

   

   Next, you'll create a variable containing the power plant's name using the name field from the Global Power Plant layer.

9. In the expression window, add a new line before the return statement and type var plantName =.

   

10. In the Profile variables tab, click the arrow beside $feature.

    

    The list of attributes for the power plant layer appears.

    Note:

    The Profile variables tab looks a bit different than when you configured the symbology for the world countries layer in the previous module. This is because pop-ups allow you to use additional profile variables such as FeatureSets.

11. Under the Values list, scroll down, and click $feature.name to complete your line of code.
12. In the return statement, replace yearLightbulbPower with plantName to test your second variable.

    

13. Click the Run button.

    In the Output table, the value is Kajaki Hydroelectric Power Plant Afghanistan. This is the name of the first power plant listed in the attribute table, which has been assigned by default as sample data.

    In the next step, you'll create a variable, annualGenerationGwh, containing the annual electricity generation attribute value.

14. In the expression window, add a new line before the return statement, type var annualGenerationGwh =.
15. On the Profile variables pane, click $feature["estimated_generation_gwh"].
16. In the return statement, replace plantName with annualGenerationGwh to test the latest variable.

    

17. Click the Run button.

    On the Output tab, there seems to be no value, and is listed as Null. This is not the expected result, so it needs to be investigated further.

    

    You'll check if the current sample value for that attribute is empty or not. The Arcade function to test whether or not a variable is empty is IsEmpty. The IsEmpty function returns true if the provided value is null or an empty text (e.g. ''). It returns false for all other cases, including empty arrays and dictionaries.

18. In the expression window, for var annualGenerationGwh = $feature["estimated_generation_gwh"], replace $feature["estimated_generation_gwh"] with IsEmpty($feature["estimated_generation_gwh"]).

    

19. Click Run.

    On the Output tab, the value is shown in Boolean and is True.

    

    This indicates that the Kajaki Hydroelectric Power Plant Afghanistan does not have a value for the estimated_generation_gwh attribute. Hence, the test produced an empty or result previously.

    Note:

    You will need to take care of those special cases of missing data in your Arcade expression. However, you will do that later in the tutorial. For now, you will complete the code for the regular case, when the attribute value is present.

    To continue developing your Arcade expression, you'll manually set a sample value of 10 gwh.

20. In the expression window, for var annualGenerationGwh = IsEmpty($feature["estimated_generation_gwh"]), delete the IsEmpty function and the beginning and end parenthesis.

    

    The expression is back to the previous format.

21. Pess Enter to add a new line after the line var annualGenerationGwh = $feature["estimated_generation_gwh"]. Type annualGenerationGwh = 10.
22. Click the Run button again.

    On the Output tab, the value is now 10, as expected, and the data type is Number.

    

    Next, in your Arcade code, you want to calculate the annual electricity generation in 60-watt light bulbs based on the value of the annualGenerationGwh variable. The first step is to convert the value from kilowatt hours (kWh) to gigawatt hours (gWh) and put the result in a new variable. There are one million kWh in a gWh, so you need to multiply the annualGenerationGwh variable by one million to convert it to kWh.

23. Add a new line above the return statement, type var annualGenerationKwh = annualGenerationGwh * 1000000.
24. In the return statement, replace annualGenerationGwh with annualGenerationKwh.

    

25. Click Run to evaluate the expression.

    The result is 10,000,000, which is the expected result, since your sample value is 10.

    

In this section, you started developing your second Arcade expression. You defined several variables and converted the annual electricity generation value from gWh to kWh.

Perform computations and format text with Arcade

You'll now perform the main computations in your Arcade expression. Then you'll format the result to display it as text.

First, you'll calculate the number of 60-watt light bulbs the plant could power for a year by dividing the annual electricity generation in kWh (annualGenerationKwh) by the number of kWh required to power a 60-watt light bulb for a year (yearLightbulbPower).

Note:

Remember that the variable yearLightbulbPower contains the result of 0.06 * 24 * 365, which is 525.6.

1. Add a new line above the return statement, type var annualGenInLightbulbs = annualGenerationKwh / yearLightbulbPower.
2. In the return statement, replace annualGenerationKwh with annualGenInLightbulbs.

   

3. Click Run to evaluate the expression.

   The Result value is 19025.87519025875, which is the expected result of 10000000 / 525.6. That's about 19,025.87 light bulbs.

   

   However, it makes more sense to return the number of light bulbs as a whole number rather than a decimal. Arcade can help you do that using the Round function.

4. Add a new line above the return statement, type var annualGenInLightbulbsRounded =.

   You'll now look for the Round function on the Functions tab.

5. Click the Functions tab. In the search text field, type round.

   

   The Round function appears.

6. Click the Round function to insert it in the expression window

   The Round function adds to the expression with a placeholder parameter indicated in the parenthesis.

   

   You'll review the information on the function in the in-app help to better understand what parameters are expected.

7. On the Functions tab, click the arrow next to the Round function.

   

8. Review the information for the Round function.

   

   The first parameter is the number to be rounded, in your case, the variable annualGenInLightbulbs. The second parameter indicates the number of decimal places to round the number to. You'll keep the default 0, so 19025.87519025875 should be rounded to 19026, with 0 decimals after the point.

9. When you are done reviewing the information about the Round function, click the arrow next to Functions to exit the in-app help.

   

10. Modify the annualGenInLightbulbsRounded line to read as follows:

    var annualGenInLightbulbsRounded = Round(annualGenInLightbulbs, 0)

    Note:

    The parameters of a function should always appear between parentheses and be separated by a comma.

11. In the return statement, replace annualGenInLightbulbs with annualGenInLightbulbsRounded.

    

12. Click Run to evaluate the expression.

    The result is 19026, as expected. That's 19,026 light bulbs.

    

    You have successfully calculated the number of 60-watt light bulbs that each power plant could supply in electricity for in a year. However, you are not done yet. Next, you will format the number to make it readable and create a sentence to put the number in context.

    Like other programming languages, Arcade has a method to convert a number to text. This function is named Text. You'll create a new variable to hold the number of light bulbs in text form.

13. Add a new line above the return statement, type var annualGenInLightbulbsText = .

    You'll now look for the Text function in the Functions tab.

14. On the Functions tab, search for text. Under the Text functions list, click the Text function to insert it in the expression window.

    The new line looks like this:

    var annualGenInLightbulbsText = Text(value)

    You'll review the information on this function in the in-app help to better understand what parameters are expected.

15. On the Functions tab, click the arrow next to the Text function.

    The first parameter is the number to be transformed to text—in your case, the variable annualGenInLightbulbsRounded. The second parameter is a template that expresses the desired format. For instance, the default '#,###' template will add a thousands separator comma. This means that a number written as 9563 will become 9,563.

16. When you are done reviewing the information, click the back arrow to exit the in-app help.
17. Modify the annualGenInLightbulbsText line to read as follows:

    var annualGenInLightbulbsText = Text(annualGenInLightbulbsRounded, '###,###,###,###')

    Note:

    The template '###,###,###,###' will add separators for larger numbers than the default '#,###' gave. Since you are expecting values in the millions and greater, you need a longer mask. For instance, a number written as 735790325 will become 735,790,325.

18. In the return statement, replace annualGenInLightbulbsRounded with annualGenInLightbulbsText.

    

19. Click Run to evaluate the expression.

    The Output is "19,026", with a comma inserted, as expected. Also, the type is now Text..

    

    The next step is to create a full sentence that contains the text-formatted number and explains what it means. You'll use a template literal to accomplish this.

    Note:

    A template literal is a way in Arcade to insert variable values and expressions into a string. Template literals are enclosed with backticks (`) and use the syntax ${variableName} to insert variables, expressions, or any other nonstring value into the string. You can learn more about template literals in the ArcGIS Arcade Structure and Logic help topic.

20. In the Expression window, add a new line before the return statement, type the following:

    var popupSentence = `It's estimated that ${ plantName } generates enough electricity to power ${ annualGenInLightbulbsText } 60-watt incandescent light bulbs for a year.`

    Note:

    The template literal must be on a single line in the Arcade editor, as moving to the next line will generate a multiline output.

21. On the return statement line, replace annualGenInLightbulbsText with popupSentence to test the latest variable.

    

22. Click the Run button.

    On the Output tab, the value is the entire sentence, where the variables ${plantName} and ${annualGenInLightbulbsText} have been replaced with their current values.

    

23. In the expression window, delete the annualGenerationGwh = 10 code.
24. Click Done to save your expression and close the Arcade expression editor window.
25. On the collapsed Contents toolbar, click Save and open and click Save to save your overall changes to the map.

    

In this section, you computed the number of 60-watt light bulbs that each power plant could supply in electricity for in a year, you formatted that number to make it more readable, and you created a sentence to put the number in context.

Add the Arcade expression to a pop-up

You will now add your saved Arcade expression to the pop-up and test it on a Global Power Plants layer on the map.

1. In the Attribute expressions pane, click the back button.

   

2. In the Pop-ups pane, click Text and click Edit text.

   

   The pop-up text editor opens, showing the text that currently displays in the pop-up for the Global Power Plants layer. You'll add the result of your Arcade expression to the existing text.

3. In the pop-up text editor, place your cursor on the next line below the existing text. Type a single brace: {.

   A list of available fields and Arcade expressions appears.

   

4. Scroll down the list and select the expression you just created, Estimated Annual Generation in Lightbulbs.

   

   Note:

   You can see that the Arcade expression you created is listed like any of the other attribute fields that are available. You can recognize it easily, thanks to the meaningful name you gave it earlier.

5. The expression is added with the unique identifier {expression/expr1}.

   

6. Click OK.

   The pop-up preview updates with the custom Arcade expression you configured.

   

   You will now open a pop-up on the map for a specific power plant to see how your Arcade expression displays.

7. On the map, on the vertical toolbar, click the Search button.

   

8. In the search box, type Kitzingen, Bayern, Germany and press Enter.

   The map zooms in to the town of Kitzingen in Germany.

9. Click the power plant west of the Kitzingen label. It is symbolized in light green because it is a solar power facility.

   

   The pop-up opens and the message you created displays. The sentence includes the number of 60-watt light bulbs that the power plant could power for a year: 146,258.

   

10. Close the pop-up.

    You successfully created an Arcade expression and displayed it in the pop-up for the Global Power Plants layer. However, you still have not taken care of the special case, when a power plant does not have a value in the estimated_generation_gwh field. You will do that in the next section.

Test the special case of missing data

You'll now handle the case when the attribute data is missing. First, you'll examine how the pop-up looks in such a case.

1. Click the Search button. In the search box, type Antananarivo, Analamanga, Madagascar and press Enter.

   The map zooms in to the town of Antananarivo in Madagascar.

2. Click the power plant northwest of the Antananarivo label. It is symbolized in red because it is an oil power facility.

   

   The pop-up opens and the message you created displays. However, the number of 60-watt light bulbs mentioned is 0.

   

   This is misleading: the power plant is not estimated to generate 0 gWh in a year; rather, there is no annual electricity generation data. In such cases, it would be better to have a different message clearly saying that there is no data available. You'll go back to the Arcade expression to implement this more accurate behavior.

3. Close the pop-up.
4. In the Layers pane, confirm that the Global Power Plants layer is selected.
5. On the Settings toolbar, click Pop-ups. In the Pop-ups configuration pane, click Attribute expressions.
6. Click the Estimated Annual Generation in Lightbulbs expression to open it in the editor window.

   

7. In the editor window, click the Run button to verify that you obtain the same behavior as in the pop-up.

   

   On the Output tab, the value includes the same sentence as in the pop-up with the misleading number of 0 light bulbs.

   Note:

   Remember that by default, the Arcade editor uses the first power plant in the layer, Kajaki Hydroelectric Power Plant Afghanistan, and you saw previously that this power plant does not have a value for the estimated_generation_gwh field.

Add code to handle missing data

You'll now add code to your expression to better handle the case when there is missing data.

To better handle the case where there is missing data, the Arcade expression needs to test whether the value of the estimated_generation_gwh field is empty or not.

• If it is, you'll return a message about the data being missing.
• If it is not, you'll proceed with building the message about the 60-watt light bulbs.

You will use the IsEmpty function again. You'll store the result of that test in a new variable, generationCheck. You want to perform the test as soon as possible, so you'll add the new code immediately after you have read the value of the estimated_generation_gwh field.

1. In the Expression window, add a line after the line that begins with var annualGenerationGwh.

   

2. Type var generationCheck = .
3. Click the Functions tab, and search for IsEmpty function.

   

4. Click the IsEmpty function to add it to your line of code.

   

5. On the Functions tab, click the arrow next to the IsEmpty function to learn how it works.

   

   IsEmpty takes in a single parameter (in your case, it will evaluate the estimated_generation_gwh field). If the value is null or an empty string, the function returns true; otherwise, it returns false. You'll store the output of IsEmpty in a variable, and then evaluate the variable to check if it is true or false.

6. When you are done reviewing the information on isEmpty, click the back arrow next to Functions.
7. In the Expression window, replace the placeholder text value with annualGenerationGwh. The entire line should be as follows:

   var generationCheck = isEmpty(annualGenerationGwh)

   Next, you'll add code to decide what to do based on the value of the generationCheck variable. To do that, you'll use an if statement (also called a conditional statement). The syntax for this statement is if (condition is true) {do something}. You can learn more about conditional statements in ArcGIS Arcade Structure and Logic.

8. Add a new line after the line that begins with var generationCheck.
9. In the new line, type if (generationCheck) {. Press Enter.

   

   Note:

   Because the generationCheck variable contains true or false, you are essentially asking Arcade if(true) or if(false). The instructions within the brackets will only be executed if generationCheck is true.

   You'll now write the code to perform the desired action when estimated_generation_gwh is empty. Between the brackets, you'll create the message to display. Just like before, you will use a template literal and store it in a new variable.

10. In between the brackets, type for copy and paste the following text (all on one line):

    var noGenerationTL = `${ plantName } does not have estimated annual generation data. Unable to return electricity generation in 60w incandescent light bulbs.`

    The expression uses the plantName variable you had set earlier in your code.

    Finally, you'll add a return statement to return that message.

11. Add a new line above the closing bracket and type return noGenerationTL.

    

12. Click Run to test your script.

    

    This time, the message does not talk misleadingly about 0 light bulbs. Instead it explains that there is missing data for the Kajaki Hydroelectric Power Plant Afghanistan power plant.

    Note:

    It is important to understand that when Arcade executes a return statement, it considers that it is the end of the code execution, and any remaining code below that statement is ignored. This is the behavior you want, since the remaining code only applies to features that have data for the estimated annual electricity generation.

Perform more tests with a console statement

As a final task in the Arcade expression editor window, you will now learn a different method to test your Arcade expression. So far, you used return statements to view the output of your script. However, there may be cases where you also want to visualize the value of variables throughout your code. To view those, you can use console statements that will write the value of your variables of interest to the Console tab. For instance, you may want to see the value of the variable generationCheck.

1. In the Expression window, add a new line after the line that begins with var generationCheck.
2. In the new line, type console("generationCheck value:", generationCheck).

   

   The first parameter gives some explanation of the object you are logging to the console. The second parameter is the object itself.

3. Click the Run button.

   The Output tab looks the same as before, showing the final result of the Arcade expression.

4. Switch to the Console tab to see the variable value logged to the console.

   

   The value held in the variable generationCheck is true, because the value for estimated_generation_gwh is empty.

5. Try other sample values for $feature["estimated_generation_gwh"], and test the expression for each one, looking at the Output and Console tabs. Include examples that yield either a true or false value for generationCheck.

   Note:

   You can add as many console statements as you want to help you develop and debug your Arcade expression. However, it is recommended that you remove or comment out those statements once the expression is finalized.

   Since this line of code was for testing purposes, you will now comment out the console statement.

6. At the beginning of the console statement, type //.

   

   The console statement is now a comment and will not run as a command.

   The example below shows what the final expression looks like. Comments have been added to describe each step.

   
   // Calculate the kilowatt-hours (kWh) required to power a 
   // 60w light bulb for a year
   var yearLightbulbPower = 0.06 * 24 * 365
   
   // Save the power plant name and annual generation to a variable 
   // for later use
   var plantName = $feature.name
   var annualGenerationGwh = $feature["estimated_generation_gwh"]
   
   // Check if there is a value in the estimated annual generation 
   // attribute field. isEmpty(fieldOrValue) returns true if empty
   var generationCheck = isEmpty(annualGenerationGwh)
   
   // Write to the generationCheck value to the Message tab for 
   // testing purposes (commented out)
   // console("generationCheck value:", generationCheck)
   
   // If there is not annual generation data, return a sentence for use
   // in the pop-up that informs the user about this.
   if (generationCheck) {
       var noGenerationTL = `${ plantName } does not have estimated annual generation data. Unable to return electricity generation in 60w incandescent light bulbs.`
       return noGenerationTL
   } 
   
   // If the annual generation data is present, continue with the remainder of the script. 
   // Convert the annual generation attribute from
   // gigawatt-hours to kilowatt-hours
   var annualGenerationKwh = annualGenerationGwh * 1000000
   
   // Compute the annual electricity generation in light bulbs
   var annualGenInLightbulbs = annualGenerationKwh / yearLightbulbPower  
     
   // Round the number 
   var annualGenInLightbulbsRounded = Round(annualGenInLightbulbs, 0)  
     
   // Format the number to add thousand separators    
   var annualGenInLightbulbsText = Text(
       annualGenInLightbulbsRounded, '###,###,###,###')
   
   // Build the sentence for use in the pop-up 
   // (Create a string using a template literal)
   var popupSentence = `It's estimated that ${ plantName } generates enough electricity to power ${ annualGenInLightbulbsText } 60-watt incandescent light bulbs for a year.`
   
   // Return the value
   return popupSentence

   Note:

   Since the sentence handling missing data is inside an if statement, you can optionally enclose the rest of your Arcade expression in else {<rest of expression>}. However, without explicitly writing else {}, as you have seen, the rest of expression will continue to execute if the condition in the if statement isn't met.

   You'll now close the Arcade expression editor and test the pop-ups on the map.

7. Click Done to save your expression and close the editor window.

   The pop-up preview for Mandroseza now displays the appropriate message.

   

8. In the Pop-up expressions pane, click the back button. Close the Pop-ups pane.
9. Save the map.
10. Click several power plants on the map to check that your Arcade expression is working properly.

    Note:

    You can search for the same two locations as before ( Kitzingen, Bayern, Germany and Antananarivo, Analamanga, Madagascar). You can also try new ones.

You've calculated the amount of electricity it takes to power a 60-watt light bulb for a year and the number of 60-watt light bulbs that each power plant could power for a year. You rounded a value to a whole number and added thousand separators. You created two different sentences that can be returned to the popup – one for scenarios when the annual electricity generation data for the power plant is present, and another one for when the data is present. You then ensured that power plant features on the map show the appropriate sentence by using an if statement.

In this tutorial, you became familiar with the Arcade expression editor. You used Arcade to symbolize world countries by electricity consumption per capita. You used Arcade to understand the number of 60-watt light bulbs that each power plant could power for a year and displayed the result in a pop-up. All the Arcade code was executed on the fly, without impacting the underlying data.

This tutorial covered only some of what you can do with Arcade. To learn more about labeling expressions and calculating fields in Arcade, explore Pump up Your Pop-ups With Arcade FeatureSets and the Living Atlas and Bring Colors From Your Map Into Your Pop-up Using Arcade.

You can find more tutorials in the tutorial gallery.

Acknowledgements

• The population and electricity consumption data comes from CIA World Factbook.
• The global power plant data comes from the World Resources Institute.