Frontend UI Components

Relevant source files

The following files were used as context for generating this wiki page:

• assets/scripts/components/table-of-contents.js
• assets/scripts/components/copy-code.js
• assets/scripts/components/tooltip.js
• assets/scripts/alpine.js
• content/en/actions/app_builder/components/_index.md
• content/en/notebooks/guide/build_diagrams_with_mermaidjs.md

The Datadog documentation platform utilizes a combination of a lightweight JavaScript framework, custom-built components for documentation-specific interactivity, and a comprehensive UI component library for building embedded applications. The core reactive functionality is powered by Alpine.js, which provides a declarative way to manage component state directly in the markup.

For the documentation site itself, bespoke JavaScript components handle features like the dynamic table of contents, copy-to-clipboard functionality for code blocks, and tooltips. For more complex, data-driven applications, the App Builder provides a rich set of pre-built UI components, ranging from simple buttons and forms to complex tables and custom charts. Additionally, the platform supports diagram rendering within Markdown using Mermaid.js.

Core Interactivity Framework

The frontend relies on Alpine.js as its primary framework for creating reactive and declarative UI components. It is initialized globally and provides the foundation for many of the interactive elements on the site.

Sources: assets/scripts/alpine.js

Alpine.js Integration

Alpine.js is imported and started, making its directives (x-data, x-init, x-show, etc.) available throughout the application. This allows for the creation of stateful components with minimal JavaScript.

The diagram below illustrates how Alpine.js acts as a foundational layer for other custom components.

Documentation-Specific Components

These components are custom-built to enhance the user experience on the documentation pages.

Table of Contents

This component dynamically generates a table of contents, tracks the user's scroll position, and highlights the currently active section.

Key Features:

• Initialization: On page load, it finds all heading elements (h2, h3, etc.) within the main content area to build the ToC links.
• Scroll Tracking: It uses an IntersectionObserver to monitor when headings enter or leave the viewport.
• Active Link Highlighting: As the user scrolls, the component adds an active class to the corresponding link in the table of contents, providing clear visual feedback.

The following flowchart shows the logic of the Table of Contents component.

Copy Code

This component adds a "Copy" button to code blocks, allowing users to easily copy code snippets to their clipboard.

Functionality:

1. A user clicks the copy button associated with a code block.
2. The script accesses the clipboard API to write the code block's text content.
3. Upon successful copy, the button's text temporarily changes (e.g., to "Copied!") to provide user feedback.
4. If the copy action fails, an error is logged to the console.

This sequence diagram illustrates the copy-to-clipboard process.

Tooltip

The tooltip component provides contextual information on hover. It is initialized on elements that have a data-tooltip-template attribute. It uses the Popper.js library for correct positioning.

Initialization:

• The script finds all elements with the data-tooltip-template attribute.
• For each element, it creates a Popper instance, using the content from the specified template.
• Event listeners for mouseenter and mouseleave are added to show and hide the tooltip.

Sources: assets/scripts/components/tooltip.js

App Builder UI Component Library

The App Builder provides a wide array of UI components for creating rich, interactive, embedded applications. These components are highly configurable through a properties panel in the App Builder UI, with many properties accepting JavaScript expressions for dynamic behavior.

Sources: content/en/actions/app_builder/components/_index.md

The following table summarizes the main components available in the App Builder.

Category	Component	Description
General	Button	A standard button with configurable intent, appearance, and click events.
	Container	A layout component to group other components.
	Integration Logo	Displays a logo for a specified integration (e.g., amazon-s3, postgres).
	Text	A component for displaying plain text or Markdown content.
Forms & Inputs	Form	A container for input fields with a title and submit/change events. Supports text inputs, selects, and text areas.
	Checkbox	A group of checkboxes for multiple selections.
	Date range picker	A UI control for selecting a time frame.
	File input	Allows users to upload files (e.g., .csv, .json).
	JSON input	A specialized input field for entering JSON data.
	Number input	An input field restricted to numerical values, with min/max validation.
	Radio	A group of radio buttons for single selection.
	Search	A search input box with submit and change events.
	Select	A dropdown menu for single or multiple selections.
	Text area	A multi-line text input field.
	Text input	A single-line text input field.
Data Display	Callout value	Highlights a single metric with a label and unit.
	Custom chart	Renders a chart using a Vega-Lite or Vega JSON specification.
	Table	A powerful component for displaying tabular data with sorting, pagination, filtering, and row actions.
Interactive	Modal	A dialog box that appears on top of the app's content.
	Tab	A component for organizing content into multiple tabbed views.
	React renderer	Allows rendering of custom React components within an app.

Sources: content/en/actions/app_builder/components/_index.md

Diagramming Components

Datadog Notebooks support rendering diagrams directly within Markdown cells using Mermaid.js syntax. This allows for the creation of flowcharts, sequence diagrams, and other visualizations alongside other notebook content.

To create a diagram:

1. Add a Markdown cell to a notebook.
2. Create a code block and select Mermaid-JS as the language.
3. Write valid Mermaid syntax within the code block.

Example of a simple flowchart:

Summary

The frontend UI of the Datadog documentation platform is a multi-faceted system. It uses Alpine.js for lightweight reactivity on static pages, enhanced by a suite of custom JavaScript components for common documentation needs like navigation and code interaction. For building complex, data-driven applications, the App Builder offers an extensive and powerful library of pre-built components. This dual approach provides both performance for content-heavy pages and flexibility for interactive application development.