Example Framework

The Example Framework is OpenLayers' documentation system for generating interactive code examples with live demos, syntax highlighting, and CodePen integration. This system processes example source files, applies templates, and creates a searchable gallery of working examples that demonstrate OpenLayers functionality.

For information about the main build system and tooling infrastructure, see Build System and Tooling.

Purpose and Architecture

The Example Framework transforms individual example files with YAML front matter into fully rendered HTML pages with embedded maps, source code display, and interactive features. The system consists of a build-time webpack plugin that processes examples and runtime JavaScript that provides search, filtering, and external editor integration.

Build Pipeline Overview

100%

Template System

The framework uses Handlebars templates to generate example pages from source data. The main template processes front matter metadata and combines it with HTML content, JavaScript source, and CSS styling.

Template Data Structure

Property	Type	Description
title	string	Example title displayed in navigation
shortdesc	string	Brief description for example index
docs	string	Markdown documentation content
tags	Array	Tags for categorization and search
layout	string	Template file to use for rendering
experimental	boolean	Shows experimental API warning
resources	Array	Additional CSS/JS dependencies
cloak	Array	Key-value pairs for hiding sensitive data

Template Processing Flow

100%

ExampleBuilder Plugin

The ExampleBuilder class is a webpack plugin that orchestrates the entire example generation process during build time.

Core Processing Methods

The plugin implements several key processing methods:

• parseExample() - Extracts YAML front matter and HTML content from example files
• transformJsSource() - Modifies import paths and removes development-specific code
• removeTypeComments() - Strips TypeScript-style type annotations for cleaner display
• cloakSource() - Replaces sensitive keys with placeholder values
• getDependencies() - Analyzes imports to generate package.json dependencies

100%

Search and Index System

The examples index provides client-side search functionality through a word-based indexing system that scores examples based on term frequency and relevance.

Search Implementation

The search system in index.js implements:

• Word Index Creation - Tokenizes example titles, descriptions, and tags
• Fuzzy Matching - Supports partial word matches using regular expressions
• Relevance Scoring - Ranks results by word frequency and match count
• URL State Management - Preserves search terms in browser history

100%

CodePen Integration

The framework provides seamless integration with external code editors through the common.js resource management system.

Export Process

The CodePen integration handles:

• Source Code Extraction - Pulls JavaScript, HTML, and CSS from displayed examples
• Dependency Resolution - Generates appropriate package.json with version constraints
• Resource Bundling - Fetches local resources and converts them for external use
• Compression - Uses LZ-String compression for efficient data transfer

100%

Resource Management

The framework handles various types of resources and dependencies that examples require.

Resource Types

Resource Type	Pattern	Handling
JavaScript	*.js	Bundled with webpack, import path transformation
CSS	*.css	Linked in template, processed for external export
Images	*.png, *.jpg, etc.	Referenced by URL, binary handling for export
Data Files	data/*	Fetched dynamically, embedded in CodePen exports

Dependency Processing

The getDependencies() function analyzes JavaScript imports to automatically generate package.json files with correct version constraints:

100%

File Organization

The Example Framework follows a structured organization pattern:

• examples/ - Source example files with front matter
• examples/templates/ - Handlebars template files
• examples/resources/ - Shared JavaScript and CSS resources
• examples/webpack/ - Build system integration
• build/examples/ - Generated example output (during build)

Each example consists of coordinated files sharing the same base name:

• example-name.html - HTML template with YAML front matter
• example-name.js - JavaScript implementation
• example-name.css - Optional custom styling