Configuring and Customizing Widgets

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.

Understanding Widget's Reference Doc

The widget's configuration objects are described using TypeScript's syntax. While it is by no means required to use TypeScript, understanding the syntax will be helpful to understand the widget reference pages. See the official TypeScript documentation for more information.

Types describe the custom parameters the widget's understand. There are several different forms of custom types to be aware of.

  1. Type Aliases – This simply assigns a memorable name to a TypeScript primitive type e.g. type StationId = string;.
  2. Union Types – Union types describe a type who's value can be any of several types. Union types are denoted by the existence of the | sigil.
  3. Intersection Types – Intersection Types describe a type produced by combining multiple types. Intersection types are denoted by the existence of the & sigil.
  4. Optional Types & Default Values – Optional types describe a configuration option that can accept an undefined value. Any configuration object with a ? sigil after its name is considered optional.

Configuration Usage

Configuration objects are plain JavaScript objects. In order to configure a widget, create an object with the appropriate key/value pairs and pass it as the one and only argument to the widget's factory function.

let configuration = {
  container: "#widget-container",
  apiKey: "valid-dtn-api-key",
  // Enumerate additional configuration options here
};
window.dtn.localWeather.createLocalWeatherWidget(configuration);

Required vs. Optional Configuration

container and apiKey are always required. Always refer to the respective widget reference for a complete list of required configuration options. Remember anything without a ? in it's name is considered required.

Read-Only Configuration

The configuration object is read-only. Once a widget is created with a configuration object, modifying it's members afterward will have no effect. Configuration is considered frozen.

let configuration = {
  defaultLocation: { postalCode: "33101" },
};
window.dtn.localWeather.createLocalWeatherWidget(configuration);
// This will have no observable effect on the widget
configuration.defaultLocation = { postalCode: "50309" };