wc-byor

v1.1.0

Published

a year ago

[![Thoughtworks](https://circleci.com/gh/thoughtworks/build-your-own-radar.svg?style=shield)](https://circleci.com/gh/thoughtworks/build-your-own-radar) [![Stars](https://badgen.net/github/stars/thoughtworks/build-your-own-radar)](https://github.com/thoug

Downloads

0High
0Medium
0Low

matkainer

tech-radar

A library that generates an interactive radar, inspired by thoughtworks.com/radar.

Difference to original radar

The original radar has an isNew column. This radar has a context column, that will create a second line of buttons, allowing you to filter for specific context items. While the filter is active, the other elements are greyed out.

The default dockerfile is running the radar as an http server, not as a webpack dev environment. To run that, build the Dockerfile.dev. The docker image mkainer/build-your-own-radar available on dockerhub uses the static server, NOT the development image.

In the CSV file, one can use #!includes UrlToFile.csv references to split up the csv file.

This version also exposes the technology radar as web-component, and be used inside an existing page like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Home</title>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <script type="module" src="https://unpkg.com/wc-byor"></script>
  </head>
  <body>
    <nav>
      <a href="/" aria-current="page">Home</a>
      <a href="/other.html">Other page</a>
    </nav>
    <main>
      <h1>Your radar</h1>
      <technology-radar
        source="https://location.of/your.csv"
        stylesheet="https://location.of/your.css"
        ></technology-radar>
    </main>
  </body>
</html>

Demo

You can see this in action at https://radar.thoughtworks.com. If you plug in this data you'll see this visualization.

How To Use

The easiest way to use the app out of the box is to provide a public Google Sheet ID from which all the data will be fetched. You can enter that ID into the input field, sign in to Google using the prompt and your radar will be generated. The data must conform to the format below for the radar to be generated correctly.

Setting up your data

You need to make your data public in a form we can digest.

Create a Google Sheet. Give it at least the below column headers, and put in the content that you want:

| name | ring | quadrant | context | description | | ------------- | ------ | ---------------------- | -------- | ------------------------------------------------------- | | Composer | adopt | tools | Software | Although the idea of dependency management ... | | Canary builds | trial | techniques | DevOps | Many projects have external code dependencies ... | | Apache Kylin | assess | platforms | Data | Apache Kylin is an open source analytics solution ... | | JSF | hold | languages & frameworks | Software | We continue to see teams run into trouble using JSF ... |

Sharing the sheet

In Google sheets, go to 'File', choose 'Publish to the web...' and then click 'Publish'.
Close the 'Publish to the web' dialog.
Copy the URL of your editable sheet from the browser (Don't worry, this does not share the editable version).

The URL will be similar to https://docs.google.com/spreadsheets/d/1waDG0_W3-yNiAaUfxcZhTKvl7AUCgXwQw8mdPjCz86U/edit. In theory we are only interested in the part between '/d/' and '/edit' but you can use the whole URL if you want.

Using CSV data

The other way to provide your data is using CSV document format. You can enter any URL that responds CSV data into the input field on the first page. The format is just the same as that of the Google Sheet, the example is as follows:

name,ring,quadrant,context,description
Composer,adopt,tools,Software,"Although the idea of dependency management ..."
Canary builds,trial,techniques,DevOps,"Many projects have external code dependencies ..."
Apache Kylin,assess,platforms,Data,"Apache Kylin is an open source analytics solution ..."
JSF,hold,languages & frameworks,Software,"We continue to see teams run into trouble using JSF ..."

Note: The CSV file parsing is using D3 library, so consult the D3 documentation for the data format details.

Using JSON data

Another other way to provide your data is using a JSON array. You can enter any URL that responds JSON data into the input field on the first page. The format of the JSON is an array of objects with the the fields: name, ring, quadrant, isNew, and description.

An example:

[
  {
    "name": "Composer",
    "ring": "adopt",
    "quadrant": "tools",
    "context": "Software",
    "description": "Although the idea of dependency management ..."
  },
  {
    "name": "Canary builds",
    "ring": "trial",
    "quadrant": "techniques",
    "context": "DevOps",
    "description": "Many projects have external code dependencies ..."
  },
  {
    "name": "Apache Kylin",
    "ring": "assess",
    "quadrant": "platforms",
    "context": "Data",
    "description": "Apache Kylin is an open source analytics solution ..."
  },
  {
    "name": "JSF",
    "ring": "hold",
    "quadrant": "languages & frameworks",
    "context": "Software",
    "description": "We continue to see teams run into trouble using JSF ..."
  }
]

Note: The JSON file parsing is using D3 library, so consult the D3 documentation for the data format details.

Building the radar

Paste the URL in the input field on the home page.

That's it!

Note: The quadrants of the radar, and the order of the rings inside the radar will be drawn in the order they appear in your data.

Check this page for step by step guidance.

More complex usage

To create the data representation, you can use the Google Sheet factory or CSV, or you can also insert all your data straight into the code.

The app uses Google Sheets APIs to fetch the data from a Google Sheet or D3.js if supplied as CSV, so refer to their documentation for more advanced interaction. The input data is sanitized by whitelisting HTML tags with sanitize-html.

The application uses webpack to package dependencies and minify all .js and .scss files.

By default, there is no distinction between both public and private Google Sheets as we now require authentication from Google (using OAuth Client ID and optionally, API Key), per Google's updated documentation. OAuth Client ID and API Key can be obtained from your Google developer console.

export CLIENT_ID=[Google Client ID]

Optionally, API Key can be set to bypass Google Authentication for public sheets.

export API_KEY=[Google API Key]

To enable Google Tag Manager, add the following environment variable.

export GTM_ID=[GTM ID]

Docker Image

We have released BYOR as a docker image for our users. The image is available in our DockerHub Repo. To pull and run the image, run the following commands.

$ docker pull wwwthoughtworks/build-your-own-radar
$ docker run --rm -p 8080:8080 -e CLIENT_ID="[Google Client ID]" wwwthoughtworks/build-your-own-radar
$ open http://localhost:8080

Notes:

Currently, the docker image will run the server as a dev server. Refer to the dockerfile in this repo for more details.
If API Key is also available, same can be provided to the docker run command as -e API_KEY=[Google API Key].

Contribute

All tasks are defined in package.json.

Pull requests are welcome; please write tests whenever possible. Make sure you have nodejs installed.

git clone [email protected]:thoughtworks/build-your-own-radar.git
npm install
npm quality:nonstrict - to run your tests
npm run dev - to run application in localhost:8080. This will watch the .js and .css files and rebuild on file changes

End to End Tests

To run End to End tests in headless mode

add a new environment variable 'TEST_URL' and set it to 'http://localhost:8080/'
npm run test:e2e

To run End to End tests in debug mode

add a new environment variable 'TEST_URL' and set it to 'http://localhost:8080/'
npm run start
Click on 'Run all specs' in cypress window

Note: Currently, end to end tests are not working, as the flow requires Google login via prompt, which Cypress does not support. We are working to find some alternative solution for this.

Don't want to install node? Run with one line docker

 $ docker run -p 8080:8080 -v $PWD:/app -w /app -it node:10.15.3 /bin/sh -c 'npm install && npm run dev'

Note: If you are facing Node-sass compile error while running, please prefix the command npm rebuild node-sass before npm run dev. like this

npm install && npm rebuild node-sass && npm run dev

After building it will start on localhost:8080