1. Help Center
  2. Docs
  3. Aeris Toolkits
  4. Aeris WeatherBlox
  5. Reference
  6. Views
  7. MapViewer

Aeris WeatherBlox

View: MapViewer

A MapViewer view is responsible for displaying and managing a weather map consisting of one or more data layers. This view also handles animating weather data across a specific time range.

JavaScript: Aeris.wxblox.views.MapViewer

Server Path: /views/maps/viewer

Data API/AMP Usage: AMP usage based on size of map and total layers. Refer to the Map Units documentation for details.

Supported Plans AMP Developer,  AMP Basic,  AMP Premium

Configuration

The following configuration options are supported by this view:

Option Default Description
map (object) Default map configuration
map.layers (object) The layer configuration for the map
map.layers.base ['flat'] (array) [array] An array of base map layer codes to render below all weather and overlay layers
map.layers.overlays ['admin'] (array) [array] An array of overlay layer codes to render above all weather and base layers
map.layers.data undefined (array) [array] An array of supported weather layer codes
map.loc null (string) The location to center the map on
map.zoom 3 (number) Map zoom level
map.bounds undefined (string) [string] or [object] The bounds to use for the map as northwest and southeast coordinates either as a string, 56.26,-131.39,15.45,-61.17, or object, { north: 56.26, west: -131.39, south: 15.45, east: -61.17 }
map.region undefined (string) The key of a supported region to display for the map. See the regions documentation for the regions currently supported and their usage.
map.size.width auto (number) [integer/auto] Map width in pixels (limited by your Aeris Maps level), or auto to have the width automatically set to fill the map container's width.
map.size.height auto (number) [integer/auto] Map height in pixels (limited by your Aeris Maps level), or auto to have the height automatically calculated based on the map container's width and the specified map.size.factor ratio
map.size.factor 0.75 (number) The scale factor to use when height is set to auto. The map height will be calculated by multiplying either the specified width value or DOM container's width by the factor value.
map.offset undefined (string) The time offset to display for single-interval maps. This does not affect animations
map.autoFuture true (boolean) Whether or not future layers corresponding to active layers defined in map.layers.data should automatically be included when the map's timeline includes future periods (e.g. fradar would be included if radar is active)
map.combine false (boolean) Whether or not all specified layers specified by map.layers.data should be combined into a single image for each request. When false, the base overlay layers will be rendered into their own separate DOM containers below and above the map content respectively and will not be animated, which reduces the total map units used for a single animation. Set to true if you need your layers rendered in a unique order around the animated map layers.
animation (object) Configuration for the map animation
animation.enabled true (boolean) Whether or not to enabled animation. If false, then the viewer will only display data for the current time
animation.from -2 * 3600 (number) [number] or [date] Start time offset relative to now for the animation in seconds, or a valid Date instance; negative values are in the past
animation.to 0 (number) End time offset relative to now for the animation in seconds, or a valid Date instance; negative values are in the past
animation.duration 2 (number) Total duration of the animation in seconds; duration and intervals are both used to control the overall speed of the animation
animation.endDelay 1 (number) Delay to hold the end of the animation before replaying from the beginning, in seconds
animation.intervals 10 (number) Total number of frames to use for the animation; duration and intervals are both used to control the overall speed of the animation such that a higher number of intervals will animate faster than a lower number of intervals for the same duration value
animation.autoplay false (boolean) Whether or not the animation should automatically start playing initially
animation.refresh 300 (number) How often the animation re-fetches data.
overlays (object) Configuration for custom overlays rendered above the map
overlays.title undefined (string) he title to display over the map. Use CSS to style the title's DOM elements as needed
overlays.timestamp MM/DD/YYYY hh:mm A (string) [string] or [object] A string value indicates the time and date format for the map's timeline during playback. Provide an object to include additional options.
overlays.timestamp.format undefined (string) Time and date format for the map timeline during playback using moment.js formatting options
overlays.timestamp.continuous true (boolean) Whether or not the timestamp should update continuously during playback regardless of frame intervals. If false, then the timestamp will only update when the animation's frame changes
overlays.branding (object) Map branding options
overlays.branding.img undefined (string) A URL to an image to display on the map, such as a company logo.
overlays.branding.html undefined (string) An HTML string to display for the map branding, such as a company logo or name. Offers more flexible customization options than overlays.branding.img.
selectors (object) Selectors for DOM render targets
controls (object) Options for layers and regions navigation elements displayed within the viewer
controls.layers null (array) [array] An array of layer config objects to display in the layer selection navigation
controls.layers[#].code (string) The AerisMaps layer code
controls.layers[#].title (string) The title to display for the layer
controls.regions null (array) [array] An array of region config objects to display in the region selection navigation
controls.regions[#].zoom (number) The map zoom level to use for the region
controls.regions[#].loc (string) An optional location to center the map on for the region. If this value is not defined or null, then the value of map.loc will be used for this region's center location.
controls.regions[#].title (string) The title to display for the region
enabled true (boolean) Whether or not this view is enabled. If false then the view will not be rendered and it's required data will not be requested. This option is typically only applicable for views contained within a parent layout.
metric false (boolean) Whether or not to display units in metric. The method setUnits() can be used at runtime once a view has rendered to change the units currently displayed.
renderNoData true (boolean) Whether or not the view should be rendered if data was not returned or not available
request undefined (object) An object containing the default Aeris Weather API request options to use for the views's data request where applicable. These parameters can also be overriden in the load(:params) method when rendering the view using the JavaScript method.

Methods

The following methods are supported by instances of this view (JavaScript method only):

viewer()

The interval viewer object that manages the map.
enabled() [boolean] Whether or not the component is currently enabled. When false, the component will not be rendered and data required for the component will not be requested.
hide() Hides the component's DOM element.
isMetric() [boolean] Whether or not the component is currently displaying Metric units.
load(:object) Requests data required by the component and renders the result. For components that don't require remote data requests, this method will call render() immediately. An optional object of request parameters can be provided to use for the request.
params() [object] Returns the latest request parameters used when loading data.
refresh() Re-renders the component using the cached data that was previously loaded.
rendered() [boolean] Whether or not the component has rendered.
setMetric(:boolean) Convenience method for setUnits() to toggle Metric units, where true sets the component's units to Metric and false uses Imperial.
setUnits(:number) Updates the unit type being displayed by the component, where 0 is Imperial and 1 is Metric.
show() Shows the component's DOM element.
units() [number] The current unit type being displayed, where 0 is Imperial and 1 is Metric.

Events

The following events are triggered by instances of this view (JavaScript method only):

change:units Triggered when the component's unit type has changed (e.g. metric or imperial).
load:done Triggered after the component's data has loaded but before rendering the component.
load:error Triggered when an error occurs while requesting the component's data.
load:start Triggered immediately before the component's data request begins loading.
render Alias for render:after.
render:after Triggered after the component has rendered and any additional DOM elements and/or events have been setup as needed for the component.
render:before Triggered immediately before the component is rendered, allowing you to access and modify the data used in the template before getting rendered.

Examples

Use the following examples to assist with getting started using this view. Select your WeatherBlox integration method for example code specific to that usage.

JavaScript
API via Package
API via URL

The first example below can be pasted into the body of your HTML document. For each additional snippet, you can replace the snippet within the first example which is located between the JavaScript comments.

Display a MapViewer component with navigation options to change the zoom level and layer data types centered on Austin, TX:

<link href="https://cdn.aerisapi.com/wxblox/aeris-wxblox.css" rel="stylesheet"/>
<script src="https://cdn.aerisapi.com/wxblox/aeris-wxblox.min.js"></script>

<!-- DOM target where the WeatherBlox view will be rendered -->
<div id="wxblox"></div>

<script>
Aeris.wxblox.setAccess('CLIENT_KEY', 'CLIENT_SECRET');

// Insert view / layout code below

var view = new Aeris.wxblox.views.MapViewer('#wxblox', {

    map: {

	loc: 'austin,tx',

        data: ['radar']

    },

	controls: {

		layers: [{

			code: 'radar',

			title: 'Radar'

		},{

			code: 'satellite',

			title: 'Satellite'

		},{

			code: 'alerts',

			title: 'Advisories'

		},{

			code: 'temperatures,clip-us-flat',

			title: 'Temps'

		}],

		regions: [{

			zoom: 7,

			title: 'Local'

		},{

			zoom: 5,

			title: 'Regional'

		},{

			region: 'us',

			title: 'National'

		}]

	}

});

view.load();

// End view / layout code

</script>

Display a MapViewer component with navigation options to change the zoom level and layer data types centered on Austin, TX:

$view = new Aeris\WxBlox\View(’/layouts/maps/viewer’, ‘austin,tx’, array(

	‘map’ => array(

		‘data’ => array(‘radar’)

	),

	‘controls’ => array(

		‘layers’ => array(

			array(‘code’ => ‘radar’, ‘title’ => ‘Radar’),

			array(‘code’ => ‘satellite’, ‘title’ => ‘Satellite’),

			array(‘code’ => ‘alerts’, ‘title’ => ‘Advisories’),

			array(‘code’ => ‘temperatures,clip-us-flat’, ‘title’ => ‘Temps’)

		),

		‘regions’ => array(

			array(‘zoom’ => 7, ‘title’ => ‘Local’),

			array(‘zoom’ => 5, ‘title’ => ‘Regional’),

			array(‘region’ => ‘us’, ‘title’ => ‘National’)

		)

	)

));

$content = $view->html();

echo $content;

Display a MapViewer component with navigation options to change the zoom level and layer data types centered on Austin, TX:
https://wxblox.aerisapi.com/[api_key]/[secret_key]/views/maps/austin,tx?opts=%7B%22map%22%3A%7B%22loc%22%3A%22austin%2Ctx%22%2C%22data%22%3A%5B%22radar%22%5D%7D%2C%22controls%22%3A%7B%22layers%22%3A%5B%7B%22code%22%3A%22radar%22%2C%22title%22%3A%22Radar%22%7D%2C%7B%22code%22%3A%22satellite%22%2C%22title%22%3A%22Satellite%22%7D%2C%7B%22code%22%3A%22alerts%22%2C%22title%22%3A%22Advisories%22%7D%2C%7B%22code%22%3A%22temperatures%2Cclip-us-flat%22%2C%22title%22%3A%22Temps%22%7D%5D%2C%22regions%22%3A%5B%7B%22zoom%22%3A7%2C%22title%22%3A%22Local%22%7D%2C%7B%22zoom%22%3A5%2C%22title%22%3A%22Regional%22%7D%2C%7B%22region%22%3A%22us%22%2C%22title%22%3A%22National%22%7D%5D%7D%7D