Window API

The Window API contains functionality for working with the current browser window. 

Some of the functionality in the Window API includes:

• Retrieving information about the current visitor's physical location and browser locale settings.
• Determining what type of device the current visitor is using to view your site.
• Working with popups and modal windows.
• Working with the multilingual capabilities of your site.
• Copying text to the visitor's clipboard.
• Scrolling the current page by a certain amount or to a certain location.
• Sending tracking information to external analytics tools.

Let's take a closer look at a couple of these.

Location

Sometimes, you want to know the physical location of your visitors. For example, you might want to show them some location-based information, such as nearby restaurants or other attractions.

You can retrieve a visitor's physical location using the getCurrentGeoLocation() function. Of course, the accuracy of the location data you get depends on the type of device used to view your site as well as other factors. So keep that in mind when making use of this location data.

Another issue to keep in mind when retrieving location data is that the environment you are trying to retrieve the location data from can affect how you get that data, if you get it at all.

Some browsers require visitors to explicitly agree to sharing their location data with you. This usually takes the form of a popup asking visitors if they want to allow your site to retrieve their location data. If they do not agree, the Promise returned by the getCurrentGeoLocation() function rejects.

These protections on the sharing of visitor location data mean you always have to be aware of the possibility that you won't be able to retrieve the visitor's location data and handle it accordingly.

Let's take a look at a simple example that uses the site visitor's location data to show a map of where the visitor is currently located. We display the visitor's location using a GoogleMap element that we've given the ID googleMap. We've set the map to be hidden when the page loads in case we can't retrieve the visitor's location.

Here you can see that we call the getCurrentGeoLocation() function. If the returned Promise resolves, we set the map element's location to the current visitor's location using latitude and longitude coordinates and show the map.

If the Promise rejects or if it doesn't resolve, the map will remain hidden.

Popup

Popups are great for grabbing the attention of your site's visitors. Common use cases include displaying promotional material, encouraging visitors to join a mailing list, or confirming an action such as data deletion.

You can open a popup on your site using the openLightbox() function from page code. You choose which popup to open by passing the popup's name when calling the function.

When you open a popup, it opens on top of the page and runs its own code, which is not connected to the code of the page that opened it. 

When a visitor closes a popup that you opened in code, the Promise returned from the openLightbox() function is resolved and you can then handle the closure of the popup.

You can also pass data from your page to the popup when calling the openLightbox() function by passing the data to the function.

You can only pass data to a popup if you open it using code. So, if you're passing data to a popup, you need to make sure there are no other triggers for opening the popup. You need to make sure the popup is not set to open automatically and there are no links set to open it. 

Once a popup is open, you can retrieve any data you sent to it from your page using the getContext() function.

If you want to send information back to the page that opened a popup, use the close() function to close the popup and return the visitor to the page. If you're passing information with the closing of the popup, you might have to disable all the other ways the popup can be closed.

The code below demonstrates the passing of data from a page to a popup and from a popup back to the page.

The page code creates a message and opens a popup. It sends the message when opening the popup.

On the other end, the popup retrieves the message that was sent from the page and displays it in a text element.

Then, the code creates an onClick event handler for the popup's close button. When the close button is clicked, a message is created and sent back to the page when closing the popup.

Finally, back on the page, the message sent from the popup is retrieved and displayed in a text element.