Documentation

Overview Architecture Data Filtering Graphs Area selection Export Integration

Technical documentation of the SCC References Explorer. The project was undertaken as part of the research conducted by the group Governance of the Universal Church after the Council of Trent at the Max Planck Institute for Legal History and Legal Theory.

Overview

The Explorer offers an interactive search over a bibliographical catalogue of the Congregation of the Council, together with a graphic visualisation of the same material. It consists of two applications, Search References and Build Graphs, which share one dataset.

Both were originally written in R with shiny, DT and ggplot2, and served from a Shiny server. They have since been ported to plain HTML, CSS and JavaScript. There is no longer any server-side component: the pages are static files and run equally well from a web server or from the local file system.

Architecture

Each application is four files placed beside the page that hosts it:

graph.html          the page, with the site navbar and footer
graph_styles.css    styles, scoped under #scc-graph
graph_keywords.js   the keyword taxonomy and the sidebar tree
graph_app.js        filtering, plotting, selection, export
graph_data.js       the catalogue, embedded as a JavaScript constant

The search application follows the same pattern under the prefix bib_.

External libraries are loaded from a CDN: Chart.js in place of ggplot2, DataTables in place of DT, and noUiSlider for the period control. The catalogue is attached with a <script> tag rather than fetched, because fetch() is refused for file:// URLs and would otherwise require a local server.

Data

The catalogue is maintained in EndNote and exported as BibTeX. The R version converted that export into a data frame with bib2df; the static version starts from the semicolon-delimited table derived from it, dataset_format.csv.

A short Python script, build_data.py, turns that table into graph_data.js, reproducing the preparation the R code performed at start-up: Year_format is renamed to Year, TYPE is duplicated as TYPOLOGY_OF_PUBLICATION, empty and NA cells are normalised, duplicate rows are dropped and the records are sorted by author. Re-run it whenever the catalogue changes:

python3 build_data.py

Filtering

The keyword tree is declared in graph_keywords.js: GROUPS holds the terms of each checkbox group, PANELS the nesting, colours and indentation of the sidebar. Both were transcribed from the Shiny UI, so the panels can be re-ordered or recoloured without touching the application logic.

A record is kept when its KEYWORDS field matches any of the ticked terms and its year falls inside the slider range. This reproduces the disjunctive grepl match of the R version, with one correction: terms are escaped before being joined into the expression, so brackets in labels such as Examination (concursus) are matched literally instead of being read as regular-expression groups.

Graphs

Three plots are provided. Bubble aggregates the filtered records into cells of the two axes and scales each bubble by the number of records in the cell. Bar counts records per X category and stacks them by the Y category, drawn horizontally as coord_flip() did. Pie shows the composition of the colour column.

Chart.js has a category scale, but it cannot place two points at the same category without overlap bookkeeping. Categorical axes are therefore drawn as linear axes over the category indices, with an explicit tick per category; the numeric Year axis needs no such treatment. Colours come from a fixed palette of twelve; beyond that the hue circle is walked by the golden angle, so a column such as Place with thirty values stays legible. The legend moves below the plot once there are more than fourteen levels.

Area selection

Shiny provided rectangular selection through brushOpts() and brushedPoints(), both server-side. The static version implements it as a Chart.js plugin: pointer events on the canvas track the rectangle, the plugin draws it in afterDraw, and on release the rectangle is tested against the rendered elements — centre containment for bubbles, rectangle intersection for bars.

Every plotted element carries the records it was built from, so a hit contributes all of them; the results are de-duplicated by record index before being handed to the table. Listeners are bound to an AbortController tied to the chart, so nothing survives a redraw.

Export

The selection can be written out as CSV, as an Excel-readable table, or as BibTeX, the last assembled from the record fields with CATEGORY as the entry type and BIBTEXKEY as the key. Files are produced in the browser as blobs; nothing is uploaded. The plot itself is exported by drawing the canvas onto an opaque white background and saving it as PNG.

Integration

The site pages carry Bootstrap 3 (sandstone) and Bootstrap 5 together, and both define selectors the applications also use — .panel-body, .container, .table. Each application is therefore wrapped in a single element (#scc-graph, #scc-app) and every rule in its stylesheet is scoped under that id, so the page cannot reach into the application and the application cannot leak onto the navbar or the footer. DataTables is loaded in its default build rather than a Bootstrap integration build for the same reason.

The pages otherwise keep the navbar, the secondary navbar and the footer unchanged. The R Markdown scaffolding they inherited — MathJax, highlight.js, tabsets, code folding and the shims — was removed, along with the iframe that used to embed the Shiny server.