Overview
This library allows you to add City Context widgets to your web page in a couple of lines, while allowing you to somewhat customize their appearance, and feed them with data coming from sources different from the text input.
Examples
The following widgets are available:
Quick start
Include City Context scripts and stylesheets in your HTML header tag:
<link href="http://assets.citycontext.com/citycontext-ui.min.css" rel="stylesheet" type="text/css">
<script src="http://assets.citycontext.com/citycontext-ui.min.js"></script>
<!-- If you are using Mapbox, add the stylesheet below as well -->
<link href='https://api.tiles.mapbox.com/mapbox.js/v2.1.5/mapbox.css' rel='stylesheet' />Then add the free user key that you got from signing up on City Context.
<body>
...
<script>
citycontext.config.userKey = 'my-citycontext-user-key';
// In addition, if you want to display a map from Mapbox,
// You can optionally do so by providing you mapbox credentials
citycontext.config.mapboxMapId = 'my-mapbox-map-id';
citycontext.config.mapboxToken = 'my-mapbox-token';
</script>
</body>To render the widget you need (either TransportWidget, CriminalityWidget, SchoolsWidget, FloodWidget or DemographicsWidget):
<body>
...
<div id="criminality-widget"></div>
...
<script>
...
citycontext.CriminalityWidget('#criminality-widget').render();
</script>
</body>Full example:
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'></meta>
<link href="http://assets.citycontext.com/citycontext-ui.min.css" rel="stylesheet" type="text/css">
<script src="http://assets.citycontext.com/citycontext-ui.min.js"></script>
<!-- If you are using Mapbox, add the stylesheet below as well -->
<link href='https://api.tiles.mapbox.com/mapbox.js/v2.1.5/mapbox.css' rel='stylesheet' />
</head>
<body>
...
<div id="criminality-widget"></div>
...
<script>
citycontext.config.userKey = 'my-citycontext-user-key';
// In addition, if you want to display a map from Mapbox,
// You can optionally do so by providing you mapbox credentials
citycontext.config.mapboxMapId = 'my-mapbox-map-id';
citycontext.config.mapboxToken = 'my-mapbox-token';
citycontext.CriminalityWidget('#criminality-widget').render();
</script>
</body>
</html>Using Browserify
The recommended way to use citycontext-ui for a more complex project is through Browserify.
Install the citycontext-ui module and add it to dependencies in package.json:
npm install --save citycontext-uiRequire citycontext-ui in your script
// main.js
var citycontext = require('citycontext-ui');Browserify it:
browserify main.js -o bundle.jsProgrammatic usage
Most of the time, you won't want to use the provided text entry. Instead, you want to display a widget next to, say, a listing or an existing map. In that case, the point of interest won't be specified by the user input, but rather will come from elsewhere in the application.
First, when instantiating the widgets, let's hide the form:
var demographicsWidget = citycontext.DemographicsWidget('#demographics-widget', { displayForm: false }).render();Next, let's update it via a postcode query:
demographicsWidget.queryByPostcode('LS1 5ES');We can also query by a point, using its latitude and longitude:
demographicsWidget.queryByLatLon('53.477860,-2.261099');Alternatively, we can use data coming directly from the markup:
<div id="demographics-widget" data-postcode="LS1 5ES"></div><div id="schools-widget" data-latlon='53.477860,-2.261099'></div>Customizing the appearance
CSS
The best way to customize the CSS is to compile the stylesheets from the less folder of a cloned repo:
git clone https://github.com/citycontext/citycontext-ui
cd citycontext-ui
npm install
make csscitycontext-ui uses the less CSS preprocessor. The less folder relies on a number of variables that are found in the less/theme.less file. This could be a good first file to modify.
Javascript
The appearance can be further customized by configuring the widgets.
Schools
To fit you color scheme, the mapbox markers color can be customized:
var citycontext = require('citycontext-ui');
citycontext.mapMarkersColor: '#409840';
citycontext.SchoolsWidget('#schools-widget').render();Criminality
The criminality bar chart provides a period-by-period (month/quarter/year) comparison between the number of crimes during the last three years.
The colors of the bar for each year can be specified to match you color theme. Each color is represented by a [red, green, blue] triple.
var citycontext = require('citycontext-ui');
citycontext.criminalityGraph.barColorsRGBA: [
[64, 152, 63], // first year color
[63, 64, 152], // second year color
[152, 63, 64] // third year color
]
citycontext.CriminalityWidget('#criminality-widget').render();citycontext-ui relies on the Chart.js library to plot criminality statistics. All the global and bar chart-specific options that Chart.js uses can be specified to further customize the graph.
var citycontext = require('citycontext-ui');
citycontext.chartsOptions.global.showScale = false; // global option
citycontext.chartsOptions.Bar.barShowStroke = false; // bar chart-specific option
citycontext.CriminalityWidget('#criminality-widget').render();Hooking into events
The widgets trigger events that you can hook into, whenever someone submits a postcode, whenever the lookup succeeds and when it fails.
var citycontext = require('citycontext-ui');
citycontext.CriminalityWidget('#criminality-widget').render();
var widget = document.querySelector('#criminality-widget');
widget.addEventListener('citycontext-ui.submit', function(e) {
console.info("Query submitted: " + e.detail.input);
});
widget.addEventListener('citycontext-ui.success', function(e) {
console.info("Query succeeded: " + e.detail.input);
});
widget.addEventListener('citycontext-ui.error', function(e) {
console.error("Query failed for " + e.detail.input + ". Error: " + e.detail.error);
});Development
git clone https://github.com/citycontext/citycontext-ui
cd citycontext-ui
make