API Usage

You may need to request WeatherBlox views 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 WeatherBlox elements on your page for indexing, searching or SEO purposes. In these cases, you can use our server-side method where you request WeatherBlox content from our servers as HTML and then insert them into your pages before serving those pages to the browser in the response.

Requesting WeatherBlox

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

PHP Package

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

The use our PHP scripts for requesting WeatherBlox content:

1. Download the WeatherBlox PHP package from our Github repository.

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

   require_once('./aeris-hosted-weather/scripts/View.php');

3. Include the WeatherBlox library assets into your HTML page where the WeatherBlox views 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>

4. Configure the library with your API access keys and custom options:

   Aeris\WxBlox\Config::getInstance()->setAccess(‘{{API_KEY}}’, '{{SECRET_KEY}}');

5. Instantiate your WeatherBlox view, passing any additional API request parameters to the view’s constructor:

   $opts = array('limit' => 5);
   $view = new Aeris\WxBlox\ View('forecasts/detailed', '98109', $opts);

6. Call render() on your view to return the final HTML content for the view:

   $content = $view->html();

7. Output the contents returned from render() wherever you want to the view to appear in your HTML page:

   <?php echo $content; ?>

The following public methods are available on a View instance:

Direct Request

An alternative to using our PHP scripts and the View class to request WeatherBlox content 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 view options and links will not be automatically formatted from the WeatherBlox’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 WeatherBlox views 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 WeatherBlox view or layout you want to request.

3. Setup the full URL for the desired view with your API access keys and additional API request parameters for the data. Note that the value for {{place}} may vary based on the view being requested:

   $url = ‘http://wxblox.aerisapi.com/{{API_KEY}}/{{SECRET_KEY}}/views/{{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 view to appear in your HTML page:

   <?php echo $content; ?>

Configuration

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

For example, to override the default layer controls on the LocalMap (maps/local) view, 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 View.php class for rendering WeatherBlox views, just pass your configuration overrides as an array for the opts key when instantiating your view instance:

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

If you’re requesting WeatherBlox views 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}}/views/maps/viewer/98109?opts=$optsStr;

The above encoded URL will 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

If you need to customize a WeatherBlox view 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 view you want to customize.

For example, in the Local (layouts/local) layout, the same map view used in the examples above are stored by the layer using the maps key. Therefore, you’d just set your configuration options for this view 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 WeatherBlox views and their corresponding keys.

Injecting Custom Content

When using our PHP library for rendering WeatherBlox views, our View class offers methods that make it easy for you to insert your own custom content into the view’s HTML before you output it to your page. Use the methods prepend(), append(), insertBefore() and insertAfter() on your View instance to insert your HTML into the desired location within the view’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\View('layouts/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 view before existing child nodes within the .obs .weather selector target:

$view = new Aeris\WxBlox\View('views/observations', '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 view’s HTML before rendering to the page.

Last modified: July 13, 2020