Every widget has a single JavaScript file as it’s entry-point. It should be loaded using a <script> tag by setting the src attribute to the desired widget found here. To load multiple widgets on a page, use multiple <script> tags, one per widget.
<script src="https://cp-docs.dtn.com/content-packages/ui-widgets/local-weather-widget/local-weather-widget-1.0-latest.js"></script>
We recommend placing these <script> tags after all other HTML on the page, just before the closing </body> tag.
<body>
<script src="https://cp-docs.dtn.com/content-packages/ui-widgets/local-weather-widget/local-weather-widget-1.0-latest.js"></script>
<script src="https://cp-docs.dtn.com/content-packages/ui-widgets/futures-chart-widget/futures-chart-widget-1.0-latest.js"></script>
<script>
// Although this script is not loaded remotely,
// it's execution will be deferred until the
// previous scripts have been loaded.
</script>
</body>
After the script(s) has finished loading the widget(s) is available for use. They will all be available under the window.dtn namespace.
Self-Hosting Widgets
You may wish to host the widget’s JavaScript files yourself. That is perfectly acceptable, the widget’s make no assumption about where they are hosted. Keep in mind any patches or bug fixes shipped to the -latest release channel would not be pushed to any self-hosted files.
The window.dtn Namespace
Each widget <script> on a page will be available under the window.dtn namespace after it is loaded. Some widgets may share an additional namespace e.g. the Interactive Map Widget and the Weather Graphics Widget share the window.dtn.map namespace.
window.dtn.map.createInteractiveMapWidget;
window.dtn.map.createWeatherGraphicsWidget;
To find the namespace and functions to create each widget, see to it’s reference page indexed here. Alternatively, use the browser’s developer tool’s JavaScript console on any page with a widget loaded to see a table of available widgets.
console.table(window.dtn);
Rendering Widgets
Each widget will have a corresponding function, called a “factory function”, used to create instances of it. Each widget requires a containing element be defined on the page before you can create it. Any unique selector will work, but an ID is simplest. Along with a valid DTN API key, that is the minimum requirement to render most widgets.
<div id="widget-container"></div>
Every widget is created by calling it’s factory function with a valid configuration object. In it’s simplest form it looks like this.
let configuration = {
container: "#widget-container",
apiKey: "valid-dtn-api-key",
};
window.dtn.localWeather.createLocalWeatherWidget(configuration);
This will attach an instance of the Local Weather Widget to the supplied container. The configuration variable used when creating a widget is called the “widget configuration.” Each widget has it’s own set of configuration options in addition to some options that are shared across all widgets. To find the complete list of configuration options for each widget, see to it’s reference page indexed here.
Responsive Containers
In typical responsive websites the layouts may change when the browser’s viewport dimensions change. However, that comes with the limitation of not being able to render layouts for smaller containers at larger viewports. Because of that, widgets are responsive to their container, not the viewport. In other words the widgets will adjust their layout based on the size of the containing element rather than the browser’s viewport.