Click here to Skip to main content
15,867,308 members
Articles / Web Development / HTML

The Great War in Europe: 1914-1918

Rate me:
Please Sign up or sign in to vote.
4.98/5 (42 votes)
6 Jul 2016CPOL14 min read 48.1K   389   41   21
An interactive map using C#, SVG, JavaScript, Angular and YouTube

Author's Note

Quote:

After downloading the code, open the Great War folder as a Web Site in Visual Studio:

Image 1

Image 2

Introduction

This article is an exercise to build an interactive map SPA (Single Page Application) aimed at remembering the 100 years of the fateful days of the Great War of 1914-1918. One hundred years ago, it was involving a sizable part of the world, and dragging Europe into a turmoil of destruction and social chaos.

The application was built as an educational tool to help students and history geeks to improve knowledge and consolidate their understanding, by merging geographical historical maps, chronological events and modern video documentaries about the Great War.

Background

There are some ways to build an interactive map using different technologies. One of them is through Web mapping, using Geographical Information Systems (GIS), such as Open Street Map, which delivers a lot of information and many built-in tools, but might be easily an overkill for our simple application. Another solution involves a simpler approach, through direct drawing of the map and controlling the graphic elements. For this purpose, we could use a battle-hardened technology (some pun intended) such as Adobe Flash, which had its days of glory, but now mostly a no-go for new projects. Now they are generally built with HTML5, which means using canvas or Scalable Vector Graphics (SVG). Of these two options, the SVG seemed to be the most reasonable choice because of all the zooming and panning that is needed for maps. Canvas is really fast, but since it works as a bitmap (not vector graphics), zooming can be tricky and processor intensive, while SVG works as a set of independent vector-constructed DOM elements, which can be more naturally zoomed as needed.

How It Works

Interactive Map

SVG (Bonsai JS)

Image 3

For the task of manipulating SVG, some alternatives for libraries were considered: Raphaël, Velocity JS, SVG JS, Walkway, Snap SVG, Bonsai JS, Lazy Line Painter, Vivus, Progressbar JS and Two JS. All of them pretty full-featured and have their own merits, but from these, I chose Bonsai JS because of the following features:

  • Architecturally separated runner and renderer
  • iFrame, Worker and Node running contexts
  • Paths
  • Assets (Audio, Video, Images, Fonts, SubMovies)
  • Keyframe and time based animations (easing functions too)
  • Path morphing

Getting Started with Bonsai JS

Bonsai JS requires only three things:

  1. The Bonsai script:
    HTML
    <script src="http://cdnjs.cloudflare.com/ajax/libs/bonsai/0.4/bonsai.min.js"></script>
  2. The movie div element:
    HTML
    <div id="movie"></div>
  3. The <class>bonsai.run code to start creating drawing:
    JavaScript
    var movie = bonsai.run(
    document.getElementById('movie')
    , {
        urls: ['js/linq.min.js', 'js/model.js', 'js/great-war-worker.js'],
        width: 800,
        height: 400
    });

The following line of the above script declares which JavaScript files will run in the context of the Web Worker thread. In this line, we must declare not only the main application file (great-war-worker.js) but also its dependencies (linq.min.js and model.js). Keep in mind that the <class>Bonsai code runs in a separate thread. For this reason, whatever JavaScript code runs in the main web page context will remain invisible and inaccessible.

JavaScript
urls: ['js/linq.min.js', 'js/model.js', 'js/great-war-worker.js'],

Web Worker Messaging

Since Bonsai JS requires the JavaScript code to run in a Web Worker and in a separate thread, the code containing Bonsai-related objects (i.e., SVG elements), cannot access the DOM directly, and vice versa. For this reason, we should establish a two-way communication through Bonsai's proprietary messaging.

Image 4

Event model for web workers - Image by: Tom Pascall's Web workers and responsiveness.

We must first create handlers dedicated to listening to each kind of messages, from both the DOM thread and the Web Worker thread. Once the handlers are ready, we can send the messages that will pass information to and from the parts involved.

The handlers in the <class>Web Page side are set up as follows. Notice that the events are attached only after the default <class>load message is called. This signals that the communication is already established. Then comes the messages related to Country elements (overCountry/outCountry/clickLocation). Finally comes the ready message, which invokes the zoom and panning control (that will be explained soon). And inside that, we can see how the zoomChanged message (inside onZoom event) is sent from the Web Page to Web Worker, so that the SVG map can modify its appearance based on the scale parameter (more on that soon). The commands to listen to/send messages are functions of the <class>movie

JavaScript
var movie = bonsai.run(...);
// emitted before code gets executed
movie.on('load', function () {
    // receive event from the runner context
    movie.on('message:overCountry', function (countryData) {
        ...
        ... highlight the country wherever it is found on the timeline list
        ...
    });
    movie.on('message:outCountry', function (countryData) {
        ...
        ... undo highlighting the country wherever it is found on the timeline list
        ...
    });
    movie.on('message:clickLocation', function (countryData) {
        ...
        ... toggle highlighting for the selected country
        ... and start a new search by that country name
        ...
    });
    movie.on('message:ready', function () {
        $('svg').attr('id', 'svg-id');
        var panZoomInstance = svgPanZoom('#svg-id', {
            onZoom: function (scale) {
                movie.sendMessage('zoomChanged', {
                    scale: scale
                });
            },
            ,
            , // a bunch of zooming/panning configurations
            ,
        });
        // zoom out
        panZoomInstance.zoom(1.0);
    });
});

In the <class>Web Worker, on the other hand, the commands to listen to or emit messages are attached to the <clas>stage object, which functions as the root instance for the hierarchy of objects in Bonsai JS.

JavaScript
stage.on('message:enterCountry', function (data) {...
stage.on('message:leaveCountry', function (data) {...
stage.on('message:clickLocation', function (data) {...
stage.on('message:zoomChanged', function (data) {...
stage.on('message:timeLineEventChanged', function (data) {...
    ...
stage.sendMessage('ready', {});
    ...
stage.sendMessage('overCountry', scope.countryData);
    ...
stage.sendMessage('outCountry', scope.countryData);
    ...
stage.sendMessage('clickLocation', scope.countryData);
    ...

Web Worker Main Script (great-war-worker.js)

The great-war-worker.js is structured as to provide separated functionality for three main entities: Country, BigCity and SmallCity. Both BigCity and SmallCity are inherited from BaseCity via prototype chain.

JavaScript
function WorldWarOne(data) {...}
var CountryObject = function (p, data, i, myColor) {...}
var BaseCity = function (parent, data) {...}
var BigCity = function (parent, data) {...}
var SmallCity = function (parent, data, citySize) {...}

The <class>WorldWarOne object is the instance that holds all other instances inside our Web Worker JavaScript code. As it can be seen, each one of these objects is constructed according to the data provide by the model.js file.

JavaScript
    function WorldWarOne(data) {
    var scope = this;
    ...
    ...local vars go here...
    ...
    for (var i = 0; i < model.countries.length ; i++) {
        ...
        ... country shapes are built here
        ...
    }
    for (var i = 0; i < model.cities.length ; i++) {
        ...
        ... major city shapes are built here
        ...
    }
    for (var i = 0; i < model.locations.length ; i++) {
        ...
        ... minor city shapes are built here
        ...
    }
    ...
}

Countries

Looking at the map, you immediately notice that many modern countries are missing. That's 1914, the age of fierce nationalism, but also the age of even stronger imperialism. And at the end of the conflict, some of these empires are about to collapse forever (or at least for the following 21 years, until another catastrophic war ensued).

Image 5

The lines that represent the country borders have been extracted from an existing SVG file provided by d-maps.com. This SVG file is a set of <class>Path objects grouped together, each <class>Path for the territories of an independent country on the map.

The <class>Path objects have been extracted from the original file, and put in our /js/model.js file, so that they can be easily manipulated via code (JavaScript).

JavaScript
var model = {
countries: [
    { code: 'SWE', name: 'Sweden', path: 'M175 32.4866c-0.1298,0 -0.2026,0.0572...' },
    { code: 'AUS', name: 'Austria-Hungary', path: 'M159.488 141.139l-0.4984 0.0106...' },
    { code: 'ROM', name: 'Romania', path: 'M229.156 119.752l-1.3951 -0.194c-0.7951,...' },
    { code: 'BUL', name: 'Bulgaria', path: 'M193.766 132.125c0.2347,0.0681...' },
    { code: 'SER', name: 'Serbia', path: 'M175.82 138.657c0.0416,0.1672 0.6748,1.3374...'},
    { code: 'MON', name: 'Montenegro', path: 'M175.058 149.117l0.7225 -1.5865c0.1538,...'
    { code: 'GER', name: 'Germany', 
      path: 'M152.074 55.2057c-0.0882,-0.0052 -0.135,-0.0208 ...'},
    .
    .
    .
],
.
.
.

The map countries are divided according to the three existing political groups during the conflict: Entente, Central Powers and Neutral Countries. Each of these groups are assigned with a different color.

JavaScript
var model = {
.
.
.
tripleEntente: { color: '#80c0ff', countries: 
['POR', 'GBR', 'FRA', 'BEL', 'ITA', 
'RUS', 'ROM', 'SER', 'MON', 'ALB', 'GRE'] },
centralPowers: { color: '#ffc080', 
countries: ['GER', 'AUS', 'BUL', 'TUR'] },
neutral: { color: '#808080', 
countries: ['NOR', 'SWE', 'DEN', 'NET', 'SWI', 'SPA'] }
}

Each country shape is built according to its shape ("path" property) and political block color (Neutral = grey, Entente = blue, Central Powers = salmon).

JavaScript
...
...
...
for (var i = 0; i < model.countries.length ; i++) {
    var c = model.countries[i];
    var myColor = '#808080';
    if (model.tripleEntente.countries.indexOf(c.code) >= 0) {
        myColor = model.tripleEntente.color;
    }
    else if (model.centralPowers.countries.indexOf(c.code) >= 0) {
        myColor = model.centralPowers.color;
    }
    else if (model.neutral.countries.indexOf(c.code) >= 0) {
        myColor = model.neutral.color;
    }
    var countryObject = new CountryObject(this, c, i, myColor)
    this.countries.push(countryObject);
}
...
...
...

Image 6

Panning and Zooming

Image 7

Panning and zooming is what allows us to freely see the map in its details, after observing the whole picture. But simply embedding a map in our page will not allow us to pan and zoom as we wish. Instead, we should provide some control buttons to do it (along with the ability to move the image towards any direction and use mouse wheel to scale it up and down.

Thankfully, we have a handy toolset at SVG-Pan-Zoom library. As they describe it themselves:

Simple pan/zoom solution for SVGs in HTML. It adds events listeners for mouse scroll, double-click and pan, plus it optionally offers:

  • JavaScript API for control of pan and zoom behavior
  • onPan and onZoom event handlers
  • On-screen zoom controls
  • It works cross-browser and supports both inline SVGs and SVGs in HTML object or embed elements

The on-screen zoom controls work precisely as intended, as one can see by their demo.

Image 8

The SVG-Pan-Zoom library works with a set of configurations.

  • viewportSelector can be querySelector string or SVGElement.
  • panEnabled must be true or false. Default is true.
  • controlIconsEnabled must be true or false. Default is false.
  • zoomEnabled must be true or false. Default is true.
  • dblClickZoomEnabled must be true or false. Default is true.
  • mouseWheelZoomEnabled must be true or false. Default is true.
  • preventMouseEventsDefault must be true or false. Default is true.
  • zoomScaleSensitivity must be a scalar. Default is 0.2.
  • minZoom must be a scalar. Default is 0.5.
  • maxZoom must be a scalar. Default is 10.
  • fit must be true or false. Default is true.
  • contain must be true or false. Default is false.
  • center must be true or false. Default is true.
  • refreshRate must be a number or auto.
  • beforeZoom must be a callback function to be called before zoom changes.
  • onZoom must be a callback function to be called when zoom changes.
  • beforePan must be a callback function to be called before pan changes.
  • onPan must be a callback function to be called when pan changes.
  • customEventsHandler must be an object with init and destroy arguments as functions.
  • eventsListenerElement must be an SVGElement or null.

We set up our SVG-Pan-Zoom instance as follows:

JavaScript
var panZoomInstance = svgPanZoom('#svg-id', {
    zoomEnabled: true
    , controlIconsEnabled: true
    , dblClickZoomEnabled: true
    , mouseWheelZoomEnabled: true
    , preventMouseEventsDefault: true
    , zoomScaleSensitivity: 0.25
    , minZoom: 1
    , maxZoom: 10
    , fit: true
    , contain: false
    , center: true
    , refreshRate: 'auto'
    , beforeZoom: function () { }
    , onZoom: function (scale) {
        movie.sendMessage('zoomChanged', {
            scale: scale
        });
    }
    , beforePan: function () { }
    , onPan: function () { }
    , eventsListenerElement: null
});

Notice that we must pass the selector of the SVG element that will be dealt with (in this case, id='svg-id').

The good news is that you don't have to mess with your Bonsai JS code (that is, Web Worker code) to perform panning/zooming: it's all within the main Web Page thread.

Once the above code is called, the SVG-Pan-Zoom controls pop up over the SVG image:

Image 9

If you scroll your mouse wheel or push the on-screen plus button, you will see the SVG image scaling up:

Image 10

...a little more...

Image 11

If you take any map application as an example, you will see that, despite the volume of data contained in the map, the information is only displayed on demand. If you zoom out, you should see only the most relevant data. Once you zoom in, you start seeing the details.

For this reason, each time the zoom changes, we send a message to the Web Worker thread (with the new scale as the parameter), which in turn will perform some operations, such as showing/hiding minor cities, changing font sizes and making countries's borders thinner, so that these zoomed in elements don't clutter the visualization.

JavaScript
var panZoomInstance = svgPanZoom('#svg-id', {
    , onZoom: function (scale) {
        movie.sendMessage('zoomChanged', {
            scale: scale
        });
    }
});

Image 12

Major Cities

Image 13

Major cities (that is, capital cities and cities that would soon become new countries' capital cities) are treated differently in the application. Their name has a bigger font size, and they appear visible even when no scale is applied.

JavaScript
var model = {
.
.
.,
cities: [
    { name: 'London', x: 166, y: 136 },
    { name: 'Paris', x: 175, y: 178 },
    { name: 'Lisbon', x: 21, y: 278 },
    { name: 'Madrid', x: 84, y: 278 },
    { name: 'Bern', x: 220, y: 215 },
    { name: 'Brussels', x: 202, y: 153 },
    { name: 'Amsterdam', x: 212, y: 129 },
    { name: 'Copenhagen', x: 275, y: 92 },
    { name: 'Oslo', x: 277, y: 34 },
    { name: 'Stockholm', x: 330, y: 40 },
    { name: 'Berlin', x: 290, y: 148 },
    { name: 'Prague', x: 294, y: 180 },
    { name: 'Vienna', x: 305, y: 208 },
    { name: 'Rome', x: 263, y: 296 },
    { name: 'Sarajevo', x: 324, y: 272 },
    { name: 'Athens', x: 384, y: 353 },
    { name: 'Constantinople', x: 441, y: 302 },
    { name: 'Bucarest', x: 406, y: 260 },
    { name: 'Sofia', x: 374, y: 287 },
    { name: 'Belgrade', x: 344, y: 262 },
    { name: 'Budapest', x: 331, y: 218 },
    { name: 'Warsaw', x: 351, y: 147 },
    { name: 'Moscow', x: 481, y: 78 },
    { name: 'Dublin', x: 117, y: 93 },
    { name: 'Belfast', x: 127, y: 75 },
    { name: 'Tunis', x: 229, y: 364 },
    { name: 'Kiev', x: 436, y: 167 },
    { name: 'Minsk', x: 403, y: 121 },
    { name: 'Vilnius', x: 384, y: 111 },
    { name: 'Riga', x: 372, y: 78 },
    { name: 'Edimburg', x: 152, y: 63 },
    { name: 'Rabat', x: 22, y: 359 },
    { name: 'Algiers', x: 144, y: 357 },
    { name: 'Zagreb', x: 299, y: 241 }
]
.
.
.
};

Battle Locations

Image 14

These kind of sites appear with smaller font size, and are not immediately visible. It would appear only when the user started zooming to a minimum scale.

JavaScript
    stage.on('message:zoomChanged', function (data) {
        scope.scale = data.scale;
        ...
        for (var i = 0; i < scope.locations.length ; i++) {
            var l = scope.locations[i];
            l.zoomChanged(scope.scale);
        }
        ...
    });
SmallCity.prototype.zoomChanged = function (value) {
    var scope = this;
    scope.cityPath.attr({
        scale: 2 ^ (1.0 / (value * .8))
    });
    if (value > 2) {
        scope.cityPath.attr({
            visible: false
        });
        scope.textGroup.attr({
            visible: true
        });
    }
    else {
        scope.cityPath.fill('#000');
        scope.cityPath.attr({
            visible: false
        });
        scope.textGroup.attr({
            visible: false
        });
    }
};

Image 15

When these locations are selected in the timeline list, the corresponding position in the map will be marked by a Map Pin image (similar to the famous Google Maps pin).

JavaScript
stage.on('message:timeLineEventChanged', function (data) {
if (data.event) {
    var event = data.event;
    if (event) {
        if (event.position) {
            scope.mapPin
            .attr({
                x: event.position.x + 15 + MAP_OFFSET.x,
                y: event.position.y - 5 + scope.scale * 2 -
                (scope.scale - 1) * 1.65 + MAP_OFFSET.y,
                visible: true
            });
            scope.mapPin.animate('.5s', {
                fillColor: '#880'
            }, {
                repeat: 10000
            });
        }
        else {
            scope.mapPin
            .attr({
                visible: false
            });
        }
    }
    else {
        scope.mapPin.attr({ visible: false });
    }
}
else {
    scope.mapPin.attr({ visible: false });
}

Selecting Countries

Image 16

There are two modes of selection of countries. The first is when the mouse is moving over the country in the map (at this point, the country is temporarily highlighted), and the second is when the user clicks on the country. This single click toggles the selection of the country, and can also unselect it a second time.

JavaScript
    stage.on('message:enterCountry', function (data) {
        for (var i = 0; i < scope.countries.length ; i++) {
            var c = scope.countries[i];
            if (c.countryData.name == data.country) {
                c.animateCountrySelection();
            }
        }
    });
    stage.on('message:leaveCountry', function (data) {
        for (var i = 0; i < scope.countries.length ; i++) {
            var c = scope.countries[i];
            var selectedCountryName =
                scope.selectedCountry ?
                scope.selectedCountry.countryData.name
                : '';
            if (c.countryData.name == data.country
                && data.country != selectedCountryName) {
                c.animateCountryUnselection();
            }
        }
    });
    stage.on('message:clickLocation', function (data) {
        for (var i = 0; i < scope.countries.length ; i++) {
            var c = scope.countries[i];
            if (c.countryData.name == data.country) {
                scope.click(c);
                c.animateCountrySelection();
            }
        }
    });
...
var CountryObject = function (p, data, i, myColor) {
    var scope = this;
    scope.over = function () {
        if (!parent.ready) {
            parent.setReady();
        }
        stage.sendMessage('overCountry', scope.countryData);
        scope.animateCountrySelection();
    };
    scope.animateCountrySelection = function () {        
        scope.countryPath.animate('.2s', {
            fillColor: scope.kolor.darker(.3)
        }, {
            easing: 'sineOut'
        });
    }
    scope.animateCountryUnselection = function () {
        scope.countryPath.animate('.2s', {
            fillColor: scope.kolor
        }, {
            easing: 'sineOut'
        });
    }
    scope.out = function () {
        stage.sendMessage('outCountry', scope.countryData);
        if (!scope.selected) {
            scope.animateCountryUnselection();
            if (parent.selectedCountry) {
                stage.sendMessage('overCountry', parent.selectedCountry.countryData);
            }
        }
    }
    scope.click = function () {
        parent.click(scope);
        stage.sendMessage('clickLocation', scope.countryData);
    };
    ...

When the user toggles a country, the timeline list is automatically filtered by that country's name, so only the events relevant for that country will be visible.

Timeline Panel

Image 17

Server Side Service

While all the rest is running on the client browser, this one the only piece of server-side functionality, contained in the Generic Handler (/services/GetTimeline.ashx file).

The handler accepts two parameters:

  • lastId: the last event id. Means that the service should retrieve only the items (timeline events) following the given Event Id. Default is zero.
  • txt: the criteria text to filter by. Default is empty string.
C#
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Net;
using System.Web;
public class GetTimeline : IHttpHandler {
    const int PAGE_SIZE = 8;
    const int MIN_SEARCH_TERM_SIZE = 4;
    public void ProcessRequest (HttpContext context) {
        var uri = new Uri(new Uri(context.Request.Url.AbsoluteUri), "timeline.json");
        List<TimelineEvent> list = new List<TimelineEvent>();
        var timelineJson = new WebClient().DownloadString(uri.ToString());
        list = JsonConvert.DeserializeObject<List<TimelineEvent>>(timelineJson);
        int id = 1;
        list.ForEach(i => i.id = id++);
        var lastId = int.Parse(context.Request["lastId"]);
        var searchText = context.Request["txt"];
        var query = list
            .Where(q => string.IsNullOrEmpty(searchText) ||
                       searchText.Length < MIN_SEARCH_TERM_SIZE ||
                       CultureInfo.CurrentCulture
                          .CompareInfo
                          .IndexOf(q.text, searchText, CompareOptions.IgnoreCase) >= 0)
            .Where(i => i.id > lastId)
            .Take(PAGE_SIZE);
        var result = query.ToList();
        var json = JsonConvert.SerializeObject(result);
        context.Response.ContentType = "application/json";
        context.Response.Write(json);
    }
    public bool IsReusable {
        get {
            return false;
        }
    }
}
public class TimelineEvent
{
    public int id { get; set; }
    public int year { get; set; }
    public string date { get; set; }
    public string text { get; set; }
    public int[] position { get; set; }
    public string videoCode { get; set; }
}
JavaScript
[
    { "year": 1914, "date": "June 28", 
      "text": "Assassination of Archduke Franz Ferdinand of Austria, 
       heir to the Austro-Hungarian throne, who was killed in Sarajevo along with 
       his wife Duchess Sophie by Bosnian Serb Gavrilo Princip.[1]", 
       "position": [324, 272], "videoCode": "ZmHxq28440c" },
    { "year": 1914, "date": "July 5", "text": "@Austria-Hungary 
       seeks German support for a war against @Serbia in case of Russian militarism. 
       @Germany gives assurances of support.[2]" },
    { "year": 1914, "date": "July 23", "text": "@Austria-Hungary sends 
       an ultimatum to @Serbia. The Serbian response is seen as unsatisfactory.[3]" },
    { "year": 1914, "date": "July 28", "text": "@Austria-Hungary 
       declares war on @Serbia. @Russia mobilizes.[4]; 
       The @Netherlands declare neutrality." },
    { "year": 1914, "date": "July 31", "text": "@Germany warns @Russia 
       to stop mobilizing. @Russia says mobilization is against @Austria-Hungary.; 
       @Germany declares war on @Russia.[5]; @Italy declares its neutrality.; 
       Denmark declares its neutrality.[6]; @Germany and the @Ottoman Empire 
       sign a secret alliance treaty.[7]; August 2; Skirmish at Joncherey, 
       first military action on the Western Front" },
    { "year": 1914, "date": "August 2–26", 
      "text": "@Germany besieges and 
       captures fortified Longwy 'the iron gate to Paris' near the @Luxembourg border, 
       opening @France to mass German invasion", "position": [208, 177] },
.
.
.
    { "year": 1918, "date": "November 12", 
    "text": "Austria proclaimed a republic." },
    { "year": 1918, "date": "November 14", 
    "text": "Czechoslovakia proclaimed a republic." },
    { "year": 1918, "date": "November 14", 
    "text": "German U-boats interned." },
    { "year": 1918, "date": "November 14", 
    "text": "3 days after the armistice, 
       fighting ends in the East African theater when General von Lettow-Vorbeck 
       agrees a cease-fire on hearing of @Germany's surrender." },
    { "year": 1918, "date": "November 21", 
    "text": "@Germany's Hochseeflotte 
       surrendered to the @United Kingdom.[63]" },
    { "year": 1918, "date": "November 22", 
    "text": "The Germans evacuate @Luxembourg." },
    { "year": 1918, "date": "November 25", 
    "text": "11 days after agreeing a cease-fire, 
       General von Lettow-Vorbeck formally surrenders his undefeated army at Abercorn 
       in present-day Zambia." },
    { "year": 1918, "date": "November 27", 
    "text": "The Germans evacuate @Belgium." },
    { "year": 1918, "date": "December 1", "text": "Kingdom of Serbs, 
       Croats and Slovenes proclaimed." }
]

Angular JS

There are many benefits of using Angular JS in this project. They include a more structured JavaScript code, templating, two-way-data-binding, modular development and fits nicely in a SPA (Single Page Application) like this.

First, we declare the Angular app name (ng-app) and the controller name (ng-controller).

HTML
<div class="" ng-app="greatWarApp" ng-controller="greatWarCtrl">

Then we bind the timeline events to our HTML via the ng-bind attribute. And we also ensure the timeline grid will show each event in timeline.events by declaring iteration through the ng-repeat attribute.

HTML
...
<div ng-repeat="event in timeline.events">
    <div class="col-xs-2 col-md-2">
        <div><span class="date" ng-bind="event.date"></span></div>
        <div><span class="year" ng-bind="event.year"></span></div>
    </div>
    <div class="col-xs-8 col-md-8">
        <div bind-html-compile="event.text"></div>
    </div>
</div>
...

Before showing in the timeline, each event text is modified in the Angular App code (file: /js/great-war-app.js), so that each country shows as a link. This is done by replacing the plain text of the country's name that comes from the service by an anchor HTML element (<a>).

JavaScript
angular.forEach(model.countries, function (v2, k2) {
var c = model.countries[k2];
ev.text = ev.text.replace(new RegExp('\@' + c.name, 'g')
    , '<a country-link="' + c.name + '">' + c.name + '</a>');
if (k2 == 0)
    this.year = v2.year;
});

There is a problem with this approach, though. When you simply bind a text containing HTML tags, they will be converted as plain text and shown as-is by Angular binding engine. If we want to automatically convert any HTML tags inside text in the binding, we should compile through a specialized directive, such as:

JavaScript
var app = angular.module("greatWarApp", 
          ["angular-bind-html-compile", "youtube-embed", "infinite-scroll"]);

The next step will be to replace the usual ng-bind-html directive by the attribute of the specialized bind-html-compile directive, and the binding value will magically be interpreted as HTML code:

HTML
<div bind-html-compile="event.text"></div>

Image 18

Notice also that each country name is replaced by an anchor element with the attribute country-link. This attribute invokes the custom directive <class>countryLink, which in turn will handle the mouseenter, mouseleave and click events on the country's link.

JavaScript
    app.directive('countryLink', function () {
    var SELECTED_HIGHLIGHTED = 'highlighted';
    return {
        restrict: 'A',
        scope: {
            countryLink: '@'
        },
        link: function (scope, element) {
            element.on('mouseenter', function () {
                movie.sendMessage('enterCountry', {
                    country: scope.countryLink
                });
            });
            element.on('mouseleave', function () {
                movie.sendMessage('leaveCountry', {
                    country: scope.countryLink
                });
            });
            element.on('click', function () {
                movie.sendMessage('clickLocation', {
                    country: scope.countryLink
                });
                var countryName = element.attr('country-link');
                if (element.hasClass(SELECTED_HIGHLIGHTED)) {
                    $('.events-grid a[country-link="' + 
                       countryName + '"]').removeClass('highlighted');
                }
                else {
                    $('.events-grid a[country-link]').removeClass('highlighted');
                    $('.events-grid a[country-link="' + 
                       countryName + '"]').addClass('highlighted');
                }
            });
        }
    };
})

Infinite Scrolling

When you have a big mass of data to show, it makes sense to partition it in distinct pages that you retrieve as you browse. One common way to paginate is to provide a more button that your user hit when he/she wants to load more, or automatically make a request to the next chunk of data as the user reach the bottom of the current list, and this is what we call Infinite Scrolling.

There are many ways to implement such infinite scrolling, and thankfully we have some <class>Angular directives to do the job, including the ngInfiniteScroll directive, which is quite straightforward and quick to implement.

HTML
<div panel-type="timeline" infinite-scroll='timeline.nextPage()'
 infinite-scroll-disabled='timeline.scrollDisabled()'
 infinite-scroll-distance='1' infinite-scroll-container='".events-grid"'>
    <div class="row row-eq-height scrollbox-content"
     ng-repeat="event in timeline.events" event-position="{{event.position}}">
        <div class="col-xs-12 col-md-12" ng-hide="!(event.video.code) ||
             !event.video.containerVisible">
            <div ng-class="event.video.containerVisibleCSSClass()">
                <youtube-video video-id="event.video.code" player-width="450"
                 player-height="276" player="event.video.player"
                 player-vars="event.video.vars"></youtube-video>
            </div>
        </div>
        <div class="col-xs-2 col-md-2 icon-container">
            <span class="icon-helper"></span>
            <span>
                <img src="img/icons/video.svg" width="32" height="32"
                 ng-class="event.video.iconCSSClass()"
                 ng-hide="!(event.video.code)" ng-click="event.video.click()" />
            </span>
        </div>
        <div class="col-xs-2 col-md-2">
            <div><span class="date" ng-bind="event.date"></span></div>
            <div><span class="year" ng-bind="event.year"></span></div>
        </div>
        <div class="col-xs-8 col-md-8">
            <div bind-html-compile="event.text"></div>
        </div>
        <div style='clear: both;'></div>
    </div>
</div>

The above code shows the <class>nextPage function invoking the <class>search function, which in turn produces a request to the service at GetTimeline.ashx.

JavaScript
    Timeline.prototype.nextPage = function () {
    var after = function (context) {
        context.lastId = context.events[context.events.length - 1].id;
    }
    this.search(after);
};
.
.
.
Timeline.prototype.search = function (after) {
    if (this.busy) return;
    this.busy = true;
    var url = "/services/GetTimeline.ashx?lastId=" +
               this.lastId + '&txt=' + this.searchText;
    $http({
        method: 'GET',
        url: url
    }).then(function successCallback(response) {
        var addedEvents = response.data;
        this.processTimelineResponse(addedEvents, this.events);
        this.busy = false;
        if (after)
            after(this);
        this.noMoreResults = (addedEvents.length < PAGE_SIZE);
    }.bind(this), function errorCallback(response) {
        // called asynchronously if an error occurs
        // or server returns response with an error status.
    }.bind(this));
}

Filtering

Image 19

Clicking on the country (or typing in a search criteria) will trigger a request to the service (Generic Handler, contained in /services/GetTimeline.ashx), so only the events containing that criteria will show up in the timeline list.

C#
public class GetTimeline : IHttpHandler {
...
    public void ProcessRequest (HttpContext context) {
        ...
        var lastId = int.Parse(context.Request["lastId"]);
        var searchText = context.Request["txt"];
        var query = list
            .Where(q => string.IsNullOrEmpty(searchText) ||
                       searchText.Length < MIN_SEARCH_TERM_SIZE ||
                       CultureInfo.CurrentCulture
                          .CompareInfo
                          .IndexOf(q.text, searchText, CompareOptions.IgnoreCase) >= 0)
            .Where(i => i.id > lastId)
            .Take(PAGE_SIZE);
        var result = query.ToList();
        ...
    }
}

Image 20

Youtube Embedded

Some events in the timeline are obviously more relevant than others, and in order to provide more information about them, the application provides the ability to watch a YouTube video for the corresponding Great War episode.

Image 21

The Great War is a great channel, probably the best YouTube channel on the Great War. It is hosted by American actor, writer and historian <a href="https://www.youtube.com/watch?v=eFqExXJSwRw">Indy Neidell</a>, who is from Texas and lives currently in Stockholm, Sweden. The channel provide a lot of invaluable information, amazing pics, video clips plus the charm and humor of Indy's hosting.

The YouTube team has long provided a complete JavaScript API for embedding YouTube videos in web pages. The problem is that at some point, we would have to integrate that YouTube code with our <class>Angular JS app.

For this reason, Matthew Brandly has taken the time to create the awesome Angular YouTube Embed, a directive aimed at integrating <class>Angular JS and YouTube JavaScript client code.

First, we have to declare the youtube-embed external directive at the setup of our Angular app.

JavaScript
var app = angular.module("greatWarApp", 
["angular-bind-html-compile", "youtube-embed", "infinite-scroll"]);

Then we implement the youtube-video directive, passing the video-id as a parameter. Notice that the events without a video code attached will not show the video icon.

HTML
<div class="col-xs-12 col-md-12" ng-hide="!(event.video.code) ||
    !event.video.containerVisible">
    <div ng-class="event.video.containerVisibleCSSClass()">
        <youtube-video video-id="event.video.code" player-width="450"
         player-height="276" player="event.video.player"
         player-vars="event.video.vars"></youtube-video>
    </div>
</div>

Another interesting feature of this application is the automatic selection of countries in the map as they are mentioned in the Youtube Video.

Image 22

At this moment, Indy Neidell is talking about three countries: Germany, Austro-Hungary and Russia.

Image 23

As soon as that subtitle appears on screen, those three countries (Germany, Austro-Hungary, Russia) are selected:

Image 24

At first, this does not appear to be a big deal, but it opens up a lot of possibilities. Just think about educational tools using Youtube videos and providing maps, images and other assets as a complement to the actual subject being taught on the videos!

But how does this work? First of all, some Youtube videos (not all, unfortunately) have transcripts associated to them.

Youtube video transcripts are accessible via the url: http://video.google.com/timedtext?lang=en&v=[VIDEO_CODE]

Once the video is opened, the transcript is obtained via get method, and the transcript property of the video object is set.

JavaScript
ev.video.player.playVideo();
setInterval(function () {
    this.timeoutFunction(ev);
}.bind(this), 1000);

 $http({
    method: 'GET',
    url: 'http://video.google.com/timedtext?lang=en&v=' + ev.videoCode
    }).then(function successCallback(response) {
        var xmlStr = response.data;
        var x2js = new X2JS();
        var jsonStr = JSON.stringify(x2js.xml_str2json(xmlStr));
        if (jsonStr) {
            ev.video.transcript = JSON.parse(jsonStr).transcript;
        }

(The resulting transcript is received as XML data. Notice the use of the x2js library which provides XML to JSON and vice versa.)

As the video is playing, the <class>timeoutFunction function searches for the specific transcript line where the current time falls between. If one line is found, the spoken line is parsed and interpreted to search for country or city names. If one or more locations are found in the transcript text, those locations are highlighted in the map, and will remain so until the player reaches the next transcript line.

JavaScript
this.timeoutFunction = function (ev) {
    if (ev.video.player.getPlayerState() == 1) {
        ev.video.time = ev.video.player.getCurrentTime();
        for (var i = 0; i < ev.video.transcript.text.length; i++) {
            var transcriptItem = ev.video.transcript.text[i];
            if (ev.video.time > parseFloat(transcriptItem._start)
                && ev.video.time < parseFloat(transcriptItem._start) +
                                   parseFloat(transcriptItem._dur)) {
                for (var j = 0; j < model.countries.length; j++) {
                    var country = model.countries[j];
                    if (transcriptItem.__text.indexOf(country.name) > -1
                        || transcriptItem.__text.indexOf(country.demonym) > -1) {
                        movie.sendMessage('enterCountry', {
                            country: country.name
                        });
                    }
                    else {
                        movie.sendMessage('leaveCountry', {
                            country: country.name
                        });
                    }
                }
                var locationFound = false;
                for (var j = 0; j < model.cities.length; j++) {
                    var city = model.cities[j];
                    if (transcriptItem.__text.indexOf(city.name) > -1) {
                        movie.sendMessage('timeLineEventChanged', {
                            event: {
                                position: {
                                    x: city.x,
                                    y: city.y
                                }
                            }
                        });
                        locationFound = true;
                    }
                }
                for (var j = 0; j < model.locations.length; j++) {
                    var location = model.locations[j];
                    if (transcriptItem.__text.indexOf(location.name) > -1) {
                        movie.sendMessage('timeLineEventChanged', {
                            event: {
                                position: {
                                    x: location.x,
                                    y: location.y
                                }
                            }
                        });
                        locationFound = true;
                    }
                }
                if (!locationFound) {
                    movie.sendMessage('timeLineEventChanged', { event: {} });
                }
                break;
            }
        }
    }
}.bind(this);

Final Considerations

That is it! I was happy to work on a project that deals not only with technology but also history topics. As a history geek (with little knowledge on the Great War), I feel it was more exciting to combine the subjects I'm learning together (programming and history) than to approach technology just for the sake of technology.

I hope you enjoyed both the article and the attached application code. If you like it, post a comment below, and if you feel it might be useful for your friends and colleagues, please don't forget to share it on Facebook, Twitter, Linked In and other social media.

History

  • 7th July, 2016: First version
  • 8th July, 2016: Download instructions
  • 15th July, 2016: Online demo
  • 4th August, 2016: Fixed Linq query
  • 5th August, 2016: Transcript lines explained

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


Written By
Instructor / Trainer Alura Cursos Online
Brazil Brazil

Comments and Discussions

 
GeneralMy vote of 5 Pin
Ehsan Sajjad12-Aug-16 1:12
professionalEhsan Sajjad12-Aug-16 1:12 
GeneralMy vote of 5 Pin
MohamedKamalPharm6-Aug-16 23:31
MohamedKamalPharm6-Aug-16 23:31 
PraiseMy vote of 5 Pin
Avelino Ferreira6-Aug-16 5:04
professionalAvelino Ferreira6-Aug-16 5:04 
GeneralRe: My vote of 5 Pin
Marcelo Ricardo de Oliveira6-Aug-16 6:43
mvaMarcelo Ricardo de Oliveira6-Aug-16 6:43 
Praisevery nice Pin
BillW335-Aug-16 7:17
professionalBillW335-Aug-16 7:17 
GeneralRe: very nice Pin
Marcelo Ricardo de Oliveira5-Aug-16 10:20
mvaMarcelo Ricardo de Oliveira5-Aug-16 10:20 
SuggestionLinq Query Pin
VMAtm4-Aug-16 4:08
VMAtm4-Aug-16 4:08 
PraiseRe: Linq Query Pin
Marcelo Ricardo de Oliveira4-Aug-16 6:34
mvaMarcelo Ricardo de Oliveira4-Aug-16 6:34 
QuestionSVG extraction. Pin
mbb0128-Jul-16 22:03
mbb0128-Jul-16 22:03 
QuestionThere he is Pin
Sacha Barber15-Jul-16 4:40
Sacha Barber15-Jul-16 4:40 
AnswerRe: There he is Pin
Marcelo Ricardo de Oliveira15-Jul-16 5:10
mvaMarcelo Ricardo de Oliveira15-Jul-16 5:10 
GeneralMy vote of 5 Pin
darkliahos15-Jul-16 2:02
darkliahos15-Jul-16 2:02 
GeneralRe: My vote of 5 Pin
Marcelo Ricardo de Oliveira15-Jul-16 5:09
mvaMarcelo Ricardo de Oliveira15-Jul-16 5:09 
GeneralRe: My vote of 5 Pin
Marcelo Ricardo de Oliveira16-Jul-16 5:17
mvaMarcelo Ricardo de Oliveira16-Jul-16 5:17 
GeneralRe: My vote of 5 Pin
darkliahos9-Aug-16 4:09
darkliahos9-Aug-16 4:09 
GeneralI like it. Pin
Stephen Gonzalez12-Jul-16 9:30
Stephen Gonzalez12-Jul-16 9:30 
GeneralRe: I like it. Pin
Marcelo Ricardo de Oliveira15-Jul-16 5:11
mvaMarcelo Ricardo de Oliveira15-Jul-16 5:11 
Praise¡Magnífico trabalho, parabéns! Pin
Jimmy_Olano8-Jul-16 10:22
Jimmy_Olano8-Jul-16 10:22 
GeneralRe: ¡Magnífico trabalho, parabéns! Pin
Marcelo Ricardo de Oliveira8-Jul-16 10:35
mvaMarcelo Ricardo de Oliveira8-Jul-16 10:35 
QuestionWas it supposed to work 'out of the box'? Pin
kalberts8-Jul-16 2:54
kalberts8-Jul-16 2:54 
AnswerRe: Was it supposed to work 'out of the box'? Pin
Marcelo Ricardo de Oliveira8-Jul-16 5:52
mvaMarcelo Ricardo de Oliveira8-Jul-16 5:52 
Sorry for the inconvenience, my fault. I should have made it clear for readers to open it as a Web Site in Visual Studio.

I've just update the article, check it out.

Thanks a lot!
Want to hire me for a freelance development? Send me a private message.

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.