TimelineJS3 Documentation

TimelineJS3 distinguishes between two types of indices:

1. event_index: An index into the sorted array of events in the timeline data object.
2. slide_index: The index of the slide as it appears in the rendered timeline.

Index Mapping Rules:

• A title slide has no event_index and has slide_index 0.
• If a title exists: The first event has event_index 0 and slide_index 1.
• If no title exists: The first event has event_index 0 and slide_index 0.

TimelineJS requires images to be hosted on a service that allows direct access without cross-domain restrictions. You can use three main categories of services:

1. Image hosting services: Services like Flickr, Instagram, or Google Photos where you provide the URL of the image page or the direct image link.
2. Object/file hosting services: Services like GitHub, AWS S3, or DigitalOcean Spaces that host files as objects. These are often more reliable for direct linking.
3. Web/Cloud hosting services: Standard web servers or cloud instances (e.g., AWS EC2, DigitalOcean Droplets, GCP Compute Engine) where you manage the file hosting via FTP, SSH, or dashboards.

Important: Avoid services that implement strict cross-domain restrictions (like Imgur) or services that have changed their hosting compatibility (like Dropbox).

Using Box for image hosting is experimental. To ensure compatibility, follow these steps to get the correct direct image link:

1. Click the Share button for the image in Box.
2. Select Enable Shared Link.
3. Set permissions to: People with the link can view and download.
4. Copy the shared link, but do not paste it into your spreadsheet yet.
5. Open that link in a new browser window.
6. Right-click the image in the viewer and select Copy image location (or similar).
7. Paste this direct image location into your spreadsheet.

To embed a TimelineJS3 timeline within an iBooks Author project, you must use the HTML widget format. This requires a .wdgt package containing specific .html, .plist, and image files.

Steps to embed:

1. Open your project in iBooks Author.
2. Navigate to Widgets > HTML.
3. In the Widget dialog, click the Choose ... button.
4. Select the TimelinJS.wdgt file (located in contrib/examples/iBooksAuthor/).
5. Click Insert.
6. Use the Preview button to verify the timeline is working correctly.

To use images stored in a GitHub repository for your Timeline:

1. Navigate to the image file within your repository on GitHub.
2. Click the Download button (or the 'Raw' button) to open the direct, raw image URL in your browser.
3. Copy this raw URL and paste it into your Timeline spreadsheet.

iBooks Author may not handle percentage-based dimensions reliably. When configuring the widget, follow these dimensioning practices:

• Use Explicit Values: Set explicit height and width values in both the .plist specification and the index.html file.
• Avoid Edge Cutoff: To prevent the edges of the timeline from being cut off, set the dimensions in the .plist file to be slightly larger than the dimensions defined in the index.html file.
• Test Viewports: Since responsive layout behavior is uncertain in iBooks Author, manually test the widget across various expected viewports.

The recommended way to update the TimelineJS icon font after making changes in IcoMoon is to use the provided automation script. This prevents errors caused by IcoMoon reassigning unicode values to existing icons.

Prerequisites:

• An extracted IcoMoon ZIP download.
• fonttools and brotli installed via pip if you want the script to automatically generate WOFF2 files: pip install fonttools brotli.

Steps:

1. Extract your IcoMoon ZIP to a temporary folder.
2. Run the update script pointing to that folder:

   node tasks/update_icons.js /path/to/icomoon-download

3. Build the project to apply changes:

   npm run build

To deploy updates to the JavaScript library, you must have a local copy of the cdn.knightlab.com repository located in the same parent directory as your TimelineJS3 repository.

Before deploying, ensure you have:

1. Thoroughly tested all changes.
2. Updated CHANGELOG with the changes and release date.
3. Updated package.json with the new version number.

Deployment is performed using npm scripts. To stage a new release and update the /latest/ directory, use npm run stage_latest. This script will prompt for a version number (tag), build the code, and copy it to both the versioned subdirectory and the /latest/ directory in the cdn.knightlab.com repository.

Note: Running these scripts does not complete the deployment. You must manually switch to the cdn.knightlab.com repository, commit the new code, and deploy that repository to finish the process.

When using Google Photos (photos.google.com), do not use the standard 'share link' or the URL in the browser address bar, as these are not direct image links.

Correct Method:

1. Open the specific image in Google Photos.
2. Right-click the image itself.
3. Select the option to copy the image link/address.
4. Use this direct link in your spreadsheet.

If you are using a Content Management System (CMS), you can use existing plugins to facilitate the embedding process instead of manual HTML snippets:

• WordPress: Use the Knight Lab TimelineJS plugin.
• MediaWiki: Use the Modern Timeline extension.
• Drupal: Use the Views TimelineJS module.