Script Usage

When using the JavaScript method for including weather blox into your page, the blox are rendered after your main page has loaded and all requests are performed asynchronously. This method is the easiest to get started with as it doesn’t require any server-side development in order to output the weather blox content into your HTML page.

Follow these steps to get started using the JavaScript method:

<!-- Step 1: Include the WeatherBlox stylesheet and script assets -->
<link href="https://cdn.aerisapi.com/wxblox/latest/aeris-wxblox.css" rel="stylesheet"/>
<script src="https://cdn.aerisapi.com/wxblox/latest/aeris-wxblox.js"></script>

<!-- Step 2: Create a DOM target where the WeatherBlox view will be rendered -->
<div id="wxblox"></div>

<script>

// Step 3: Within a <script> tag block, configure the core Aeris client with your API access keys and custom options
const aeris = new AerisWeather('CLIENT_ID', 'CLIENT_SECRET');

// Step 4: Set up an event handler to be notified when the WeatherBlox library has fully loaded and initialized:
aeris.on('ready', () => {

    // Step 5: Within your "ready" event handler, setup your desired components:
    const widget = new aeris.wxblox.views.Forecast('#widget');

    // Step 6: Add any desired event listeners/handlers for your view instance:
    widget.on('load:start', function(e) {
        console.log('load started');
    });
    widget.on('load:done', function(e) {
        console.log('load done');
    });
    widget.on('render:before', function(e) {
        console.log('before render');
    });
    widget.on('render:after', function(e) {
        console.log('after render');
    });

    // Step 7: Call `load()` on your widget, passing any additional API request parameters:
    widget.load({
        p: '98109'
    });

});

</script>

Configuration

Each component provides the following core configuration options:

Option Default Description
enabled true [boolean] Whether or not this component is enabled. If false then the component will not be rendered and it’s required data will not be requested
metric false [boolean] Whether or not to display units in metric. The method setUnits() can be used at runtime once a component has rendered to change the units currently displayed
renderNoData true [boolean] Whether or not the component should be rendered if data was not returned or not available
request undefined [object] An object containing the default API request options to use for the component’s data request where applicable

The following is the default configuration object:

{
    enabled: true,
    metric: false,
    renderNoData: true,
    request: undefined
}

Events

The JavaScript weather blox trigger events that you can observe and handle accordingly. By default, all components trigger the following events:

Event Description
load:start Triggered immediately before the component’s data request begins loading
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
render:before Triggered immediately before the component is rendered, allowing you to access and modify the data used in the template before getting rendered
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 Alias for render:after
change:units Triggered when the component’s unit type has changed (e.g. metric or imperial)

Layout/view components, which are a combination of individual weather blox to output a larger blox of content, also trigger their own events related to the rendering of the layout’s components. All layouts trigger the following events:

Event Description
components:render Triggered after all components required by the layout have completed their data requests and have been rendered to the DOM

Public Methods

The following public methods are available on all JavaScript components. Each component may support additional public methods which will be detailed in each component’s documentation.

Method Description
params() [object] Returns the latest request parameters used when loading data
show() Shows the component’s DOM element
hide() Hides the component’s DOM element
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
rendered() [boolean] Whether or not the component has rendered
units() [number] The current unit type being displayed, where 0 is Imperial and 1 is Metric
setUnits(:number) Updates the unit type being displayed by the component, where 0 is Imperial and 1 is Metric
setMetric(:boolean) Convenience method for setUnits() to toggle Metric units, where true sets the component’s units to Metric and false uses Imperial
isMetric() [boolean] Whether or not the component is currently displaying Metric units
refresh() Re-renders the component using the cached data that was previously loaded
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.

Last modified: July 15, 2019