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.
|
||||
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
|
||||
A git repository template to bootstrap coulomb projects from.
|
||||
Reference in New Issue
Block a user