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, you can sign up for an ArcGIS free trial.

  2. On the ribbon, click Map.

    Map button

    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.

    Map Viewer

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

  4. In the Layers pane, click Add.

    Add button

  5. Click My Content and choose ArcGIS Online.

    ArcGIS Online option

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

    The Global Power Plants layer appears in the search results.

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

    Search for global power plants.

    The layer is added to the map. It 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, search for electricity consumption owner:Learn_ArcGIS.
  9. For the World Countries Electricity Consumption search result, click Add.

    The layer is added to the map. It 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.

    Back button

  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.

    Both layers displayed

    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.

    Aggregation button

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

    Enable clustering slider button

    Clustering is enabled by default.

  15. For Clustering, click on Options.

    Clustering 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.

    Cluster radius and size options

    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.

    Close the Clustering pane.

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

    Dark Gray Canvas basemap.

  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.

    Collapse the Contents toolbar.

    Next, you'll save the map.

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

    Save as on the Save and open menu

  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.

    Save map window

  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 Layers.

    Layers button

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

    Show table menu option

    The attribute table appears.

    Note:

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

    Attribute table

    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.

    Styles on the Settings toolbar

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

    Styles pane

    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.

    Arcade expression editor

  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.

    Test 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 = .

    Declare the first variable

    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.

    Profile variables

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

    Insert the first attribute field.

    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.

    First complete line of code

    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.

    Add the first return statement.

  7. Click the Run button.

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

    First test result

    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.

    Create population variable

    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.

    Create the consumptionPerCapita variable.

  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 = 4000.

    Declare a variable with a literal value

  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 = 4000 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.

    New expression Edit button

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

    Rename expression name

  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.

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.

    New expression's default style

    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.

    Turn off the layer

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

    Map with Counts and Amounts (size) symbolization

    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.

    Choose the new 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.

    Map with Counts and Amounts (color) symbolization

    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, select Pop-ups.

    Pop-ups on the Setting toolbar

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

    Disable pop-ups.

  8. On the collapsed Contents toolbar, click Save and open and click Save to save your changes to the map.

    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.

    Final map symbolization

    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.

    Content button on

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

    Open in Map Viewer option

  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.

    Global Power Plants attribute table

    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.

    Default pop-up

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.

    Global Power Plants selected

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

    Pop-ups pane

    You'll now create the new Arcade expression.

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

    Add expression button

    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. Click the Edit button next to New expression.

    Edit button

  5. In the New expression text box, type Estimated Annual Generation in Lightbulbs and click outside the text box.

    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.

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

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

  8. Press Enter and type return yearLightbulbPower.

    First two lines of the new expression

    Next, you will run your code.

  9. 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.

    Result of the yearLightbulbPower variable

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

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

    Second variable

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

    Arrow to expand the feature item

    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.

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

    Complete second line of code

  14. 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.

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

    Create the annualGenerationGwh variable.

  18. 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.

    Null result

    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 IsEmtpy 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.

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

    Check if the value is empty

  20. Click Run.

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

    Boolean value is true for the record

    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.

  21. 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.

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

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

    Test result is 10.

    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.

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

    Create the annualGenerationKwh variable.

  26. Click Run to evaluate the expression.

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

    Test result is 10000000.

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.

    Create the annualGenInLightbulbs variable.

  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.

    Test result is 1902587.

    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.

    Round function

    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.

    Round function added to expression with two placeholder parameters

    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.

    Information button

  8. Review the information for the Round function.

    Help for 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.

    Return to function list button

  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.

    Create the annualGenInLightbulbsRounded variable.

  12. Click Run to evaluate the expression.

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

    Test result is 19026.

    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.

    Create the annualGenInLightbulbsText variable.

  19. Click Run to evaluate the expression.

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

    Test result is 19026 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.

    Create the popupSentence 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.

    Test result is a sentence.

  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.

    Save 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.

    Back button

  2. In the Pop-ups pane, click Text and click the text that appears below.

    Text element

    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.

    Insert a brace.

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

    Select the expression in the drop-down list.

    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}.

    Complete pop-up text

  6. Click OK.

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

    Preview of the pop-up for the Global Power Plants layer

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

  7. In the Settings toolbar, click Map tools and click Search.

    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.

    Kitzingen power plant on the map

    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.

    Text in the pop-up for Kitzingen

  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. On the Settings toolbar, click Map tools and then click Search. 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.

    Antananarivo pop-up on the map

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

    Text in pop-up for a missing value

    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.

    Reopen the Arcade expression editor.

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

    Test result showing zero watts

    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.

    Add line after the line var annualGenerationGwh

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

    Search for the IsEmpty function.

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

    Add the IsEmpty function to the code.

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

    Information button for IsEmpty

    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 and type a closing bracket, }.

    Add the If statement.

    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.

    Add a Return statement in the If condition.

  12. Click Run to test your script.

    Run the new message for missing data.

    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).

    Add a Console statement.

    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.

    Go to the Messages tab.

    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 //.

    Comment out the Console statement.

    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.

    The new text displays in the pop-up when there is a missing value.

  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.