Add article that renders IDP analytics events from JSON (LG-5590)

.env.example

@@ -0,0 +1 @@
+export IDP_BASE_URL_PREVIEW=http://localhost:3000

.gitignore

@@ -7,6 +7,5 @@ node_modules/
 .DS_Store
 .vscode
 .idea
+.env
 
-# pulled dynamically in the build/deploy process
-_data/team.yml

Gemfile

@@ -8,6 +8,7 @@ gem "kramdown", ">= 2.3.0"
 group :jekyll_plugins do
   gem "jekyll-redirect-from"
   gem "jekyll-last-modified-at"
+  gem "jekyll-environment-variables"
 end
 
 group :test do

Gemfile.lock

@@ -46,6 +46,8 @@ GEM
       rouge (~> 3.0)
       safe_yaml (~> 1.0)
       terminal-table (~> 1.8)
+    jekyll-environment-variables (1.0.1)
+      jekyll (>= 3.0, < 5.x)
     jekyll-last-modified-at (1.3.0)
       jekyll (>= 3.7, < 5.0)
       posix-spawn (~> 0.3.9)
@@ -117,6 +119,7 @@ DEPENDENCIES
   activesupport
   html-proofer
   jekyll (~> 4)
+  jekyll-environment-variables
   jekyll-last-modified-at
   jekyll-redirect-from
   kramdown (>= 2.3.0)

Makefile

@@ -1,8 +1,8 @@
-run: setup
-	bundle exec jekyll serve --watch
+run: setup .env
+	/bin/bash -c "source .env && bundle exec jekyll serve --watch"
 
-build: setup
-	bundle exec jekyll build
+build: setup .env
+	/bin/bash -c "source .env && bundle exec jekyll build"
 
 setup:
 	bundle
@@ -15,4 +15,7 @@ test: build
 clean:
 	rm -rf _site
 
+.env:
+	cp -n .env.example .env
+
 .PHONY: setup clean

_articles/analytics-events.md

@@ -0,0 +1,35 @@
+---
+title: "Analytics Events"
+description: "Event descriptions"
+layout: article
+category: Reporting
+---
+
+{% if site.env.BRANCH == 'main' %}
+  {% assign idp_base_url = site.env.IDP_BASE_URL %}
+{% else %}
+  {% assign idp_base_url = site.env.IDP_BASE_URL_PREVIEW %}
+{% endif %}
+{% assign idp_base_url = idp_base_url | default: 'https://secure.login.gov' %}
+
+These are the events that are documented in the IDP. Each event has can have custom
+properties that go under `event_properties` in the final payload:
+
+### Events
+
+```json
+{
+  "name": "Event Name",
+  "user_id": "some-user-id",
+  "properties": {
+    "event_properties": {}
+  }
+}
+```
+
+<div
+  id="events-container"
+  data-idp-base-url="{{ idp_base_url }}">
+</div>
+
+<script type="module" src="{{ "/assets/js/analytics-events.js" | prepend: site.baseurl }}"></script>

_articles/queries.md

@@ -2,7 +2,7 @@
 title: "Reporting Queries"
 description: "Queries to run in the Rails console for common reporting questions"
 layout: article
-category: "AppDev"
+category: "Reporting"
 ---
 
 ## Query timeout

_config.yml

@@ -15,10 +15,13 @@ copy_to_destination:
   - node_modules/identity-style-guide/dist/assets
   - node_modules/anchor-js/anchor.min.js
   - node_modules/@18f/private-eye/private-eye.js
+  - node_modules/preact/dist/preact.module.js
+  - node_modules/htm/dist/htm.module.js
 
 plugins:
   - jekyll-redirect-from
   - jekyll-last-modified-at
+  - jekyll-environment-variables
 
 exclude:
   - CONTRIBUTING.md

_layouts/article.html

@@ -10,7 +10,7 @@
                  html=content
                  sanitize=true
                  class="inline_toc usa-accordion usa-sidenav"
-                 id="my_toc"
+                 id="sidenav"
                  item_class="usa-sidenav__item"
                  submenu_class="usa-sidenav__sublist"
                  h_min=2

assets/js/analytics-events.js

@@ -0,0 +1,204 @@
+import { h, Component, render } from '../../preact.module.js';
+import htm from '../../htm.module.js';
+
+// Copied from https://github.com/bryanbraun/anchorjs
+const urlify = new function() {
+  // hax to make the below copy-paste more easily
+  this.options = { truncate: 64 };
+
+  /**
+   * Urlify - Refine text so it makes a good ID.
+   *
+   * To do this, we remove apostrophes, replace non-safe characters with hyphens,
+   * remove extra hyphens, truncate, trim hyphens, and make lowercase.
+   *
+   * @param  {String} text - Any text. Usually pulled from the webpage element we are linking to.
+   * @return {String}      - hyphen-delimited text for use in IDs and URLs.
+   */
+  this.urlify = function(text) {
+    // Decode HTML characters such as ' ' first.
+    var textareaElement = document.createElement('textarea');
+    textareaElement.innerHTML = text;
+    text = textareaElement.value;
+
+    // Regex for finding the non-safe URL characters (many need escaping):
+    //   & +$,:;=?@"#{}|^~[`%!'<>]./()*\ (newlines, tabs, backspace, vertical tabs, and non-breaking space)
+    var nonsafeChars = /[& +$,:;=?@"#{}|^~[`%!'<>\]./()*\\\n\t\b\v\u00A0]/g;
+
+    // The reason we include this _applyRemainingDefaultOptions is so urlify can be called independently,
+    // even after setting options. This can be useful for tests or other applications.
+    if (!this.options.truncate) {
+      _applyRemainingDefaultOptions(this.options);
+    }
+
+    // Note: we trim hyphens after truncating because truncating can cause dangling hyphens.
+    // Example string:                      // " ⚡⚡ Don't forget: URL fragments should be i18n-friendly, hyphenated, short, and clean."
+    return text.trim()                      // "⚡⚡ Don't forget: URL fragments should be i18n-friendly, hyphenated, short, and clean."
+      .replace(/'/gi, '')                   // "⚡⚡ Dont forget: URL fragments should be i18n-friendly, hyphenated, short, and clean."
+      .replace(nonsafeChars, '-')           // "⚡⚡-Dont-forget--URL-fragments-should-be-i18n-friendly--hyphenated--short--and-clean-"
+      .replace(/-{2,}/g, '-')               // "⚡⚡-Dont-forget-URL-fragments-should-be-i18n-friendly-hyphenated-short-and-clean-"
+      .substring(0, this.options.truncate)  // "⚡⚡-Dont-forget-URL-fragments-should-be-i18n-friendly-hyphenated-"
+      .replace(/^-+|-+$/gm, '')             // "⚡⚡-Dont-forget-URL-fragments-should-be-i18n-friendly-hyphenated"
+      .toLowerCase();                       // "⚡⚡-dont-forget-url-fragments-should-be-i18n-friendly-hyphenated"
+  };
+
+  // hax to make the above copy-paste more easily
+  this.urlify = this.urlify.bind(this);
+}().urlify;
+
+window.urlify = urlify;
+
+const html = htm.bind(h);
+
+function Anchor({ slug, icon = String.fromCharCode(59851) }) {
+  const setRef = (dom) => {
+    if (dom && document.location.hash.slice(1) === slug) {
+      setTimeout(() => dom.scrollIntoView(), 0);
+    }
+  }
+
+  return html`
+    <a ref=${setRef}
+       class="anchorjs-link"
+       aria-label="Anchor"
+       data-anchorjs-icon=${icon}
+       id=${slug}
+       href=${`#${slug}`}
+       style="font: 1em / 1 anchorjs-icons; padding-left: 0.375em;"></a>`;
+}
+
+function Example({ event_name, attributes }) {
+  function typeExample(type) {
+    switch(type) {
+      case 'Boolean':
+        return ['true', 'false'];
+      case 'Integer':
+        return 0;
+      case 'Hash':
+        return '{}';
+      default:
+        return type;
+    }
+  }
+
+  const attributeExamples = attributes.flatMap(({ name, types, description }) => {
+    const value = types.flatMap((type) => typeExample(type)).join(' | ');
+
+    let example = [`${name}: ${value},`];
+
+    if (description) {
+      example.unshift(`// ${description}`);
+    }
+
+    return example;
+  });
+
+  if (attributeExamples.length) {
+    attributeExamples.unshift('');
+    attributeExamples.push('');
+  }
+
+  const eventProperties = attributeExamples.
+    join("\n      ").
+    replace(/(  $)/, ''); // fix last line indentation
+
+  const example = `{
+  name: ${JSON.stringify(event_name)},
+  properties: {
+    event_properties: {${eventProperties}}
+  }
+}`;
+
+  return html`<code><pre>${example}</pre></code>`;
+}
+
+function Attribute({ name, types, description }) {
+  return html`
+    <li>
+      <kbd>${name}</kbd>
+      ${ types?.length ? html`${' '}<span>(${types.join(', ')})</span>` : undefined }
+      <p>${description}</p>
+    </li>
+  `;
+}
+
+function Event({ event_name, description, attributes = [] }) {
+  return html`
+    <div>
+      <h3>
+        ${event_name}
+        <${Anchor} slug=${urlify(event_name)} />
+      </h3>
+      <p>${description}</p>
+
+      ${
+        attributes?.length ? html`
+          <h4>
+            Attributes
+            <${Anchor} slug=${urlify(event_name + ' Attributes')} />
+          </h4>
+          <details>
+            <summary>Show attribute details</summary>
+            <ul>
+              ${attributes.map((attribute) => html`<${Attribute} ...${attribute} />` )}
+            </ul>
+          </details>
+        ` : undefined
+      }
+
+      <h4>
+        Example
+        <${Anchor} slug=${urlify(event_name + ' Example')} />
+      </h4>
+      <${Example} event_name=${event_name} attributes=${attributes} />
+    </div>
+  `;
+}
+
+function Events({ events }) {
+  return html`${events.map((event) =>
+    html`<${Event} ...${event} />`
+  )}`;
+}
+
+function SidebarNavItem({ name }) {
+  return html`
+    <li class="usa-sidenav__item">
+      <a href=${`#${urlify(name)}`}>${name}</a>
+    </li>
+   `;
+}
+
+function ErrorPage({ error, url }) {
+  return html`
+    <div class="usa-alert usa-alert--error">
+      <div class="usa-alert__body">
+        <h5 class="usa-alert__heading">Error loading event definitions</h5>
+        <div class="usa-alert__text">
+          <p>There was an error loading event definitions from <a href=${url}>${url}</a>:</p>
+          <p>${error.message}</p>
+        </div>
+      </div>
+    </div>
+  `
+}
+
+function Sidenav({ events }) {
+  return html`${events.map(({ event_name: name }) =>
+    html`<${SidebarNavItem} name=${name} />`
+  )}`;
+}
+
+const container = document.querySelector('#events-container');
+const { idpBaseUrl } = container.dataset;
+const eventsUrl = `${idpBaseUrl}/api/analytics-events`;
+
+const sidenav = document.querySelector('#sidenav');
+
+window.fetch(eventsUrl)
+  .then((response) => response.json())
+  .then(({ events }) => {
+    render(html`<${Events} events=${events} />`, container);
+    render(html`<${Sidenav} events=${events} />`, sidenav);
+  })
+  .catch((error) => render(html`<${ErrorPage} url=${eventsUrl} error=${error} />`, container));