API Usage

You may need to request weather blox and insert them into your HTML before the page is rendered by the browser, or you may not want to rely on JavaScript for rendering large blox of content on your page for indexing, searching or SEO purposes. In these cases, you can use our server-side method where you request weather blox from our servers as HTML and then insert them into your pages before serving those pages to the browser in the response.

Requesting Weather Blox

There are two approaches to using the server-side method – using our PHP package for quicker integration, or directly requesting the weather blox from our server.

PHP Package

Using the Component class and associated scripts from our PHP package allows you to configure your components using the Config class instance. This means that global component options, such as how links within all weather blox are formatted, are automatically handled by your Component instance.

The use our PHP scripts for requesting weather blox:

  1. Include the library’s PHP scripts (Config.php, Component.php and Util.php) into your PHP script:

    require_once('./aeris-hosted-weather/scripts/Component.php');
  2. Include the WeatherBlox library assets into your HTML page where the weather blox will be rendered to:

    <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>
  3. Configure the library with your API access keys and custom options:

    Aeris\WxBlox\Config::getInstance()->setAccess(‘{{API_KEY}}’, '{{SECRET_KEY}}');
  4. Instantiate your weather blox component, passing any additional API request parameters to the component’s constructor:

    $opts = array('limit' => 5);
    $view = new Aeris\WxBlox\Component('forecasts/detailed', '98109', $opts);
  5. Call render() on your component to return the final HTML content for the component:

    $content = $view->html();
  6. Output the contents returned from render() wherever you want to the component to appear in your HTML page:

    <?php echo $content; ?>

The following public methods are available on a Component instance:

Method Description
config($key) [any] Returns the configuration value for the specified $key
html() [string] Returns the component’s HTML content
render() Renders the component but does not return the result. Use html() to render and return the component’s HTML content
find($selector,$context) Searches the component’s HTML for the element specified by the $selector string and within the optional $context selector string. If found, this method will return a DOMNode as it uses PHP’s DOMXPath internally for performing the queries and converts your selector strings to the proper XPath format.
prepend($selector,$html) Inserts the provided $html content as the first child within the DOM element specified by $selector if it exists within the component’s HTML
append($selector,$html) Inserts the provided $html content as the last child within the DOM element specified by $selector if it exists within the component’s HTML
insertBefore($selector,$html) Inserts the provided $html content before the DOM element specified by $selector if it exists within the component’s HTML
insertAfter($selector,$html) Inserts the provided $html content after the DOM element specified by $selector if it exists within the component’s HTML

Direct Request

An alternative to using our PHP scripts and the Component class to request weather blox is to request them by their URLs directly from our servers. While this reduces the dependency on our scripts and PHP for rendering, the downside is that component options and links will not be automatically formatted from the weather blox’s response. You will need to perform any links or other output customization on your own before outputting the weather content to your page.

The use the direct-request via URL method:

  1. Include the WeatherBlox library assets into your HTML page where the weather blox will be rendered to:

    <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>
  2. Determine the key/type for the weather blox view or layout you want to request.
  3. Setup the full URL for the desired component with your API access keys and additional API request parameters for the data. Note that the value for {{place}} may vary based on the component being requested:

    $url = ‘http://wxblox.aerisapi.com/{{API_KEY}}/{{SECRET_KEY}}/components/{{type}}/{{place}}';
  4. Make the HTTP request for the resulting URL using your method of choice and render the contents from the response to your HTML page:

    $content = file_get_contents($url);
  5. Output the contents returned by the request wherever you want the component to appear in your HTML page:

    <?php echo $content; ?>

Configuration

You may need to customize your weather blox beyond just the API requests when using the server-hosted method. You can provide an opts parameter with your weather blox request that must be a JSON-encoded string that corresponds to the supported configuration options for each weather blox component.

For example, to override the default layer controls on the LocalMap (maps/local) weather blox component, you would need to provide a custom value for the controls.layers configuration option:

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

If you’re using our Component.php class for rendering weather blox, just pass your configuration overrides as an array for the opts key when instantiating your component instance:

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

If you’re requesting weather blox from our servers directly, just pass your custom configuration object to the opts URL parameter as a serialized JSON string:

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

The above encoded URL will then be:

http://wxblox.aerisapi.com/{{API_KEY}}/{{SECRET_KEY}}/components/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

If you need to customize a weather blox component that’s part of a layout container, you would follow the same process as above but by assigning your custom options to the key of the component you want to customize.

For example, in the Local (layouts/local) layout, the same map component used in the examples above are stored by the layer using the maps key. Therefore, you’d just set your configuration options for this component on the layout’s maps key for the custom options instead:

$opts = array(
    'maps' => array(
        'controls' => array(
            'layers' => array(
                array('code' => 'radar', 'title' => 'Radar')
            )
        )
    )
);

Refer to the layout documentation for more information on accessing individual weather blox and their corresponding keys.

Injecting Custom Content

When using our PHP library for rendering weather blox components, our Component class offers methods that make it easy for you to insert your own custom content into the component’s HTML before you output it to your page. Use the methods prepend(), append(), insertBefore() and insertAfter() on your Component instance to insert your HTML into the desired location within the component’s HTML. Refer to the method documentation above for usage details about each of these methods.

For instance, if you want to insert a custom block of HTML content in a Local weather view after the observations block but before the short term phrasing:

$view = new Aeris\WxBlox\Component('view-local', 'seattle,wa');
$view->insertAfter('.awxb-view-obs', '<div>This is just an custom content block area.</div>');
$content = $view->html();
...
echo $content;

You can also insert custom HTML into an existing container using prepend() or append(). For example, you want to insert custom HTML into the Obs weather blox component before existing child nodes within the .obs .weather selector target:

$view = new Aeris\WxBlox\Component('obs', 'seattle,wa');
$view->prepend('.awxb-view-obs .obs .weather', '<div>This is just an custom content block area.</div>');
$content = $view->html();
...
echo $content;

Alternative Methods

If you’re not using PHP or require a different server-side integration method, you can use regular expressions or DOM helper library for your language of choice for manipulating a component’s HTML before rendering to the page.

Last modified: July 15, 2019