Quinoa vis modules - unified react component for displaying controlled visualizations
Quinoa vis module exposes a set of scripts aimed at being used in quinoa applications.
These scripts are of two types :
- a set of React components displaying a visualization for which the whole state is controlled declaratively, exposing a consistent API despite the difference of data structures and visualization parameters
- a set of parsing and mapping scripts aimed at manipulating data according to a specific visualization type
Components are stateful, because they can temporarily have an inner state different from the one provided in their props, in order to allow application-state-independent navigation behaviors in the vis.
Installation as a dependency
npm install --save https://github.com/medialab/quinoa-vis-modules
Installation for development
git clone https://github.com/medialab/quinoa-vis-modules
cd quinoa-vis-modules
npm install
npm run build-storybook
Development
The project uses storybook to visually test the possible implementations of the component.
npm run storybook
Npm Scripts
build
: builds dist code for use as dependency
lint
: lints the code (autofix on)
comb
: prettifies scss code
test
: run mocha unit tests on all .spec.js
prefixed files present in src
build-storybook
: builds storybook static assets
storybook
: runs a visual testing environment accessible at localhost:6006
precommit-add-build
: as the project uses a pre-commit hook to enforce code quality at each commit, each successful commit automatically adds the build directory
Module general structure and API
Module submodules
;
Examples of use of the components
Each component receives a declarative description of the state it has to render, plus some callbacks, like so:
const MyTimelineContainer = <div className="my-timeline-container"> <Timeline data=timelineData allowUserViewChange =true onUserViewChange= console viewParameters = fromDate: toDate: orientation: 'portrait' colorsMap: main: cartography: '#F24D98' computation: '#813B7C' mathematics: '#59D044' statistics: '#F3A002' /> </div>
See the story book for more examples of use.
Data formatting needs
The data provided to components must always be an object in which each property represents a collection of the data to represent.
For now, timeline and map require both a single-collection dataset, that is to be provided with an object containing a property main
containing the data as an array of js objects.
Example of data readable by a timeline :
"main": "title": "Event title" "description": "Event description" "source": "Event source" "category": "computation" "startDate": "1943-12-31T23:00:00.335Z" // ...
Network requires a two-collections dataset, made of a nodes
collection and an edges
collection.
"nodes": "id": "229" "x": -3886054 "y": -7056831 "size": 36082125 "label": "Amérique Du Sud" "category": "rgb(255,51,51)" // ... "edges": "id": "5720" "type": "undirected" "label": "" "source": "229" "target": "964" "weight": 1 // ..
API
Each quinoa-vis-module component must comply to the following API :
Variable props :
data
: ready-to-use data to visualizeallowUserViewChange
: boolean to specify whether the user can pan/zoom/interact with the view or notviewParameters
: object describing the current view of the visualization - the shape of this object depends on the visualization type
Method props :
onUserViewChange
: returns data about the triggering interaction and the new view representation
viewParameters
prop
Common proporties of the The viewParameters
must contain all the parameters necessary to render successfully a view of the visualization. The particular structures of the viewParameters
of each component is detailed below, but all viewParameters
props share some following subprop :
colorsMap
: object that specifies how to color objects. First-level keys correspond to data's collections names. Second-level keys are values to look for in a categorical set of values present in objects' data, value are css color descriptions (therefore accepted methods : names, rgb, rgba, hex)dataMap
: object that specifies how to interpret's data points' properties in order to populate the visualization. First-level keys correspond to data's collections names. Second-level keys correspond to a visualization's parameter, the value pointing to datapoints' properties names to use for populating the visualization.showCategories
: object that specifies how to visually filter objects. First-level keys correspond to data's collections names. Each of them contains an array of strings corresponding the categories to show.
viewParameters
property models
visualization-specific Timeline
Example of a viewParameters object for the Timeline component:
const timelineBaseViewParameters = fromDate: toDate: colorsMap: main: cartography: '#F24D98' computation: '#813B7C' mathematics: '#59D044' statistics: '#F3A002' default: 'lightgrey' default: 'lightgrey' shownCategories: main: 'computation' ;
fromDate
: date||number
Start date to use fo displayingr the main view of the timeline.
toDate
: date||number
End date to use for displaying the main view of the timeline.
Map
Example of a viewParameters object for the Map component:
const mapBaseViewParameters = cameraX: 488674345 cameraY: 23455482 cameraZoom: 4 colorsMap: main: 'accélérée': '#F24D98' 'normale': '#813B7C' default: 'lightgrey' default: 'lightgrey' tilesUrl: 'http://{s}.tile.stamen.com/toner/{z}/{x}/{y}.png';
cameraX
: number
Longitude coordinate of the camera center
cameraY
: number
Latitude coordinate of the camera center
cameraZoom
: number
Zoom degree of the camera (1 corresponds to the farthest position of camera)
tilesUrl
: string
Url pattern to use in order to retrieve map tiles.
Network
Example of a viewParameters object for the Network component:
const networkJSONBaseViewParameters = cameraX: 0 cameraY: 0 cameraRatio: 2 cameraAngle: 0 labelThreshold: 7 minNodeSize: 2 sideMargin: 0 colorsMap: nodes: 1: '#813B7C' 2: '#41d9f4' 3: '#64f441' default: '#F24D98' edges: default: '#c0c6c6' default: '#c0c6c6' ;
cameraX
: number
Describes the camera center
cameraY
: number
Describes the camera center
cameraRatio
: number
Zoom degree of the camera.
cameraAngle
: number
Rotation angle of the camera.
labelThreshold
: number
Zoom level starting from which labels can be displayed.
minNodeSize
: number
Minimum size of network nodes.
sideMargin
: number
The margin (in pixels) to keep around the graph.
Pre-commit hook
The project uses a precommit hook before each commit to ensure the code remains clean at all times. Check out the package.json
to learn more about it.