Configuration

You may need to customize the configuration of a WeatherBlox view beyond just the API data request parameters, such as overriding the default options that control the final output. Most WeatherBlox views have additional customization options that you can override via their constructor method when you create an instance of them. Refer to the documentation for each view or layout for additional information regarding the configuration options currently supported.

Global Configuration

The global configuration for your WeatherBlox setup manages things like link formatting, icon locations and mappings, and the units to display. The library provides all of the defaults necessary to get started without worrying about any of these settings, but you can override these defaults to provide additional customization.

Both JavaScript and API methods of using WeatherBlox support the ability to customize link formatting, which can appear throughout the rendered views and are used to link to different areas of your site. For example, the NearbyObservations view contains links for each location that, when clicked, will take the user to the weather page for that location. Or for the Maps layout, clicking a new map layer or region will take the user to the page for that content (if not using JavaScript event handlers for the links).

Below is the default configuration object, specifically related to the available link types taken from the full configuration object:

JavaScript
PHP
{
	links: {
		loc: '{{place.state}}/{{place.name}}',
		local: {
			main: '/local/{{loc}}.html',
			radar: '/local/{{loc}}/radar.html',
			history: {
				day: '/local/{{loc}}/history/{{year}}/{{month}}/{{date}}.html',
				month: '/local/{{loc}}/history/{{year}}/{{month}}.html',
				year: '/local/{{loc}}/history/{{year}}/{{month}}.html'
			},
			forecast: {
				day: '/local/{{loc}}/forecast/{{year}}/{{month}}/{{date}}.html'
			},
			normals: {
				month: '/local/{{loc}}/normals/{{month}}.html'
			},
			sunmoon: {
				month: '/local/{{loc}}/sunmoon/{{year}}/{{month}}.html',
				year: '/local/{{loc}}/sunmoon/{{year}}/{{month}}.html'
			},
			calendar: {
				day: '/local/{{loc}}/history/{{year}}/{{month}}/{{date}}.html',
				month: '/local/{{loc}}/calendar/{{year}}/{{month}}.html',
				year: '/local/{{loc}}/calendar/{{year}}/{{month}}.html'
			},
			advisory: '/local/{{loc}}/advisories.html',
			maps: '/local/{{loc}}/maps.html'
		},
		maps: {
			main: '/maps/{{regionSlug}}/{{layers}}.html',
			default: '/maps/us/radar.html'
		}
	},
	icons: {
		path: '//cdn.aerisapi.com/wxblox/icons/',
		ext: 'png',
		mapping: {}
	},
	unitsType: Units.Type.Imperial,
	units: {
		imperial: {
			temp: '°F',
			speed: ' mph',
			distance: ' mi',
			height: ' ft',
			pressure: ' in',
			percent: '%',
			precip: '"',
			rain: '"',
			snow: '"',
			text: ''
		},
		metric: {
			temp: '°C',
			speed: ' kmh',
			distance: ' km',
			height: ' m',
			pressure: ' mb',
			percent: '%',
			precip: ' mm',
			rain: ' mm',
			snow: ' cm',
			phrase: 'met'
		}
	}
}
array(
	'timeout' => 10,
	'links' => array(
		'loc' => '{{place.state}}/{{place.name}}',
		'local' => array(
			'main' => '/local/{{loc}}.html',
			'radar' => '/local/{{loc}}/radar.html',
			'history' => array(
				'day' => '/local/{{loc}}/history/{{year}}/{{month}}/{{date}}.html',
				'month' => '/local/{{loc}}/history/{{year}}/{{month}}.html',
				'year' => '/local/{{loc}}/history/{{year}}/{{month}}.html'
			),
			'forecast' => array(
				'day' => '/local/{{loc}}/forecast/{{year}}/{{month}}/{{date}}.html'
			),
			'normals' => array(
				'month' => '/local/{{loc}}/normals/{{month}}.html'
			),
			'sunmoon' => array(
				'month' => '/local/{{loc}}/sunmoon/{{year}}/{{month}}.html',
				'year' => '/local/{{loc}}/sunmoon/{{year}}/{{month}}.html'  
			),
			'calendar' => array(
				'day' => '/local/{{loc}}/history/{{year}}/{{month}}/{{date}}.html',
				'month' => '/local/{{loc}}/calendar/{{year}}/{{month}}.html',
				'year' => '/local/{{loc}}/calendar/{{year}}/{{month}}.html'
			),
			'advisory' => '/local/{{loc}}/advisories.html',
			'maps' => '/local/{{loc}}/maps.html'
		),
		'maps' => array(
			'main' => '/maps/{{region}}/{{type}}.html',
			'default' => '/maps/us/radar.html'
		)
	)
);

To override these default configuration values using WeatherBlox, you just need to use the Aeris.wxblox.config.set() JavaScript method (or Aeris\WxBlox\Config::getInstance()->set() PHP method) to set your desired value for the configuration's key path.

For example, the following would change the icon path to a custom icon set used across various WeatherBlox views:

Aeris.wxblox.config.set('icons.path', 'https://www.mydomain.com/images/wxicons/');

Heads Up! Some configuration options aren't available when using the WeatherBlox API method since the views are rendered on our servers before being available to your application. However, you can modify the returned HTML content as needed before rendering the output.

Handling Links

Some WeatherBlox views and layouts contain links that can be used to direct a user to a different weather-related page, such as viewing full weather advisory information or viewing a different day for an hourly forecast. Review our documentation on handling links for more information on customizing links within your WeatherBlox implementation.

Configuring Views - JavaScript

To customize view options using the JavaScript (client-side) method, pass an optional object as the second parameter to a view's constructor method after the DOM target, which should contain the options you wish to override for the view.

For example, to override the default layout controls on a MapViewer instance, you would need to provide a custom value for the controls.layers configuration option:

var view = new Aeris.wxblox.views.MapViewer('#map', { 
	controls: { 
		layers: [{
			code: "radar", 
			title: "Radar"
		}] 
	}
});

Configuring Layouts

Configuring a WeatherBlox view that's part of a layout container follows a similar approach as explained above except that you would need to assign your options to the key associated with the view you're targeting within the layout.

For example, in the local.Main layout, an instance of the same MapViewer view used in the examples above is displayed along with local weather information. This view is associated with the maps key within the layout. Therefore, you would just set your configuration options for this view on the layout's maps key instead:

var view = new Aeris.wxblox.layouts.local.Main('#local-view', { 
	maps: {
		controls: { 
			layers: [{
				code: "radar", 
				title: "Radar"
			}] 
		}
	}
});

Refer to each layout's specific documentation for more information on accessing and targeting individual views contained within them.

Configuring Views - API

To customize view options using the API (server-side) method, provide an opts parameter with your request, which must be a JSON-encoded string that corresponds to the supported configuration options for the requested view.

For example, to override the default layout controls on the MapViewer view (maps/viewer), you would need to provide a custom value for the controls.layers configuration option. The resulting JSON object for this option would look similar to:

{ controls: { layers: [ {code: "radar", title: "Radar"} ] } }

If you're using our PHP package and associated View class, just pass your configuration overrides as an array to an opts key when instantiating your instance:

$opts = array(
    'controls' => array(
        'layers' => 
            array('code' => 'radar', 'title' => 'Radar')
        )
    );
$view = new Aeris\WxBlox\View('maps/viewer', '98109', $opts);

When requesting WeatherBlox views directly from our servers, you must pass your JSON-encoded string to the opts URL parameter:

$opts = array(
    'controls' => array(
        'layers' => 
            array('code' => 'radar', 'title' => 'Radar')
        )
    );
$optsStr = json_encode($opts);
$url = ‘http://wxblox.aerisapi.com/{{API_KEY}}/{{SECRET_KEY}}/views/maps/viewer/98109?opts=$optsStr;

The above encoded URL that is requested would then be:

http://wxblox.aerisapi.com/{{API_KEY}}/{{SECRET_KEY}}/views/maps/viewer/98109?opts=%7B%22maps%22%3A%7B%22controls%22%3A%7B%22layers%22%3A%5B%7B%22code%22%3A%22radar%22%2C%22title%22%3A%22Radar%22%7D%5D%7D%7D%7D

Configuring Layouts

Configuring a WeatherBlox view that's part of a layout container follows a similar approach as explained above except that you would need to assign your options to the key associated with the view you're targeting within the layout.

For example, in the local.Main (layouts/local) layout, an instance of the same MapViewer view used in the examples above is displayed along with local weather information. This view is associated with the maps key within the layout. Therefore, you would just set your configuration options for this view on the layout's maps key instead:

$opts = array(
    'maps' => array(
        'controls' => array(
            'layers' => 
                array('code' => 'radar', 'title' => 'Radar')
            )
        )
    );
$view = new Aeris\WxBlox\View('layouts/local', '98109', $opts);

Refer to each layout's specific documentation for more information on accessing and targeting individual views contained within them.