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;. This means anytime in a widget’s documentation allows for a StationId (notice the capital S), a string is expected. You can read more here on the official TypeScript docs.
  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. The widget’s make heavy use of these to describe configuration options that take string literals e.g. type WeatherFields = | "TEMPERATURE" | "FEELS_LIKE" | "HUMIDITY"; or configuration options that can take multiple values. You can read more here on the official TypeScript docs.
  3. Intersection Types – Intersection Types describe a type produced by combining multiple types. Intersection types are denoted by the existence of the & sigil. The widget’s make use of this to describe a configuration option that requires members from multiple different object types e.g. type Location = Coordinates & { zoom?: number; }; requires all the members of the Coordinates type in addition to an optional zoom member. You can read more here on the official TypeScript docs.
  4. Optional Types & Default Values – Optional types describe a configuration option that can accept an undefined value. They will often implement a default value of undefined(or nothing at all) is passed e.g. show3YearAverageBasis?: boolean = true; can be either undefined, true, or false and if undefined (or nothing) is passed the default will be true. Any configuration object with a ? sigil after its name is considered optional. You can read more here on the official TypeScript docs.

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. Some widgets such as the Premium widgets, may have additional configuration options that are 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" };