Widgets

Getting Started with your First Widget

This guide will help with:

Choosing a widget from DTN’s catalog
Integrating a widget on your site
Customizing the widget’s behavior

DTN has many widgets to choose from. Visit the DTN Widget Catalog to view the available widgets.

For this guide we will be using the DTN Interactive Map as an example.

Once you’ve chosen the widget you want to integrate, the first step is to find where the script is hosted. Using the DTN Interactive Map Widget for our guide, we can find that by visiting the documentation for that widget and reading the installation instructions.

https://cp-docs.dtn.com/content-packages/ui-widgets/interactive-map-widget/interactive-map-widget-1.0-latest.js

Now you can add the required script tag to your site.

<script src="https://cp-docs.dtn.com/content-packages/ui-widgets/interactive-map-widget/interactive-map-widget-1.0-latest.js"></script>

We recommend setting the defer attribute and placing the script tag directly before the closing body tag for the best performance.

<script defer src="https://cp-docs.dtn.com/content-packages/ui-widgets/interactive-map-widget/interactive-map-widget-1.0-latest.js"></script>

Once you’ve loaded the script, a new global namespace of dtn will be available on the window object. For every unique DTN widget that was loaded on the page, a function to create the widget will be available on this namespace. These functions are called “widget factory functions” or just “factory functions.” Since we have loaded the Interactive Map Widget for this guide, we can expect to find a function to create that widget called createInteractiveMapWidget.

console.log(typeof window.dtn.map.createInteractiveMapWidget); // "function"

All of DTN’s widgets will follow this pattern. If for example we also loaded the necessary script tag for the DTN Local Weather Widget, there would be an additional function available for creating that widget.

console.log(typeof window.dtn.localWeather.createLocalWeatherWidget); // "function"

Once you have the widget factory functions available, there is one additional step step required before you can start rendering widget’s on your page. That is to define an HTML element that will contain the widget. To do that put a div where you want to the widget to show up, and give it a unique id attribute.

<div id="my-widget-container"></div>

Now that there is a container for the widget, everything is ready to create one.

All DTN Widgets will be created the same way, by passing a configuration object to the create function. Every DTN Widget will require at least two configuration options in order to load properly. They are the a reference to the container we set up earlier, and your DTN access token.

let mapWidget = window.dtn.map.createInteractiveMapWidget({
  // DTN API key
  apiKey: "your-dtn-api-key-here",
  // The unique selector set up in the previous step
  container: "#my-widget-container",  // <-- The selector here matches the div previously defined
});

That’s it! You should see a DTN Interactive Map Widget rendered into the container specified. Keep reading to find out how to customize the widget.

Once you have the widget up and running, it’s time to configure it to fit your needs.

Each of DTN’s Widget will have a common set of configuration options, as well as some unique options. For this guide we will focus on the DTN Interactive Map Widget, using the widget reference page.

In this step you will use the configuration options available to set the default location of the map to your desired location, control the zoom level and set a default layer. By now this code should be familiar to you.

let mapWidget = window.dtn.map.createInteractiveMapWidget({
  apiKey: "your-dtn-api-key-here",
  container: "#my-widget-container",
});

Cross-referencing the configuration and API documentation again, you can read more about each configuratin option available. In our example, we want to change the initial view of the Map Widget. Based on the documentation you can see there is a defaultLocation option available which looks like it might fit our needs.

Now that that configuration option needed to modify has been identified, you need to figure out the coordinates of the location you want to set the DTN Map Widget to. Once you have that, you can set the defaultLocation configuration option just like the container and token options from before.

let mapWidget = window.dtn.map.createInteractiveMapWidget({
  apiKey: "your-dtn-api-key-here",
  container: "#my-widget-container",
  // This is the new configuration option
  defaultLocation: { latitude: 45, longitude: -93 },
});

If you have set the defaultLocation option correctly, you should observe that the DTN Interactive Map Widget is now centered on your desired location. If not you should encounter an error in your browser’s console describing what was invalid.

Now that the Map Widget is centered correctly, you notice the camera is zoomed way out. We can fix that by setting the defaultLocation‘s zoom configuration option.

let mapWidget = window.dtn.map.createInteractiveMapWidget({
  // ...
  // Add a zoom member to the defaultLocation object
  defaultLocation: { latitude: 45, longitude: -93, zoom: 3 },
});

Great, now that the map’s camera is set correctly, you can set what DTN weather information you want shown. For the purposes of this guide we will show the current radar data available in North America. Checking the configuration options available it looks like the defaultLayers configuration option fits your need.

let mapWidget = window.dtn.map.createInteractiveMapWidget({
  // ...
  defaultLocation: { latitude: 45, longitude: -93, zoom: 3 },
  defaultLayers: "RADAR",
});

Getting Started with your First Widget

Choosing a Widget

Integrating a Widget on Your Site

Customizing a Widget

Wrapping Up