Dynamically control your maps using URL parameters

Context

URL parameters allow you to share multiple versions of the same map, without having to rebuild it depending on different user requirements. This tutorial will guide you through embedding a Builder map in a low code tool that can be controlled using URL parameters to update the map's view based on users input. Through these steps, you'll learn to make your embedded maps more engaging and responsive, providing users with a seamless and interactive experience.

Resources for this tutorial:

In this tutorial, we're providing you with an existing Builder map as a hands-on example to guide you through the process. This example map highlights historic weather events. If you're interested in creating a similar map, this tutorial is for you.

• Public map URL: https://clausa.app.carto.com/map/5d942679-411f-4ab7-afb7-0f6061c9af63

• Embed code:

  <iframe width="640px" height="360px" src="https://clausa.app.carto.com/map/5d942679-411f-4ab7-afb7-0f6061c9af63"></iframe>

Step-by-Step Guide:

In this guide, we'll walk you through:

• Accessing your map URL and embed code

• Dynamically updating URL parameters in Builder

• Updating an embedding map using URL parameters

Accessing your map URL and embed code

To access your map's URL and/or embed code, first ensure that your map has been shared — either within your organization, with specific groups, or publicly. After sharing the map, you can proceed with the following steps:

1. Map Link: This direct URL to your map can be quickly obtained in two ways:

   • Through a quick action from the 'Share' button.

   • Within the sharing modal in the left bottom corner.

2. Embed code: This is specifically available within the sharing modal:

   • Navigate to the sharing settings of your map.

   • Look for the "Developers and embedding" section. Here, the embed code is provided, allowing you to copy and paste it into the HTML of your site or application for seamless embedding.

Dynamically updating URL parameters in Builder

Leveraging URL parameters with Builder maps enables dynamic customization for specific audience views without creating multiple map versions. This method simplifies sharing tailored map experiences by adjusting URL parameters, offering a personalized viewing experience with minimal effort.

In the viewer mode of a Builder map, any modifications you make are instantly updated in the URL. For example, if you zoom to a specific level in the loaded Builder map, the zoom level gets added to the URL. Here's how it looks:

https://clausa.app.carto.com/map/5d942679-411f-4ab7-afb7-0f6061c9af63?zoom=4

Below you can see how when you interact with the map: navigating, filtering widgets, parameters, etc. automatically change the URL displaying that specific map view.

Updating an embedding map using URL parameters

You also have the option to manually insert URL parameters to customize your map's viewer mode further. This option is particularly useful for tailoring map content to specific user queries or interests when the map is embedded, making the application more engaging and interactive.

In this section we'll illustrate how to integrate a Builder map in a custom application using Retool, a development platform for creating apps rapidly.

1. Begin by inserting an iFrame component in your Retool application. In the URL section, use your map URL. You can use the provided map URL: https://clausa.app.carto.com/map/5d942679-411f-4ab7-afb7-0f6061c9af63.

1. Add a container in Retool to neatly organize UI components that will interact with your map.

2. Implement UI elements to enable users to filter the map view based on criteria like state, type of severe weather event, and the event's date range. Start by adding a multi-select dropdown to allow users select a specific state. Name this element as State, and pre-fill it with the names of all U.S. states in alphabetical order:

["Alabama","Alaska","Arizona","Arkansas","California","Colorado","Connecticut","Delaware","District of Columbia","Florida","Georgia","Hawaii","Idaho","Illinois","Indiana","Iowa","Kansas","Kentucky","Louisiana","Maine","Maryland","Massachusetts","Michigan","Minnesota","Mississippi","Missouri","Montana","Nebraska","Nevada","New Hampshire","New Jersey","New Mexico","New York","North Carolina","North Dakota","Ohio","Oklahoma","Oregon","Pennsylvania","Rhode Island","South Carolina","South Dakota","Tennessee","Texas","Utah","Vermont","Virginia","Washington","West Virginia","Wisconsin","Wyoming"]

1. Include a checkbox group element named Event. This component will enable users to select the type of severe weather event they are interested in, such as hail, tornadoes, or wind, with one option set as the default.

1. Add two date pickers, one named as StartDate and the other EndDate. These components will define the timeframe of the event, providing default start and end dates to guide the user's selection. For the provided map example, let's ensure we are matching the temporal frame of the weather events by setting the start date to 1950-01-03 and end date to 2022-01-03.

1. Create a transformer named mapUrlParameters to dynamically construct the iframe's URL based on the user's selections. Use JavaScript to fetch the values from the UI components and assemble them into the URL parameters.

const paramState = {{State.value}}
const eventType = {{Event.value}}
const startDate = {{StartDate.value}}
const endDate = {{EndDate.value}}

const urlParameters = `?param_state=${paramState}&param_event_type=${eventType}&param_event_date_from=${startDate}&param_event_date_to=${endDate}`

return urlParameters

1. Add a button component labelled Apply that, when clicked, updates the iFrame URL with the new parameters selected by the user. This action ensures the map is only refreshed when the user has finalized their choices, making the map interaction more efficient and user-friendly.

1. To further enhance user experience, implement a secondary event that zooms to the map's focal point in the iFrame when the "Apply" button is clicked. This ensures the map is centered and zoomed appropriately for the user.

Additionally, customize your application by adding headers, more interactive elements, and so on, to increase usability and aesthetic appeal.