The Teach Viz by Example (TVBE) repository is a space for the data visualization teaching community to find, share, and contribute exemplary data visualizations and visualization-ready datasets. The site builds on Minicomp’s Wax project, a lightweight framework for digital exhibits built on Jekyll and GitHub Pages. This project extends Wax by including additional processing scripts, page layouts, and includes.
This project, and other work by the Visualizing the Future grant, was made possible in part by the Institute of Museum and Library Services, RE-73-18-0059-18.
-
Change directory into where you'd like your site, e.g., your Desktop:
cd ~/Desktop
-
Download the zip file from the Visualizing the Future github repository. The option to download the zip file should be on the button labeled "Code." Your browser will save the file where it normally saves downloads.
-
Move the zip file to the location you will use. In our example, to the Desktop.
-
Unzip the file. This can be done through your operating system graphic user interface, or in the terminal:
unzip examples-repository.zip
You can delete the zip file once you're done.
-
Go inside the project folder and install the gems:
bundle install
-
To check, see if you can run the demo site:
bundle exec jekyll serve
After the last step the terminal will provide you with a localhost URL for you to see your local copy of the site on your browser.
For general information about dependencies and installation for Wax, see the main Wax GitHub repository and wiki documentation.
Jekyll’s documentation includes information about setting up a local development environment for Jekyll site building.
The TVBE repository includes two data processing scripts: a tailored Google Apps Script that processes Google Form submissions into a series of separate sheets for separate collections, and a python script that processes the .csv files exported from Google Sheets into JSON metadata files read for Wax processing.
The examples hosted in this repository are submitted via a (currently in development) Google Form. The Google Form allows users to submit examples for our two primary collections (data visualizations and datasets) as well as other examples that may be related but fall outside those collections. The results from the Google Form must then be split into separate sheets for each collection. Additional processing helps prepare the data for Wax and adds support for multi-value fields, like “visualization type” and “audience level.” The script is specifically tailored to the fields and data values included in the Google Form for this project. This script is hosted in the Google Sheet produced by the Google Form and is run whenever a new example is submitted. The sheets produced by the script are then manually downloaded as .csv files, saved to the data-tools directory, and processed with the python script to produce JSON.
The Parse Google Sheet python script uses a delimiter added by the Google Apps Script (a “|” character) to identify multi-value fields in the .csv file. The script converts the .csv to JSON, processing multi-value fields into JSON arrays instead of strings. The JSON output from this script should be saved to the _data directory in preparation for the wax:pages rake task.
The TVBE also includes a data dictionary to supplement the metadata file used by Wax to generate item pages. In the original Wax project, a similar function is provided by adding metadata into an item layout, e.g., qatar_item.html. To reduce redundancy across collections and to make the same values available across multiple layouts, TVBE uses a centralized data dictionary approach.
The data dictionary is a YAML file placed in the _data directory that provides additional details about the different fields that can appear in collection items - for example, human-readable labels and details about the field type. To associate a collection with a data dictionary, edit the _config.yml file to add, e.g., dictionary: 'data_dictionary' under a collection. Currently, all collections use the same data dictionary, but each collection can be linked to its own data dictionary if needed.
The data dictionary can then be used in a page with code like the following:
{% assign col_metadata = site.collections | where: 'label', page.collection | first %}
{% assign dictionary = site.data[col_metadata.dictionary] %}
An example of a layout that uses the data dictionary is the gallery-page-multi-facet.html layout. The layout finds the dictionary associated with the specified collection, and for metadata fields specified as facets, the layout pulls the human-readable label ("field_label") out of the data dictionary. The data dictionary also drives formatting inside the modified item_metadata include, which checks the field type in the data dictionary before deciding on the proper formatting for field values.
TVBE extends Wax by modifying and adding page layouts and includes, as well.
One major addition is the inclusion of a layout that supports check-box (multi-select) filters on multiple metadata fields - gallery-page-multi-facet.html. This layout is built on Wax's collection_gallery.html include.
Our version uses HTML and Liquid templating to build the main page elements, including a sidebar of checkbox filters and a gallery of collection items. Embedded JavaScript controls the hiding and showing of gallery items based on the checkbox filters. (Filter functionality is still a work in progress.) Finally, to support both visual and non-visual collections, this layout uses a page metadata field called item_include to control the display of items in the gallery. (TVBE has two new item includes - datasets_gallery_item.html and datavis_gallery_item.html.)
Another addition is a modification of the code that formats the item pages. Our indiv_example.html layout -- which is a modification of Wax's generic_collection_item.html layout -- adjusts the layout to work for either visual or non-visual collections by separating the page title and pagination code from the image viewer, which may or may not be present. A list of desired metadata fields (in their desired order) is specified in the header of this file so certain metadata fields can be excluded from display for an entire collection, even if they appear in the original collection metadata and data dictionary.
The item page layout still uses an include to build the metadata table, but the new layout adds support for passing the collection's data dictionary to the include. The item_metadata.html include that formats the item metadata table has been updated to respond to the new data dictionary field types. For example, if a field has a type internal (a new data type used by TVBE), the code finds a collection item with the correct pid and pulls in the item's metadata. This include also supports metadata fields that contain list, a feature made possible by the TVBE data processing scripts.
We have compiled a few helpful tips for developers on modifying Wax, Jekyll, and our scripts.
We are actively developing this resource and plan to release a workflow and documentation to facilitate user contributions in Spring 2021.
The best way to reach out with technical concerns is to lodge an issue on GitHub. You can also view our code in our repository.
