Skip to content

Latest commit

 

History

History
254 lines (174 loc) · 9.33 KB

install.md

File metadata and controls

254 lines (174 loc) · 9.33 KB
Raw

Installing Aeris.js

From a CDN

For basic usage, Aeris.js can be used from a CDN:

<script type="text/javascript" src="//cdn.aerisjs.com/aeris.min.js"></script>

Available Packages

There are several hosted versions of the Aeris.js library, each with a varying set of features.

  • Aeris.js

    The default library includes all of the Aeris.js features. Leaflet is used as the default mapping library.

    //cdn.aerisjs.com/aeris.min.js

    For this package, you will also need to include the Leaflet library and stylesheet:

    

    • 



<script type="text/javascript" src="http://cdnjs.cloudflare.com/ajax/libs/leaflet/0.7.2/leaflet.js"></script>
    ```


Setting API Keys


In order to use weather data from the Aeris API, you must provide an Aeris API client id and secret (visit hamweather.com to sign up for a free devleoper account). API keys may be set globally using the aeris.config object:


aeris.config.setApiId('abcd1234');
aeris.config.setApiSecret('wxyz6789');


RequireJS / AMD


Aeris.js uses RequireJS to load modules and components. Using RequireJS (or a compatible AMD loader), you can pick and choose which Aeris.js components you would like to use.


require(['aeris/maps/map', 'aeris/maps/layers/radar'], function(AerisMap, Radar) {
    var map = new AerisMap('map-canvas');
    var radar = new Radar();

    radar.setMap(map);
});


You can then use the RequireJS Optimizer to package your application. Only the Aeris.js components which you used will be bundled into your application. This will likely result in a smaller footprint than when using a one-size-fits-all CDN package.


Dependencies


For the core maps and API libraries, Aeris.js relies heavily on Underscore and Backbone. Note that if you use Aeris.js from a CDN, these dependencies are bundled into the build.


In order to use Aeris.js AMD modules, you must tell the library where to find its dependencies:


require.config({
    paths: {
        // Specify base path of aeris-js library 
        aeris: 'myApp/vendor/aerisjs/src',

        // Core dependencies.
        // Required for all Aeris.js components
        underscore: 'myApp/vendor/underscore',
        backbone: 'myApp/vendor/backbone',

        // Google Maps AMD module loader plugin
        // See https://github.com/hamweather/googlemaps-amd
        // Only required if using Google Maps
        googlemaps: 'myApp/vendor/googlemaps',
        
        // The async AMD loader plugin is used by googlemaps.
        // See https://github.com/millermedeiros/requirejs-plugins
        async: 'myApp/vendor/async'

        // Only required for marker collections rendered with Google Maps.
        // Must use exact version 2.1.1
        // (v2.1.2 includes a breaking change. Go figure.)
        // http://google-maps-utility-library-v3.googlecode.com/svn/trunk/markerclustererplus/docs/reference.html
        'gmaps-markerclusterer-plus': 'mapApp/lib/vendor/gmaps-markerclusterer-plus'

        // Only required for marker collections rendered with Leaflet
        // See https://github.com/Leaflet/Leaflet.markercluster
        'leaflet-markercluster': 'mapApp/lib/vendor/leaflet.markercluster'
    },

    // A Shim configuration is required for libraries which
    // do not support AMD out of the box.
    // See http://requirejs.org/docs/api.html#config-shim
    shim: {
        // Only required when using google maps
        'gmaps-markerclusterer-plus': {
          exports: 'MarkerClusterer'
        },

        // Only required when using Leaflet
        'leaflet-markercluster': {
          deps: ['leaflet'],
          exports: 'L.MarkerClusterGroup'
        }
    }
});


See the AMD/Bower.js example app for a full working RequireJS configuration.


Specifying a Map Library


By default, The Aeris.js library uses Leaflet as it core mapping library. You can change which mapping library is used by overriding the aeris/maps/strategy AMD path.


require.config({
    paths: {
        // Use Leaflet (default)
        'aeris/maps/strategy': 'myApp/vendor/aerisjs/src/maps/leaflet'

        // Use Google Maps
        'aeris/maps/strategy': 'myApp/vendor/aerisjs/src/maps/gmaps'

        // Use OpenLayers
        'aeris/maps/strategy': 'myApp/vendor/aerisjs/src/maps/openlayers'
    }
});


The map libraries will be loaded for you as AMD modules -- there is no need to include them separately. See Setting API Keys for instructions of map library configuration.


Not all functionalities are currently implemented for all map rendering strategies. See Supported Mapping Libraries for a breakdown of supported features.


Setting API Keys


Depending on which Aeris.js components you choose to use, you may be required to supply API keys. This can be accomplished via RequireJS Configuration, and should be set before loading any Aeris.js modules.


require.config({
    config: {
        // Required for using weather data or tiles from the
        // Aeris API.
        // See http://www.hamweather.com/products/aeris-api/
        'aeris/config': {
            apiId: '[YOUR AERIS API CLIENT ID]',
            apiSecret: '[YOUR AERIS API CLIENT SECRET]'
        },

        // Required only when using the MapQuest geocoding service
        'aeris/geocode/config':  {
            apiId: '[YOUR MAPQUEST API KEY]'
        }
    },

    // If using google maps,
    // it is recommended to specify an API key
    // See https://github.com/hamweather/googlemaps-amd
    // for full documentation
    googlemaps: {
        params: {
            // Geometry library is required for a number of Aeris components
            // (only when using the Google Maps strategy)
            libraries: 'geometry',
            key: '[YOUR GOOGLE API KEY]'
        }
    }
});


Using Bower


Bower is a package manager for javascript libraries. Aeris.js can be installed as a Bower package:


bower install aerisjs



The Bower package includes all components of the Aeris.js library. Aeris.js dependencies will all be installed for you by Bower.


The only difference from your RequireJS configuration will be the location of your vendor libraries:


require.config({
    paths: {
        aeris: 'bower_components/aerisjs/src',

        underscore: 'bower_components/underscore/underscore'
        // etc...
    }
});


Download the repo


Of course, you can always just go ahead and download the whole repo and stick it in your application directory. This means you'll have to download and manage all your dependencies yourself, but hey, to each their own.