[Vis Tools] Define standardized vis tools in Flask and allow customization (#6066)

nick-nlb · web-flow · commit 71a7a54198f7 · 2026-03-09T11:58:54.000-07:00
## Issue [b/489513837](https://buganizer.corp.google.com/issues/489513837) ## Description Pre-standardized versions of the vis tools allowed for customization of the examples. The default examples (for the main site) were provided in Flask as JSON, and these could be overridden by duplicating them into a particular custom_dc directory and editing them. While this functionality still exists, it is not applied to the (very different) examples given by the new standardizecd tools. These were provided directly in the TS, and were not easily customizable. This PR moves the definitions of examples out of TypeScript and into Flask. We have a few different ways that we transfer information from Flask to the frontend. In this case, we opted to use the same method as we used for the old tools, in order to keep the process of customizing these nearly identical to what it was before. ## Details In `server/template/tools`, the same directory where the existing default examples for older tools was provided, we now supply files for each of the three tool types: `scatter_vis_tool_examples.json`, `map_vis_tool_examples.json` and `timeline_vis_tool_examples.json`. These three files populate the primary DC website and also serve as the main examples. The files are JSON, in the following format: ``` [ { "id": "unique_id_1", "titleMessageId": "optional id for i18n, does not need to be provided if a title is given. This will be translated by the frontend, and will not generally be used by custom DCs", "title": "Title to be used in lieu of a translatable message ID. This will be used by custom DCs. "url": "/tools/timeline#{...url to chart...}" }, ... subsequent examples ``` As described in the example above, you only need to give either a titleMessageId (for i18n conversion) or a title, which will be used directly. Custom DCs will almost certainly only use the `title`. ### Process for customizing The process for a custom DC to customize these examples is very similar to what it was for the old tools. You take the example file from the root `server/template/tools` directory, and copy it into `server/custom_dc/{custom dc name}`. You would then edit the file, giving the titles and URLs that you want for the examples. The frontend will then pick those up. As noted above, a custom DC is very unlikely to use a titleMessageId, because they won't be using the i18n library. ## Testing If you do not provide a custom example set, the site should look identical to how it did before. In other words the following URL should look the same on both master and locally: https://datacommons.org/tools/map http://localhost:8080/tools/map However, if you either edit the default examples, or load a custom DC and create an override for that custom DC as above, you will see those examples, rather than the default ones. A note that if you are running a custom DC, you will want to turn the standardized vis tool flag on in order to see the changes. ## Screenshots ### Before <img width="1294" height="669" alt="Screenshot 2026-03-06 at 8 35 19 AM" src="https://github.com/user-attachments/assets/7e531088-0f24-4a79-acb9-4c1e56289071" /> ### After <img width="1681" height="679" alt="Screenshot 2026-03-06 at 8 37 05 AM" src="https://github.com/user-attachments/assets/3f5771cb-9776-4cfa-a6cb-8c173a181a36" />
diff --git a/server/routes/tools/html.py b/server/routes/tools/html.py
@@ -38,18 +38,42 @@ def get_example_file(tool):
                       'templates/tools/{}_examples.json'.format(tool))
 
 
+def load_example_file(tool_or_filename, default=None):
+  """Loads a JSON example file, returning a default if missing."""
+  if default is None:
+    default = {}
+  filepath = get_example_file(tool_or_filename)
+  if os.path.exists(filepath):
+    try:
+      with open(filepath) as f:
+        return json.load(f)
+    except json.JSONDecodeError:
+      current_app.logger.error('Malformed JSON in %s', filepath)
+  return default
+
+
+def _get_vis_tool_examples(tool_name):
+  """Returns (info_json, vis_tool_examples_json, use_standardized_ui)"""
+  use_standardized_ui = is_feature_enabled(STANDARDIZED_VIS_TOOL_FEATURE_FLAG,
+                                           request=request)
+  if use_standardized_ui:
+    return {}, load_example_file(f'{tool_name}_vis_tool', default=[]), True
+  return load_example_file(tool_name, default={}), [], False
+
+
 @bp.route('/timeline')
 def timeline():
-  with open(get_example_file('timeline')) as f:
-    info_json = json.load(f)
-    return flask.render_template(
-        'tools/timeline.html',
-        info_json=info_json,
-        use_standardized_ui=is_feature_enabled(
-            STANDARDIZED_VIS_TOOL_FEATURE_FLAG, request=request),
-        maps_api_key=current_app.config['MAPS_API_KEY'],
-        sample_questions=json.dumps(
-            current_app.config.get('HOMEPAGE_SAMPLE_QUESTIONS', [])))
+  info_json, vis_tool_examples_json, use_standardized_ui = _get_vis_tool_examples(
+      'timeline')
+
+  return flask.render_template('tools/timeline.html',
+                               info_json=info_json,
+                               vis_tool_examples_json=vis_tool_examples_json,
+                               use_standardized_ui=use_standardized_ui,
+                               maps_api_key=current_app.config['MAPS_API_KEY'],
+                               sample_questions=json.dumps(
+                                   current_app.config.get(
+                                       'HOMEPAGE_SAMPLE_QUESTIONS', [])))
 
 
 # This tool was used by several data science course (but no traffic in 2025).
@@ -60,30 +84,32 @@ def timeline_bulk_download():
 
 @bp.route('/map')
 def map():
-  with open(get_example_file('map')) as f:
-    info_json = json.load(f)
-    return flask.render_template(
-        'tools/map.html',
-        maps_api_key=current_app.config['MAPS_API_KEY'],
-        info_json=info_json,
-        use_standardized_ui=is_feature_enabled(
-            STANDARDIZED_VIS_TOOL_FEATURE_FLAG, request=request),
-        sample_questions=json.dumps(
-            current_app.config.get('HOMEPAGE_SAMPLE_QUESTIONS', [])))
+  info_json, vis_tool_examples_json, use_standardized_ui = _get_vis_tool_examples(
+      'map')
+
+  return flask.render_template('tools/map.html',
+                               maps_api_key=current_app.config['MAPS_API_KEY'],
+                               info_json=info_json,
+                               vis_tool_examples_json=vis_tool_examples_json,
+                               use_standardized_ui=use_standardized_ui,
+                               sample_questions=json.dumps(
+                                   current_app.config.get(
+                                       'HOMEPAGE_SAMPLE_QUESTIONS', [])))
 
 
 @bp.route('/scatter')
 def scatter():
-  with open(get_example_file('scatter')) as f:
-    info_json = json.load(f)
-    return flask.render_template(
-        'tools/scatter.html',
-        info_json=info_json,
-        use_standardized_ui=is_feature_enabled(
-            STANDARDIZED_VIS_TOOL_FEATURE_FLAG, request=request),
-        maps_api_key=current_app.config['MAPS_API_KEY'],
-        sample_questions=json.dumps(
-            current_app.config.get('HOMEPAGE_SAMPLE_QUESTIONS', [])))
+  info_json, vis_tool_examples_json, use_standardized_ui = _get_vis_tool_examples(
+      'scatter')
+
+  return flask.render_template('tools/scatter.html',
+                               info_json=info_json,
+                               vis_tool_examples_json=vis_tool_examples_json,
+                               use_standardized_ui=use_standardized_ui,
+                               maps_api_key=current_app.config['MAPS_API_KEY'],
+                               sample_questions=json.dumps(
+                                   current_app.config.get(
+                                       'HOMEPAGE_SAMPLE_QUESTIONS', [])))
 
 
 @bp.route('/statvar')
@@ -98,24 +124,24 @@ def stat_var():
 def download():
   # List of DCIDs displayed in the info page for download tool
   # NOTE: EXACTLY 2 EXAMPLES REQUIRED.
-  with open(get_example_file('download')) as f:
-    info_places = json.load(f)
-    return flask.render_template(
-        'tools/download.html',
-        info_places=json.dumps(info_places),
-        maps_api_key=current_app.config['MAPS_API_KEY'],
-        sample_questions=json.dumps(
-            current_app.config.get('HOMEPAGE_SAMPLE_QUESTIONS', [])))
+  info_places = load_example_file('download', default=[])
+
+  return flask.render_template('tools/download.html',
+                               info_places=json.dumps(info_places),
+                               maps_api_key=current_app.config['MAPS_API_KEY'],
+                               sample_questions=json.dumps(
+                                   current_app.config.get(
+                                       'HOMEPAGE_SAMPLE_QUESTIONS', [])))
 
 
 @bp.route('/visualization')
 def visualization():
-  with open(get_example_file('visualization')) as f:
-    info_json = json.load(f)
-    return flask.render_template(
-        'tools/visualization.html',
-        manual_ga_pageview=True,
-        info_json=info_json,
-        maps_api_key=current_app.config['MAPS_API_KEY'],
-        sample_questions=json.dumps(
-            current_app.config.get('HOMEPAGE_SAMPLE_QUESTIONS', [])))
+  info_json = load_example_file('visualization', default={})
+
+  return flask.render_template('tools/visualization.html',
+                               manual_ga_pageview=True,
+                               info_json=info_json,
+                               maps_api_key=current_app.config['MAPS_API_KEY'],
+                               sample_questions=json.dumps(
+                                   current_app.config.get(
+                                       'HOMEPAGE_SAMPLE_QUESTIONS', [])))
diff --git a/server/templates/tools/map.html b/server/templates/tools/map.html
@@ -32,7 +32,8 @@
   <div id="metadata" class="d-none" data-footer="{{ config['MAP_TOOL_FOOTER'] }}"></div>
   <div id="main-pane"></div>
   <script>
-    infoConfig = {{info_json|tojson|safe}};
+    globalThis.infoConfig = {{ info_json | tojson | safe }};
+    globalThis.visToolExamples = {{ vis_tool_examples_json | default([]) | tojson | safe }};
     globalThis.minStatVarGeoCoverage = {{ config['MIN_STAT_VAR_GEO_COVERAGE'] | int(1) }};
   </script>
 {% endblock %}
diff --git a/server/templates/tools/map_vis_tool_examples.json b/server/templates/tools/map_vis_tool_examples.json
@@ -0,0 +1,37 @@
+[
+  {
+    "id": "map_water_withdrawal_rate_in_the_usa",
+    "titleMessageId": "waterWithdrawalRateInUsa",
+    "url": "/tools/map#%26sv%3DWithdrawalRate_Water%26pc%3D0%26denom%3DCount_Person%26pd%3Dcountry%2FUSA%26ept%3DCounty"
+  },
+  {
+    "id": "map_unemployment_rate_in_new_jersey",
+    "titleMessageId": "unemploymentRateInNewJersey",
+    "url": "/tools/map#%26sv%3DUnemploymentRate_Person%26pc%3D0%26denom%3DCount_Person%26pd%3DgeoId%2F34%26ept%3DCounty"
+  },
+  {
+    "id": "map_median_income_in_texas",
+    "titleMessageId": "medianIncomeInTexas",
+    "url": "/tools/map#%26sv%3DMedian_Income_Person%26pc%3D0%26denom%3DCount_Person%26pd%3DgeoId%2F48%26ept%3DCounty"
+  },
+  {
+    "id": "map_attainment_of_bachelor_degree_in_colorado",
+    "titleMessageId": "attainmentOfBachelorDegreeInColorado",
+    "url": "/tools/map#%26sv%3DCount_Person_EducationalAttainmentBachelorsDegreeOrHigher%26pc%3D1%26denom%3DCount_Person%26pd%3DgeoId%2F08%26ept%3DCounty"
+  },
+  {
+    "id": "map_projected_temperature_rise_in_the_usa",
+    "titleMessageId": "projectedTemperatureRiseInUsa",
+    "url": "/tools/map#%26sv%3DDifferenceRelativeToBaseDate2006_Max_Temperature_RCP45%26pc%3D0%26denom%3DCount_Person%26pd%3Dcountry%2FUSA%26ept%3DCounty"
+  },
+  {
+    "id": "map_median_age_in_usa",
+    "titleMessageId": "medianAgeInUsa",
+    "url": "/tools/map#%26sv%3DMedian_Age_Person%26pc%3D0%26denom%3DCount_Person%26pd%3Dcountry%2FUSA%26ept%3DCounty"
+  },
+  {
+    "id": "map_no_schooling_completed_in_usa",
+    "titleMessageId": "noSchoolingCompletedInUsa",
+    "url": "/tools/map#%26sv%3DCount_Person_EducationalAttainmentNoSchoolingCompleted%26pc%3D0%26denom%3DCount_Person%26pd%3Dcountry%2FUSA%26ept%3DCounty"
+  }
+]
diff --git a/server/templates/tools/scatter.html b/server/templates/tools/scatter.html
@@ -31,7 +31,8 @@
 <div id="metadata" class="d-none"></div>
 <div id="main-pane"></div>
 <script>
-  infoConfig = {{info_json|tojson|safe}};
+  globalThis.infoConfig = {{ info_json | tojson | safe }};
+  globalThis.visToolExamples = {{ vis_tool_examples_json | default([]) | tojson | safe }};
   globalThis.minStatVarGeoCoverage = {{ config['MIN_STAT_VAR_GEO_COVERAGE'] | int(1) }};
 </script>
 {% endblock %}
diff --git a/server/templates/tools/scatter_vis_tool_examples.json b/server/templates/tools/scatter_vis_tool_examples.json
@@ -0,0 +1,12 @@
+[
+  {
+    "id": "scatter_prevalence_of_coronary_heart_disease_vs_projected_temperature_rise_in_the_usa",
+    "titleMessageId": "coronaryHeartDiseaseVsProjectedTemperatureRise",
+    "url": "/tools/scatter#%26svx%3DDifferenceRelativeToBaseDate2006_Max_Temperature_RCP45%26dx%3DCount_Person%26svy%3DPercent_Person_WithCoronaryHeartDisease%26dy%3DCount_Person%26epd%3Dcountry%2FUSA%26ept%3DCounty%26qd%3D1%26dd%3D1%26pp%3D"
+  },
+  {
+    "id": "scatter_literate_population_per_capita_vs_population_below_poverty_level_per_capita_for_states_in_india",
+    "titleMessageId": "literatePopulationVsPopulationBelowPovertyLevel",
+    "url": "/tools/scatter#svx%3DCount_Person_BelowPovertyLevelInThePast12Months_AsFractionOf_Count_Person%26dx%3DCount_Person%26svy%3DCount_Person_Literate%26pcy%3D1%26dy%3DCount_Person%26epd%3Dcountry%2FIND%26ept%3DAdministrativeArea1"
+  }
+]
diff --git a/server/templates/tools/timeline.html b/server/templates/tools/timeline.html
@@ -31,7 +31,8 @@
 <div id="metadata" class="d-none"></div>
 <div id="main-pane"></div>
 <script>
-  infoConfig = {{info_json|tojson|safe}};
+  globalThis.infoConfig = {{ info_json | tojson | safe }};
+  globalThis.visToolExamples = {{ vis_tool_examples_json | default([]) | tojson | safe }};
 </script>
 {% endblock %}
 
diff --git a/server/templates/tools/timeline_vis_tool_examples.json b/server/templates/tools/timeline_vis_tool_examples.json
@@ -0,0 +1,22 @@
+[
+  {
+    "id": "timeline_water_withdrawal_rate_in_california",
+    "titleMessageId": "waterWithdrawalRateInCalifornia",
+    "url": "/tools/timeline#place=geoId%2F06&statsVar=WithdrawalRate_Water_Thermoelectric__WithdrawalRate_Water_PublicSupply__WithdrawalRate_Water_Irrigation__WithdrawalRate_Water_Aquaculture"
+  },
+  {
+    "id": "timeline_university_towns_by_income",
+    "titleMessageId": "universityTownsByIncome",
+    "url": "/tools/timeline#&place=geoId/0606000,geoId/2511000,geoId/2603000,geoId/1777005,geoId/1225175,geoId/4815976&statsVar=Median_Income_Person"
+  },
+  {
+    "id": "timeline_close_but_different_berkeley_and_piedmont",
+    "titleMessageId": "closeButDifferentBerkeleyAndPiedmont",
+    "url": "/tools/timeline#place=geoId%2F0606000%2CgeoId%2F0656938&statsVar=Median_Income_Person__Percent_Person_18OrMoreYears_WithPoorGeneralHealth__Monthly_Median_GrossRent_HousingUnit__Count_CriminalActivities_CombinedCrime&chart=%7B%22count-none%22%3A%7B%22pc%22%3Afalse%2C%22delta%22%3Afalse%7D%2C%22age-none%22%3A%7B%22pc%22%3Afalse%2C%22delta%22%3Afalse%7D%2C%22grossRent-none%22%3A%7B%22pc%22%3Afalse%2C%22delta%22%3Afalse%7D%2C%22unemploymentRate-none%22%3A%7B%22pc%22%3Afalse%2C%22delta%22%3Afalse%7D%7D"
+  },
+  {
+    "id": "timeline_close_but_different_palo_alto_and_east_palo_alto",
+    "titleMessageId": "closeButDifferentPaloAltoAndEastPaloAlto",
+    "url": "/tools/timeline#place=geoId%2F0655282%2CgeoId%2F0620956&statsVar=Median_Income_Person__UnemploymentRate_Person__Count_Person_HispanicOrLatino__Count_Person_AsianAlone__Count_Person_BlackOrAfricanAmericanAlone__Count_Person_WhiteAlone__Percent_Person_18OrMoreYears_WithPoorGeneralHealth__Monthly_Median_GrossRent_HousingUnit&chart=%7B%22count-none%22%3A%7B%22pc%22%3Afalse%2C%22delta%22%3Afalse%7D%2C%22age-none%22%3A%7B%22pc%22%3Afalse%2C%22delta%22%3Afalse%7D%2C%22grossRent-none%22%3A%7B%22pc%22%3Afalse%2C%22delta%22%3Afalse%7D%7D"
+  }
+]
diff --git a/static/js/tools/map/app.tsx b/static/js/tools/map/app.tsx
@@ -66,6 +66,7 @@ function App(): ReactElement {
     statVar.value,
     placeInfo.value
   );
+  const visToolExamples = globalThis.visToolExamples || [];
 
   return (
     <React.StrictMode>
@@ -99,7 +100,10 @@ function App(): ReactElement {
                       margin-top: ${theme.spacing.xl}px;
                     `}
                   >
-                    <ChartLinkChips toolType="map" />
+                    <ChartLinkChips
+                      toolType="map"
+                      visToolExamples={visToolExamples}
+                    />
                   </div>
                 )
               ) : (
diff --git a/static/js/tools/scatter/app.tsx b/static/js/tools/scatter/app.tsx
@@ -66,6 +66,8 @@ function App(): ReactElement {
     STANDARDIZED_VIS_TOOL_FEATURE_FLAG
   );
   const theme = useTheme();
+  const visToolExamples = globalThis.visToolExamples || [];
+
   return (
     <>
       <StatVarChooser
@@ -119,7 +121,10 @@ function App(): ReactElement {
                       margin-top: ${theme.spacing.xl}px;
                     `}
                   >
-                    <ChartLinkChips toolType="scatter" />
+                    <ChartLinkChips
+                      toolType="scatter"
+                      visToolExamples={visToolExamples}
+                    />
                   </Row>
                 )
               ) : (
diff --git a/static/js/tools/shared/vis_tools/chart_link_chips.tsx b/static/js/tools/shared/vis_tools/chart_link_chips.tsx
@@ -23,26 +23,58 @@ import React from "react";
 import { LinkChips } from "../../../components/content/link_chips";
 import { Link } from "../../../components/elements/link_chip";
 import { intl } from "../../../i18n/i18n";
-import { toolMessages } from "../../../i18n/i18n_tool_messages";
-import { landingPageLinks } from "./landing_page_example_links";
+import {
+  toolMessages,
+  VisToolExampleChartMessages,
+} from "../../../i18n/i18n_tool_messages";
+
+declare global {
+  interface Window {
+    visToolExamples?: VisToolExample[];
+  }
+}
+
+export interface VisToolExample {
+  id: string;
+  title?: string;
+  titleMessageId?: string;
+  url: string;
+}
 
 interface ChartLinkChipsProps {
   toolType: "map" | "scatter" | "timeline";
+  visToolExamples: VisToolExample[];
 }
 
-/** Gets the set of link chips for the correct tool from the config */
-function getLinkChips(props: ChartLinkChipsProps): Link[] {
-  switch (props.toolType) {
-    case "map": {
-      return landingPageLinks.mapLinks;
-    }
-    case "scatter": {
-      return landingPageLinks.scatterLinks;
+function getLinkChips(config: VisToolExample[]): Link[] {
+  if (!config || !Array.isArray(config)) {
+    return [];
+  }
+
+  const links: Link[] = [];
+
+  for (const item of config) {
+    let finalTitle = item.title;
+
+    const messageKey =
+      item.titleMessageId as keyof typeof VisToolExampleChartMessages;
+    if (!finalTitle && messageKey && VisToolExampleChartMessages[messageKey]) {
+      finalTitle = intl.formatMessage(VisToolExampleChartMessages[messageKey]);
     }
-    default: {
-      return landingPageLinks.timelineLinks;
+
+    // if a given example does not contain an id or final title, we omit
+    if (!finalTitle || !item.id) {
+      continue;
     }
+
+    links.push({
+      id: item.id,
+      title: finalTitle,
+      url: item.url,
+    });
   }
+
+  return links;
 }
 
 export function ChartLinkChips(props: ChartLinkChipsProps): JSX.Element {
@@ -52,7 +84,7 @@ export function ChartLinkChips(props: ChartLinkChipsProps): JSX.Element {
       header={intl.formatMessage(toolMessages.ExamplesHeader)}
       headerComponent="h4"
       section={`${props.toolType}_tool_example_charts`}
-      linkChips={getLinkChips(props)}
+      linkChips={getLinkChips(props.visToolExamples)}
       chipTextSize="sm"
     />
   );
diff --git a/static/js/tools/shared/vis_tools/landing_page_example_links.ts b/static/js/tools/shared/vis_tools/landing_page_example_links.ts
diff --git a/static/js/tools/timeline/page.tsx b/static/js/tools/timeline/page.tsx
