TimelineJS Deployment and Usage Guide

Prerequisites

Runtime: Modern web browser (Chrome, Firefox, Safari, Edge)
Development Tools:
- Node.js (for building from source)
- Git (for cloning the repository)
Optional: API keys for external services (Google, Flickr, Twitter) if using those data sources

Installation

Clone the repository:

git clone https://github.com/NUKnightLab/TimelineJS.git
cd TimelineJS

Install dependencies (if building from source):
```
npm install
```
Build the project (if needed):
```
npm run build
```

Configuration

Timeline Configuration

TimelineJS accepts configuration through JavaScript object when initializing:

var timeline_config = {
    width: 960,
    height: 540,
    start_at_slide: 0,
    start_at_end: false,
    hash_bookmark: false,
    source: "your_data_source_url",
    embed: false,
    type: "timeline",
    touch: false,
    orientation: "normal",
    maptype: "",
    preload: 4,
    interval: 10,
    api_keys: {
        google: "",
        flickr: "",
        twitter: ""
    }
};

Data Source Configuration

TimelineJS supports multiple data sources:

Google Spreadsheet: Provide the spreadsheet URL
JSON/JSONP: Provide the URL to your JSON data
HTML: Provide HTML content
Twitter Search: Use hashtag format (e.g., %23medill)
Storify: Provide Storify URL

API Keys (Optional)

If using external services, configure API keys in the api_keys object:

api_keys: {
    google: "YOUR_GOOGLE_API_KEY",
    flickr: "YOUR_FLICKR_API_KEY",
    twitter: "YOUR_TWITTER_API_KEY"
}

Build & Run

Development

Serve the files locally:
```
npm run dev
```
Open your browser and navigate to http://localhost:8080

Production

Build for production:
```
npm run build
```
Deploy the dist folder to your web server

Embedding TimelineJS

To embed TimelineJS in your webpage:

<!DOCTYPE html>
<html>
<head>
    <link href="css/timeline.css" rel="stylesheet">
</head>
<body>
    <div id="timeline"></div>
    <script src="js/timeline-min.js"></script>
    <script>
        var timeline = new VMM.Timeline('timeline', 960, 540);
        timeline.init('your_data_source_url');
    </script>
</body>
</html>

Deployment

Static Hosting

TimelineJS is a client-side JavaScript application that can be deployed to any static hosting service:

GitHub Pages: Perfect for documentation and demos
Netlify: Free static hosting with CDN
Vercel: Serverless deployment platform
AWS S3 + CloudFront: Scalable cloud hosting
Firebase Hosting: Google's static hosting solution

Steps for Static Deployment

Build your project: npm run build
Upload the contents of the dist folder to your hosting service
Ensure your data source is accessible (CORS enabled if cross-domain)

Troubleshooting

Common Issues

1. Timeline Not Loading

Problem: Timeline doesn't appear on the page Solution:

Check browser console for JavaScript errors
Verify the TimelineJS CSS and JS files are correctly linked
Ensure the container element (#timeline) exists in your HTML

2. Data Source Errors

Problem: "Loading timeline" message appears indefinitely Solution:

Verify your data source URL is correct and accessible
Check CORS settings if using a different domain for data
Validate your JSON data structure

3. Timeline Too Wide/Narrow

Problem: Timeline doesn't fit the container Solution:

Adjust the width parameter in your configuration
Ensure your container has appropriate CSS dimensions

4. Slides Not Displaying

Problem: Timeline loads but no slides are visible Solution:

Check your data source format (JSON structure must match TimelineJS requirements)
Verify date formats in your data are valid

5. Mobile Display Issues

Problem: Timeline doesn't work well on mobile devices Solution:

Set touch: true in your configuration
Test on actual mobile devices (emulators may not accurately represent behavior)

Debug Mode

Enable debug logging by adding this to your initialization:

timeline.init('your_data_source_url', {
    debug: true
});

This will output additional information to the browser console for troubleshooting.

How to Deploy & Use NUKnightLab/TimelineJS