README TimelineSvg

TimelineSvg is a lightweight, browser-based system for generating multi-lane timelines as clean, scalable SVG graphics. It reads simple CSV files, applies a configurable project definition, and renders a fully customizable timeline without requiring any backend or build pipeline.

All processing happens locally in the user’s browser — completely offline and fully private.

---

Features

• Pure browser execution — no server, no installation
• CSV-driven timelines with customizable field mappings
• Automatic layout of months, lanes, and items
• SVG templates with macros ({{MONTHS}}, {{LANES}})
• Replaceable CSS and templates at runtime
• Internal and external view modes
• Offline SVG export (external view only)
• Extremely easy to extend or theme

---

How It Works

TimelineSvg is built around three components:

1. project.json — The project configuration

Each project folder provides a project.json, defining:

{
  "name": "Example Project",
  "dataSource": "example/sample.csv",
  "stylesheet": "example/style.css",
  "svgTemplate": "example/template.svg",
  "settings": {
    "timelineMonths": 18
  },
  "fieldMapping": {
    "id": "ID",
    "title": "Title",
    "lane": "Lane",
    "due": ["Due"]
  }
}

This controls:

• data source
• styling
• template structure
• date range
• field mapping between CSV and internal timeline model

2. CSV input

The CSV must contain at least:

• a title
• a date (any common format: YYYY-MM-DD, DD.MM.YYYY, etc.)
• a lane/group field

Example:

ID,Title,Due,Lane
1,Implement API,2025-12-01,Backend
2,UI Prototype,2026-02-15,Frontend

3. Template-based SVG rendering

TimelineSvg replaces two macros in the template:

• {{MONTHS}} → month labels and vertical grid lines
• {{LANES}} → lane backgrounds, labels, and items

Example template:

<svg xmlns="http://www.w3.org/2000/svg">
  <rect width="100%" height="100%" fill="#FFFFFF"/>
  {{MONTHS}}
  {{LANES}}
</svg>

This makes TimelineSvg highly customizable: You can recreate any design, layout, or branding using your own SVG template.

---

Usage

1. Open the application

Just open index.html in any modern browser (Chrome, Firefox, Safari, Edge).

2. Load a project

You can choose between:

• automatic loading from project.json in the project folder
• manual upload of a project.json file via the UI

3. Preview the timeline

The timeline renders automatically when the CSV loads and is displayed inside the viewer container.

4. Switch views

• Internal View: IDs are visible
• External View: IDs are hidden (used for export)

5. Export SVG

Click Download SVG → an external-view SVG is saved to disk.

---

Project Structure

/
│ index.html
│ engine.js
│ generator.js
│
├─ example/
│   ├─ project.json
│   ├─ style.css
│   ├─ template.svg
│   └─ sample.csv
│
└─ my-project/
    ├─ project.json
    ├─ style.css
    ├─ template.svg
    └─ data.csv

---

Customizing Your Own Project

To create your own timeline project:

1. Duplicate the example/ folder
2. Adjust project.json (dataSource, mappings, template)
3. Replace the CSV with your data
4. Modify the SVG template for your layout
5. Open index.html and load your project

TimelineSvg will take care of the rest.

---

Why SVG?

• infinitely scalable
• editable in design tools
• embeddable in documents, websites, and presentations
• easy to script, style, and customize

---

Requirements

• Any modern browser
• No build tools
• No server
• No dependencies except PapaParse (bundled by CDN)

xxx