The application model will reflect the application state. In our application, the selected country defines the state of the application; we will use three-letter country codes as the only attribute of the application model:

// Application Model
app.ApplicationModel = Backbone.Model.extend({
    // Code of the Selected Country
    defaults: {
        code: ''
    }
});

We will have two additional models: the CountryInformation model will represent information about the current HDI value and its main components, and the CountryTrend model will contain information about the country and time series of HDI measurements.

The data source for these models will be an endpoint of the Human Development Data API. The API allows us to retrieve data about poverty, education, health, social integration, and migrations, among many others. A complete list of the API endpoints and some examples of queries are available at the Human Development Data API website (http://hdr.undp.org/en/data/api). The API exposes the data in several formats and receives parameters to filter the data.

The CountryInformation model will retrieve information about the Human Development Index and its Components endpoint. For instance, we can access this endpoint by passing name=Germany as the parameter of the request. The request to http://data.undp.org/resource/wxub-qc5k.json?name=Germany will return a JSON file with the main components of the HDI:

[ 
  {
    "_2011_expected_years_of_schooling_note" :"e",
    "_2012_life_expectancy_at_birth" :"80.6",
    "_2012_gni_per_capita_rank_minus_hdi_rank" :"10",
    "_2012_hdi_value" :"0.920",
    "type" : "Ranked Country",
    "abbreviation" : "DEU",
    "_2010_mean_years_of_schooling" :"12.2",
    "_2011_expected_years_of_schooling" :"16.4",
    "name" : "Germany",
    "_2012_hdi_rank" :"5",
    "_2012_gross_national_income_gni_per_capita" :"35431",
    "_2012_nonincome_hdi_value" :"0.948"
  }
]

We will define the model such that it has the name and code attributes and some of the information provided by the JSON file. We will add the url, baseurl, and urltpl attributes to construct the URL for each country, as follows:

// Country Information Model
app.CountryInformation = Backbone.Model.extend({

    // Default attributes, the name and code of the country
    defaults: {
        code: '', 
        name: ''
    },

    // URL to fetch the model data
    url: '',

    // Base URL
    baseurl: 'http://data.undp.org/resource/wxub-qc5k.json',

    // URL Template
    urltpl: _.template('<%= baseurl %>?Abbreviation=<%= code %>')
});

Each country has the abbreviation field; this field contains the code for the country. We will use this code as the ID of the country. The names of the attributes of the JSON object contain data; for instance, the _2012_life_expectancy_at_birth attribute contains the year of the measurement. If we create an instance of the model and invoke its fetch method, it will retrieve the data from the JSON endpoint and add attributes to each attribute of the retrieved object. This will be a problem because the endpoint returns an array and not all the countries have up-to-date measurements. In the case of Germany, the only object in the array has the _2012_life_expectancy_at_birth attribute, but in the case of other countries, the most recent measurements could be from 2010.

To have a uniform representation of the data, we can strip the year out of the attribute names before we set the attributes for the model. We can do this by setting the parse method, which is invoked when the data is fetched from the server. In this method, we will get the first element of the retrieved array and strip the first part of the attributes beginning with _ to only have attributes of the form life_expectancy_at_birth:

    // Parse the response and set the model contents
    parse: function(response) {

        // Get the first item of the response
        var item = response.pop(),
            data = {
                code: item.abbreviation, 
                name: item.name
            };

        // Parse each attribute
        for (var attr in item) {
            if (attr[0] === '_') {
                // Extract the attribute name after the year
                data[attr.slice(6)] = item[attr];
            }
        }

        // Return the parsed data
        return data;
    }

We will also add a method to update the model with the selected country in the application. The setState method will receive the application model and use its code attribute to construct the URL for the selected country and to fetch the new information, as follows:

setState: function(state) {
    // Construct the URL and fetch the data
    this.url = this.urltpl({
        baseurl: this.baseurl, 
        code: state.get('code')
    });
    this.fetch({reset: true});
}

We will create the CountryTrend model to store the trends of the HDI for each country, and the Countries collection to store the CountryTrend instances. The CountryTrend model will hold the country code and name, a flag to indicate whether the country has been selected or not, and a series of HDI measurements for different years. We will use the code of the country as an ID attribute:

// Country Trend Model
app.CountryTrend = Backbone.Model.extend({

    // Default values for the Country Trend Model
    defaults: {
        name: '',
        code: '',
        selected: false,
        hdiSeries: []
    },

    // The country code identifies uniquely the model
    idAttribute: 'code'
});

The Countries collection will contain a set of the CountryTrend instances. The collection will have an endpoint to retrieve the information for the model instances. We will need to define the parse method in the CountryTrend model, which will be invoked automatically before new CountryTrend instances are generated. In the parse method, we construct an object with the attributes of the new model instance. The data retrieved for the collection will have the following structure:

{
  _1990_hdi: "0.852"
  _1980_hdi: "0.804"
  _2000_hdi: "0.922"
  // ...
  _2012_hdi: "0.955"
}

Here, the year of the HDI measurement is contained in the key of the object. There are other attributes also, which we will ignore. We will split the attribute name using the _ character to extract the year:

    // Parse the country fields before instantiating the model
    parse: function(response) {

        var data = {
            code: response.country_code,
            name: response.country_name,
            selected: false,
            hdiSeries: []
        };

        // Compute the HDI Series
        for (var attr in response) {
            var part = attr.split('_'),
                series = [];

            if ((part.length === 3) && (part[2] === 'hdi')) {
                data.hdiSeries.push({
                    year: parseInt(part[1], 10),
                    hdi: parseFloat(response[attr])
                });
            }
        }

        // Sort the data items
        data.hdiSeries.sort(function(a, b) { 
            return b.year - a.year; 
        });

        return data;
    }

The data object will contain the country's code, name, the selected flag, and the array of hdiSeries, which will contain objects that have the year and HDI value. The Countries collection will contain the CountryTrend instances for each country. The data will be retrieved from the Human Development Index Trends endpoint. We set the collection model, the endpoint URL, and a parse method, which will filter the items that have a country code (there are items for groups of countries). We will also add a method to set a selected item in order to ensure that there is only one selected item:

// Countries Collection
app.Countries = Backbone.Collection.extend({

    // Model
    model: app.CountryTrend,

    // JSON Endpoint URL
    url: 'http://data.undp.org/resource/efc4-gjvq.json',

    // Remove non-country items
    parse: function(response) {
        return response.filter(function(d) { 
            return d.country_code; 
        });
    },

    // Set the selected country
    setSelected: function(code) {

        var selected = this.findWhere({selected: true});

        if (selected) { 
            selected.set('selected', false); 
        }

        // Set the new selected item
        selected = this.findWhere({code: code});
        if (selected) {
            selected.set('selected', true); 
        }
    }
});

We will proceed to create the views for the models.

The application will have three views: the chart with the trends of HDI values for the ranked countries, the information view at the right-hand side, and the search form.

CountriesTrendView is a view of the Countries collection, which displays the evolution of the HDI for the ranked countries. As we did in Chapter 6, Interaction between Charts, we will create a Backbone View that will contain an instance of a D3-based chart:

// Countries Trend View
app.CountriesTrendView = Backbone.View.extend({

    // Initialization and render
    initialize: function() {
        this.listenTo(this.collection, 'reset', this.render);
        this.listenTo(this.collection, 'change:selected', this.render);
    }
});

In the initialize method, we start listening for the reset event of the collection and the change:selected event, which are triggered when an element of the collection is selected. In both cases, we will render the view. We will add and configure an instance of the D3-based chart, hdi.chart.trends:

app.CountriesTrendView = Backbone.View.extend({
    // Initalization and render...

    // Initialize the trend chart
    chart: hdi.chart.trend()
        .series(function(d) { return d.hdiSeries; })
        .x(function(d) { return d.year; })
        .y(function(d) { return d.hdi; }),

    // Initialize and render methods...
});

We will skip the description of the hdi.chart.trend chart for brevity, but as usual, the chart is implemented using the reusable chart pattern and has accessor methods to configure its behavior. The chart displays the time series of HDI measurements for all the ranked countries, highlighting the line bound to a data item with the selected attribute set to true.

The HDI trend chart

In the render method, we get the width of the container element of the view and update the width of the chart using this value. We select the container element, bind the collection data to the selection, and invoke the chart:

    // Update the chart width and bind the updated data
    render: function() {
        // Update the width of the chart
        this.chart.width(this.$el.width());

        // Rebind and render the chart
        d3.select(this.el)
            .data([this.collection.toJSON()])
            .call(this.chart);
    },

We will also add the setState method to change the selected country of the underlying collection. This method will help us to update the selected item of the collection when the application model changes the selected country. We will do this later in the application setup:

    // Update the state of the application model
    setState: function(state) {
        this.collection.setSelected(state.get('code'));
    }

The search form will allow the user to search among the ranked countries to select one of them. We will use the Typeahead jQuery plugin from Twitter (http://twitter.github.io/typeahead.js/) to provide autocompletion, and we will populate the suggestion list with the items in the Countries collection. The Typeahead plugin contains two components: Bloodhound, the autocompletion engine, and Typeahead, the plugin that adds autocompletion capabilities to an input field.

In the initialize method, we bind the reset event of the collection to the render method in order to update the view when the list of country trends is retrieved:

// Search Form View
app.CountriesSearchView = Backbone.View.extend({

    // Initialize
    initialize: function() {
        this.listenTo(this.collection, 'reset', this.render);
    },

    // Events and render methods...
});

The DOM element associated with this view will be a div containing the search form, which is located in the navigation bar. We assign an ID to the div and to the input field:

<div class="form-group" id="search-country">
  <input type="text" class="form-control typeahead"
         placeholder="Search country"id="search-country-input">
</div>

To provide autocompletion, we need to initialize the autocompletion engine and add the autocompletion features to the search input item:

    // Render the component
    render: function() {
        // Initialize the autocompletion engine
        // Add autocompletion to the input field
    },

We initialize the Typeahead autocompletion engine; setting the datumTokenizer option is a function that, given a data element, returns a list of strings that should be associated with the element. In our case, we want to match the country names; so, we use the whitespace tokenizer and return the country name split by whitespace characters. The input of the search field will be split using whitespace characters too. We add the list of elements among which we want to search, which in our case are the elements in the collection:

    // Render the component
    render: function() {
        // Initialize the autocompletion engine
        this.engine = new Bloodhound({
            datumTokenizer: function(d) { 
                return Bloodhound.tokenizers.whitespace(d.name); 
            },
            queryTokenizer: Bloodhound.tokenizers.whitespace,
            local: this.collection.toJSON()
        });
        this.engine.initialize();

        // Add autocompletion to the input field...
    },

To add the autocompletion features to the search form, we select the input element of the view and configure the typeahead options. In our case, we just want to show the name of the country and use the engine dataset as the source for the autocompletion:

        // Render the element
        this.$el.children('#search-country-input')
            .typeahead(null, {
                displayKey: 'name',
                source: this.engine.ttAdapter()
            });

When the user begins to type in the input field, the options that match the input will be displayed. When the user selects an option, the typeahead:selected event will be triggered by the input element. We will add this to the event's hash of the view, binding the event to the setSelected callback:

    events: {
        'typeahead:selected input[type=text]': 'setSelected'
    },

Note that the typeahead:selected event is a jQuery event. The callback will receive the event and the data item selected by the user, and it will update the selected item in the collection, as follows:

    //  Update the selected item in the collection
    setSelected: function(event, datum) {
        this.collection.setSelected(datum.code);
    }

The Typeahead autocompletion in action

The last view will be CountryInformationView. This view is a visual representation of the CountryInformation model. For this view, we will add the _includes/country-information.html file with the contents of the template and include it in the index.md file:

---
layout: main
title: HDI Explorer
---

{% include country-information.html %}

<!-- More content... -->

The template will contain several internal div elements; we will show only a part of the template here:

<!-- Country Information Template -->
<script type="text/template" id="country-summary-template">

<!-- Country Name and Rank -->
<div class="row country-summary-title">
  <div class="col-xs-8"><%= name %></div>
  <div class="col-xs-4 text-right">#<%= hdi_rank %></div>
</div>

<!-- HDI Value and Rank of the Country -->
<div class="row country-summary-box">
  <!-- Header -->
  <div class="col-xs-12 country-summary-box-header">
    <i class="fa fa-bar-chart-o fa-fw"></i>
    human development index
  </div>
  <!-- HDI Index -->
  <div class="col-xs-12">
    <div class="col-xs-9">human development index</div>
    <div class="col-xs-3 text-right"><%= hdi_value %></div>
  </div>
  <!-- Country Rank -->
  <div class="col-xs-12">
    <div class="col-xs-9">hdi rank</div>
    <div class="col-xs-3 text-right"><%= hdi_rank %></div>
  </div>
</div>

<!-- More divs with additional information... -->
</script>

Here, we create the structure of the bar on the right-hand side, which will contain the Human Development Index, rank, life expectancy, education statistics, and income for the selected country. We will use the Underscore templates to render this view. The view structure is simpler in this case; we just compile the template, listen to the changes of country name in the model, and render the template with the model data:

// Country Information View
app.CountryInformationView = Backbone.View.extend({
    // View template
    template: _.template($('#country-summary-template').html()),

    initialize: function() {
        // Update the view on name changes
        this.listenTo(this.model, 'change:name', this.render);
    },

    render: function() {
        // Render the template
        this.$el.html(this.template(this.model.toJSON()));
    }
});

The rendered view will display the current values for the HDI components

With the models, collections, and views created, we can create the respective instances and bind events to callbacks in order to keep the views in sync. We begin by creating an instance of the application model and the collection of country HDI trends. In the js/app/setup.js file, we create and configure the model, collection, and view instances:

// Application Model
app.state = new app.ApplicationModel();

// HDI Country Trends Collection
app.countries = new app.Countries();

After the application's state changes, we will have to update the selected item in the Countries collection. We bind the change:code event of the application model to the callback that will update the selected item in the collection:

// Update the selected item in the countries collection
app.countries.listenTo(app.state, 'change:code', function(state){
    this.setSelected(state.get('code'));
});

We need to update the application state when the Countries collection is populated for the first time. We will set the application state's code attribute to the code of the first element in the collection of countries. We also bind the change:selected event of the collection to update the application model:

app.countries.on({
    'reset': function() {
        app.state.set('code', this.first().get('code'));
    },

    'change:selected': function() {
        var selected = this.findWhere({selected: true});
        if (selected) {
            app.state.set('code', selected.get('code'));
        }
    }
});

Note that when we are selecting an item, we are also deselecting another item. Both the items will trigger the change:selected event, but the application should change its state only when an item is selected. We can now fetch the countries data, passing the reset flag to ensure that any existing data is overwritten:

app.countries.fetch({reset: true});

We create an instance of the CountryInformation model and bind the changes to the code attribute of the application to the changes of the state in the model. The setState method will fetch the information for the code given by the application state:

// HDI Information
app.country = new app.CountryInformation();
app.country.listenTo(app.state, 'change:code', app.country.setState);

We can now create instances of the views. We will create an instance of the CountriesTrendView. This view will be rendered in the div element with the #chart ID:

// Countries Trend View
app.trendView = new app.CountriesTrendView({
    el: $('div#chart'),
    collection: app.countries
});

We create an instance and configure the CountriesSearchView. This view will be rendered in the navigation bar:

app.searchView = new app.CountriesSearchView({
    el: $('#search-country'),
    collection: app.countries
});

We also create a CountryInformationView instance, which will be rendered in the right-hand side of the page:

app.infoView = new app.CountryInformationView({
    el: $('div#table'),
    model: app.country
});

In the index.md file, we create the elements where the views will be rendered and include the application files. In the main.html layout, we include the CSS styles of the application, Bootstrap and Font Awesome:

---
layout: main
title: HDI Explorer
---

{% include country-information.html %}

<div class="container-fluid">
  <div class="row">
    <div class="col-md-8" id="chart"></div>
    <div class="col-md-4 country-summary" id="table"></div>
  </div>
</div>

<scriptsrc="{{ site.baseurl }}/dependencies.min.js"></script>
<scriptsrc="{{ site.baseurl }}/hdi.min.js"></script>

The application served by Jekyll on a localhost

Here, we consolidated jQuery, Bootstrap, Underscore, Backbone, Typeahead, and D3 in the dependencies.min.js file and the application models, collections, views, and chart in the hdi.min.js file. To create these consolidated files, we created a Gruntfile and configured concatenation and minification tasks as we did in Chapter 7, Creating a Charting Package. As the configuration of the tasks is similar to the configuration presented in the previous chapter, we will skip its description.

It is also worth mentioning that in general, it is not a good practice to include complete libraries. For instance, we included the complete Bootstrap styles and JavaScript components, but in the application, we used only a small part of the features.

Bootstrap allows you to include the components individually, reducing the payload of the page and improving the performance. We also included the Font Awesome fonts and styles only to include four icons. In a project where performance is crucial, we will probably include only the components that we really need.