Keeping Angular controllers complexity and size under control by using plain JavaScript widgets

Another problem I found while working on a legacy Angular application last year, was huge controllers with several hundreds of lines.

Most of those controllers contained a lot of procedural code and were doing too much. This made them very hard to test.

In the new Angular application we're currently working on, we're refactoring very aggressively to keep the size of our controllers small.

Apart from the strategy I talked about in a previous post, another technique that is giving us good results is extracting as much logic and state as possible from the controllers by moving related state and logic into small plain JavaScript objects that we call widgets.

This has had a huge impact in the testability of the code and helped us to keep the controllers size and complexity small.

Now I'll show you the results of one of this refactors, so that you can see its impact in a controller.

This is the first working version of a controller that is coordinating the behavior and content of a page showing details about a track. This page contains a map (using OpenLayers) with the polyline of the track on it, some statistics about the track and several charts (plotted using flot library)) to present some data from the track. It's possible to interact with these charts by changing the magnitude represented in their x axis (it can be distance or time):

	"use strict";
	app.controller('TrackDetailsPageController', [
	'$scope',
	'$routeParams',
	'Track',
	'trackStatisticsToDisplay',
	'Charts',
	'trackMap',
	'Categories',
	function ($scope, $routeParams, Track, trackStatisticsToDisplay, Charts, trackMap, Categories) {
	$scope.xAxis = Charts.defaultXAxis;
	$scope.options = {};
	$scope.chartTypes = Charts.defaultChartTypes;
	$scope.ChartDescriptions = Charts.descriptions;
	$scope.xAxisInDistanceUnits = function () {
	$scope.xAxis = Charts.xAxisInDistanceUnits;
	};
	$scope.xAxisInTimeUnits = function () {
	$scope.xAxis = Charts.xAxisInTimeUnits;
	};
	$scope.hasXAxisDistanceUnits = function () {
	return $scope.xAxis === Charts.xAxisInDistanceUnits;
	};
	$scope.hasXAxisTimeUnits = function () {
	return $scope.xAxis === Charts.xAxisInTimeUnits;
	};
	$scope.yUnits = function (chartType) {
	if ($scope.yUnitsByChartType) {
	return $scope.yUnitsByChartType[chartType];
	}
	};
	$scope.xUnits = function (chartType) {
	if ($scope.xUnitsByChartType) {
	return $scope.xUnitsByChartType[chartType]();
	}
	};
	$scope.track = Track.get({
	track_slug: $routeParams.track_slug
	},
	function (track) {
	$scope.groupedStatistics = trackStatisticsToDisplay.create(
	track.getStatistics()
	);
	var source = trackMap.getTrackPolylineSource(
	track.getUrl()
	);
	$scope.xUnitsByChartType = _.reduce(
	$scope.chartTypes,
	function (acc, chartType) {
	var scope = $scope;
	acc[chartType] = function () {
	return track.getXAxisUnits(chartType, scope.xAxis);
	};
	return acc;
	},
	{}
	);
	$scope.yUnitsByChartType = _.reduce(
	$scope.chartTypes,
	function (acc, chartType) {
	acc[chartType] = track.getYAxisUnits(chartType);
	return acc;
	},
	{}
	);
	source.once('change',
	function () {
	trackMap.addTrackPolylineToMap(
	$scope.routeMapInstance,
	source
	);
	}
	);
	}
	);
	$scope.getSportIconCssClass = function (category) {
	if (!category) {
	category = 'common.all_sports';
	}
	return 'svg-' + Categories.getSportIconCssClass(category);
	}
	$scope.$on('OLMaps:created', function (event, mapInstance) {
	if (mapInstance.key) {
	$scope[mapInstance.key] = mapInstance.map;
	}
	});
	}
	]);

view raw TrackDetailsPageController.js hosted with ❤ by GitHub

Notice how there are a lot of functions in the scope which are managing the state of the xAxis variable and getting information about the charts (x and y axis units, selected magnitude for x axis).

We had also this directive for the charts:

	app.directive('flotChart', [
	'$window',
	'Charts',
	'NumbersWithFixedDecimals',
	function ($window, Charts, NumbersWithFixedDecimals) {
	return {
	restrict: 'AE',
	scope: {
	data: '=flotData',
	graphicType: '=graphicType',
	options: '=flotOptions',
	plothover: '&plotHover',
	plotclick: '&plotClick',
	xAxis: '=xAxis'
	},
	link: function (scope, element, attr) {
	var plot = $.plot($(element), getPoints(), getOptions());
	$(element).bind('plothover', function (event, position, item) {
	scope.plothover({
	event: event,
	position: position,
	item: item
	});
	});
	$(element).bind('plotclick', function (event, position, item) {
	scope.plotclick({
	event: event,
	position: position,
	item: item
	});
	});
	scope.$watch('data', function (newVal, oldVal) {
	drawGraphics();
	}, true);
	scope.$watch('options', function (newVal, oldVal) {
	plot = $.plot($(element), getPoints(), getOptions());
	}, true);
	scope.$watch('xAxis', function (newVal, oldVal) {
	drawGraphics();
	});
	angular.element($window).bind('resize', function() {
	plot = $.plot($(element), getPoints(), getOptions());
	});
	function drawGraphics() {
	plot.setData(getPoints());
	plot.setupGrid();
	plot.draw();
	}
	function getPoints() {
	var roundNumberToTwoDecimals = NumbersWithFixedDecimals.toDecimals(2).round;
	if (!scope.data.$resolved) {
	return {
	data: []
	};
	}
	return [
	{
	data: roundCoordinatesToTwoDecimals(
	scope.data.graphics.data[scope.graphicType][scope.xAxis]
	)
	}
	];
	function roundCoordinatesToTwoDecimals(points) {
	return _.map(
	points,
	function (point) {
	return [
	roundNumberToTwoDecimals(point[0]),
	roundNumberToTwoDecimals(point[1])
	];
	}
	);
	}
	}
	function getOptions() {
	return _.extend(Charts.defaultOptions, scope.options);
	}
	}
	};
	}
	]);

view raw ChartsDirective.js hosted with ❤ by GitHub

which was being passed the selected x axis magnitude and the charts data.

We got to this version of the code after several design changes and quick spikes. Once we were happy with the UI behavior, it was time to stabilize it.

To do it we created a widget in an Angular factory which was a plain JavaScript object in charge of managing the state related to the charts (xAxis variable which was being read and mutated) and accessing the charts data (which were only being read):

	app.factory('chartsWidgetFactory', [
	'Charts',
	'chartPoints',
	function (Charts, chartPoints) {
	var trackWithCharts,
	chartTypesInTrack,
	chartTypes,
	xUnitsByChartType,
	yUnitsByChartType,
	chartOptions;
	return {
	create: function (track, options) {
	trackWithCharts = track;
	chartOptions = options || {};
	chartTypesInTrack = track.getChartsKeys();
	chartTypes = _.filter(
	Charts.defaultChartTypes,
	function (chartType) {
	return _.contains(chartTypesInTrack, chartType);
	}
	);
	xUnitsByChartType = _.reduce(
	chartTypes,
	function (acc, chartType) {
	acc[chartType] = function (xAxis) {
	return track.getXAxisUnits(chartType, xAxis);
	};
	return acc;
	},
	{}
	);
	yUnitsByChartType = _.reduce(
	chartTypes,
	function (acc, chartType) {
	acc[chartType] = track.getYAxisUnits(chartType);
	return acc;
	},
	{}
	);
	return {
	types: chartTypes,
	yUnits: function (chartType) {
	return yUnitsByChartType[chartType];
	},
	xUnits: function (chartType) {
	return xUnitsByChartType[chartType](this.xAxis);
	},
	xAxis: Charts.defaultXAxis,
	xAxisInDistanceUnits: function () {
	this.xAxis = Charts.xAxisInDistanceUnits;
	},
	xAxisInTimeUnits: function () {
	this.xAxis = Charts.xAxisInTimeUnits;
	},
	hasXAxisDistanceUnits: function () {
	return this.xAxis === Charts.xAxisInDistanceUnits;
	},
	hasXAxisTimeUnits: function () {
	return this.xAxis === Charts.xAxisInTimeUnits;
	},
	descriptionFor: function (chartType) {
	return Charts.descriptions[chartType];
	},
	options: chartOptions,
	extractPointsFor: function (chartType) {
	return chartPoints.extractFrom(track, chartType, this.xAxis);
	},
	track: track
	};
	}
	};
	}
	]);

view raw chartsWidget.js hosted with ❤ by GitHub

Notice how the widget is created by passing the track to the create method. This method initializes some values and returns the charts widget which has privileged access through a closure to several private functions and data.

We basically moved all the functions related to the charts that were before in the controller into the new widget and made some of them private.

After being moved to the widget, the logic controlling the charts became very easy to test using fake tracks:

	"use strict";
	describe("chartsWidgetFactory", function () {
	var chartData = {
	speed_graphics: {
	units: {
	distance: "km",
	speed: "km/h",
	time: "min"
	},
	with_respect_to_distance: [
	],
	with_respect_to_time: [
	]
	},
	elevations_graphics: {
	units: {
	distance: "km",
	elevation: "m",
	time: "min"
	},
	with_respect_to_distance: [
	],
	with_respect_to_time: [
	]
	}
	},
	fakeTrackWithCharts = {
	graphics: {
	data: chartData
	}
	},
	chartsWidgetFactory,
	chartPoints,
	trackMethods,
	charts;
	beforeEach(module("agora"));
	beforeEach(function () {
	module(function ($provide) {
	$provide.constant('Charts', {
	'defaultOptions': {
	},
	'descriptions': {
	'elevations_graphics': 'charts.elevations_graphics',
	'speed_graphics': 'charts.speed_graphics'
	},
	defaultXAxis: 'with_respect_to_distance',
	defaultChartTypes: [
	'elevations_graphics',
	'speed_graphics',
	'blabla1_graphics_that_it_is_not_in_track',
	'blabla2_graphics_that_it_is_not_in_track'
	],
	xAxisInDistanceUnits: "with_respect_to_distance",
	xAxisInTimeUnits: "with_respect_to_time"
	});
	});
	});
	beforeEach(
	inject(function (_chartsWidgetFactory_, _chartPoints_, _trackMethods_) {
	chartsWidgetFactory = _chartsWidgetFactory_;
	chartPoints = _chartPoints_;
	trackMethods = _trackMethods_;
	_.extend(fakeTrackWithCharts, trackMethods);
	charts = chartsWidgetFactory.create(fakeTrackWithCharts);
	})
	);
	it("initializes its xAxis property with the value of Charts.defaultXAxis",
	inject(function (Charts) {
	expect(charts.xAxis).toBe(Charts.defaultXAxis);
	})
	);
	it("initializes the chart types to only those chart types from Charts.defaultChartTypes " +
	"that are included in the track charts", function () {
	expect(charts.types).toEqual([
	'elevations_graphics',
	'speed_graphics'
	]);
	});
	it("gets the y axis units of a given chart", function () {
	expect(charts.yUnits('speed_graphics')).toBe('km/h');
	expect(charts.yUnits('elevations_graphics')).toBe('m');
	});
	it("gets the x axis units of a given chart by delegating on track " +
	"(which is augmented with trackMethods)",
	inject(function (Charts) {
	spyOn(fakeTrackWithCharts, "getXAxisUnits");
	charts.xUnits('elevations_graphics');
	expect(fakeTrackWithCharts.getXAxisUnits)
	.toHaveBeenCalledWith(
	'elevations_graphics',
	Charts.defaultXAxis
	);
	})
	);
	it("can set the x axis property of the charts",
	inject(function (Charts) {
	expect(charts.xAxis).toBe(Charts.defaultXAxis);
	charts.xAxisInTimeUnits();
	expect(charts.xAxis).toBe(Charts.xAxisInTimeUnits);
	charts.xAxisInDistanceUnits();
	expect(charts.xAxis).toBe(Charts.xAxisInDistanceUnits);
	})
	);
	it("has queries for the value of the x axis property of the charts", function () {
	charts.xAxisInTimeUnits();
	expect(charts.hasXAxisTimeUnits()).toBeTruthy();
	expect(charts.hasXAxisDistanceUnits()).toBeFalsy();
	charts.xAxisInDistanceUnits();
	expect(charts.hasXAxisTimeUnits()).toBeFalsy();
	expect(charts.hasXAxisDistanceUnits()).toBeTruthy();
	});
	it("gets the description of a given chart type",
	inject(function (Charts) {
	_.each(
	charts.types,
	function (chartType) {
	expect(charts.descriptionFor(chartType))
	.toBe(Charts.descriptions[chartType])
	}
	);
	})
	);
	it("delegates on chartPoints to extract the points of a given chart",
	inject(function (Charts) {
	spyOn(chartPoints, "extractFrom");
	charts.extractPointsFor('speed_graphics');
	expect(chartPoints.extractFrom)
	.toHaveBeenCalledWith(
	fakeTrackWithCharts,
	'speed_graphics',
	Charts.defaultXAxis
	);
	})
	);
	it("can initialize the charts options with a given object", function () {
	var someArbitraryOptions = {
	whateverOption: "whatever"
	},
	otherCharts = chartsWidgetFactory.create(
	fakeTrackWithCharts, someArbitraryOptions
	);
	expect(otherCharts.options).toEqual(someArbitraryOptions);
	});
	it("initializes the charts options to an empty object when no options are passed", function () {
	expect(charts.options).toEqual({});
	});
	});

view raw chartsWidgetSpec.js hosted with ❤ by GitHub

After this change the controller was reduced to this:

	"use strict";
	app.controller('TrackDetailsPageController', [
	'$scope',
	'$routeParams',
	'Track',
	'trackStatisticsToDisplay',
	'trackMap',
	'Categories',
	'chartsWidgetFactory',
	function ($scope, $routeParams, Track, trackStatisticsToDisplay, trackMap, Categories, chartsWidgetFactory) {
	$scope.track = Track.get({
	track_slug: $routeParams.track_slug
	},
	function (track) {
	$scope.groupedStatistics = trackStatisticsToDisplay.create(
	track.getStatistics()
	);
	var source = trackMap.getTrackPolylineSource(
	track.getUrl()
	);
	source.once('change',
	function () {
	trackMap.addTrackPolylineToMap(
	$scope.routeMapInstance,
	source
	);
	}
	);
	$scope.charts = chartsWidgetFactory.create(track);
	}
	);
	$scope.getSportIconCssClass = function (category) {
	if (!category) {
	category = 'common.all_sports';
	}
	return 'svg-' + Categories.getSportIconCssClass(category);
	};
	$scope.$on('OLMaps:created', function (event, mapInstance) {
	if (mapInstance.key) {
	$scope[mapInstance.key] = mapInstance.map;
	}
	});
	}
	]);

view raw TrackDetailsPageControllerWithChartExtracted.js hosted with ❤ by GitHub

Notice how all the chart-managing logic has disappeared from the controller. The only code related to the chart that remains is its creation.

We were also able to simplify the code of the directive by just passing it the new widget:

	"use strict";
	app.directive('flotChart', [
	'$window',
	'Charts',
	function ($window, Charts) {
	return {
	restrict: 'AE',
	scope: {
	graphicType: '=graphicType',
	plothover: '&plotHover',
	plotclick: '&plotClick',
	charts: '=charts'
	},
	link: function (scope, element, attr) {
	var plot = $.plot($(element), getPoints(), getOptions());
	$(element).bind('plothover', function (event, position, item) {
	scope.plothover({
	event: event,
	position: position,
	item: item
	});
	});
	$(element).bind('plotclick', function (event, position, item) {
	scope.plotclick({
	event: event,
	position: position,
	item: item
	});
	});
	scope.$watch('charts.track', function (newVal, oldVal) {
	drawGraphics();
	}, true);
	scope.$watch('charts.options', function (newVal, oldVal) {
	plot = $.plot($(element), getPoints(), getOptions());
	}, true);
	scope.$watch('charts.xAxis', function (newVal, oldVal) {
	drawGraphics();
	});
	angular.element($window).bind('resize', function() {
	plot = $.plot($(element), getPoints(), getOptions());
	});
	function drawGraphics() {
	plot.setData(getPoints());
	plot.setupGrid();
	plot.draw();
	}
	function getPoints() {
	if (!scope.charts.track.$resolved) {
	return {
	data: []
	};
	}
	return [
	{
	data: scope.charts.extractPointsFor(scope.graphicType)
	}
	];
	}
	function getOptions() {
	return _.extend(Charts.defaultOptions, scope.options);
	}
	}
	};
	}
	]);

view raw SimplifiedChartsDirective.js hosted with ❤ by GitHub

Notice how the widget has also absorbed the code that produced the points in the chart.

We have continued refactoring this controller and others in the same way. Making small refactors every time we detected duplication or discovered new concepts that could help us extract behavior from them.

This is the current code of the controller that we've been showing in this example:

	"use strict";
	app.controller('TrackDetailsPageController', [
	'$scope',
	'$routeParams',
	'trackStatisticsToDisplay',
	'trackMap',
	'chartsWidgetFactory',
	'tracksRepository',
	'CategoriesIcons',
	function ($scope, $routeParams, trackStatisticsToDisplay, trackMap, chartsWidgetFactory, tracksRepository, CategoriesIcons) {
	$scope.track = tracksRepository.getTrack(
	$routeParams.track_slug,
	function (track) {
	$scope.groupedStatistics = trackStatisticsToDisplay.create(
	track.getStatistics()
	);
	var source = trackMap.getTrackPolylineSource(track);
	source.once('change',
	function () {
	trackMap.addTrackPolylineToMap(
	$scope.routeMapInstance,
	source
	);
	}
	);
	$scope.charts = chartsWidgetFactory.create(track);
	}
	);
	$scope.CategoriesIcons = CategoriesIcons;
	$scope.$on('OLMaps:created', function (event, mapInstance) {
	if (mapInstance.key) {
	$scope[mapInstance.key] = mapInstance.map;
	}
	});
	}
	]);

view raw currentTrackDetailsPageController.js hosted with ❤ by GitHub

Keeping Angular controllers complexity and size under control is a constant effort that, having seen in other projects the negative effects of huge controllers, I think it's totally worth it.