Now with Partition Management
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

citycontext-ui

1.1.1 • Public • Published

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-ui

Require citycontext-ui in your script

// main.js
var citycontext = require('citycontext-ui');

Browserify it:

browserify main.js -o bundle.js

Programmatic 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 css

citycontext-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

Keywords

none

install

npm i citycontext-ui

Downloadsweekly downloads

1

version

1.1.1

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar