Update README.md
This commit is contained in:
178
README.md
178
README.md
@@ -1,177 +1,3 @@
|
|||||||
# **TimelineSvg**
|
# repo-seed
|
||||||
|
|
||||||
**TimelineSvg** is a lightweight, browser-based system for generating multi-lane timelines as clean, scalable SVG graphics.
|
A git repository template to bootstrap coulomb projects from.
|
||||||
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:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"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:
|
|
||||||
|
|
||||||
```csv
|
|
||||||
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
|
|
||||||
<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
|
|
||||||
Reference in New Issue
Block a user