vis-timeline

repository·master·Indexed 25 days ago

https://github.com/visjs/vis-timeline

An interactive visualization library for creating fully customizable timelines with items and ranges. It supports single points in time, time ranges, and features such as zooming, dragging, and data manipulation using vis.DataSet for two-way data binding.

Tokens
6.7K
Snippets
10
Records
33
Agent score
82%

What's inside vis-timeline

  1. Generate documentation using JSDoc

    master

    You can generate documentation for the project using the jsdoc command line interface. The following command demonstrates how to use a configuration file, recurse into subdirectories, use a specific template, and specify output and source directories.

    jsdoc -c jsdoc.json -r -t docs -d gen/docs lib

    Flags:

    • -c: Specifies the configuration file (e.g., jsdoc.json).
    • -r: Recurse into subdirectories of the specified source directories.
    • -t: Specifies the path to the template (e.g., docs).
    • -d: Specifies the destination directory for generated HTML files (e.g., gen/docs).
    • The source files to be parsed are provided as positional arguments (e.g., lib).
  2. Choose the correct vis-timeline build

    master

    Depending on your environment (browser vs bundler) and dependency management needs, choose one of the following builds:

    1. Standalone build: No dependencies. Best for Minimal Working Examples (MWEs), but may cause bundle bloat or interoperability issues.

      • CDN: https://unpkg.com/vis-timeline@latest/standalone/umd/vis-timeline-graph2d.min.js
      • Import: import { Timeline } from "vis-timeline/standalone";
    2. Peer build: Requires you to load Vis Data and Moment (including locales except English) yourself. Good for interoperability with other packages.

      • CDN: https://unpkg.com/vis-timeline@latest/peer/umd/vis-timeline-graph2d.min.js
      • Import: import { Timeline } from "vis-timeline/peer";
    3. ESNext build: Similar to the peer build but without bundled dependencies or polyfills. Intended for use with bundlers like Rollup or Webpack.

      • CDN: https://unpkg.com/vis-timeline@latest/esnext/umd/vis-timeline-graph2d.min.js
      • Import: import { Timeline } from "vis-timeline/esnext";
    4. Legacy build: Deprecated. Only kept for backwards compatibility. Do not use for new projects.

  3. Build vis-timeline from source

    master

    To build the library from the source code:

    1. Clone the repository.
    2. Install dependencies using npm install.
    3. Run the build command.

    You can also exclude external dependencies (like moment or hammerjs) during the build process using the -e flag.

    # Clone and install
    $ git clone git://github.com/visjs/vis-timeline.git
    $ cd vis-timeline
    $ npm install
    
    # Build
    $ npm run build
    
    # Build excluding specific dependencies
    $ npm run build -- -e moment,hammerjs
  4. Control item editability

    master

    Editability can be controlled at the timeline level via options.editable or overridden at the individual item level via the editable property in the item data.

    Supported edit actions:

    • updateTime: Allows dragging the item to change its time.
    • updateGroup: Allows moving the item to a different group.
    • remove: Allows deleting the item.

    If options.editable.overrideItems is set to true, the item-level editable property will take precedence over the global timeline configuration.

  5. Create a range item for the timeline

    master

    A RangeItem is a type of timeline item that spans a duration between two points in time. To create one, provide an object containing both start and end properties. If either property is missing, an error will be thrown.

    Required data properties:

    • start: The beginning timestamp of the range.
    • end: The ending timestamp of the range.
    • id (optional): A unique identifier for the item.
    • content (optional): The text or HTML to display inside the range.
    • className (optional): A custom CSS class to apply to the item.
  6. Configure Item data and properties

    master

    When creating or updating items in the timeline, you provide a data object. The Item class (used internally by the timeline) consumes this object to define the item's appearance and behavior.

    Key properties in the data object include:

    • id: A unique identifier (should not be changed after creation).
    • start: The start time of the item.
    • end: The end time of the item (optional).
    • content: The HTML or text content to display inside the item.
    • group: The ID of the group this item belongs to.
    • subgroup: The ID of the subgroup this item belongs to.
    • className: A CSS class name to apply to the item.
    • style: Custom CSS styles to apply to the item.
    • selectable: Boolean indicating if the item can be selected (overrides global settings if options.editable.overrideItems is not true).
    • editable: Object or boolean to control specific editing capabilities (updateTime, updateGroup, remove).
  7. Understand ClusterItem in vis-timeline

    master

    A ClusterItem is a specialized item type used to represent a group of items that have been clustered together on the timeline. It acts as a visual proxy for multiple underlying items, typically used during zooming or when many items overlap.

    Key characteristics:

    • Automatic Range: It automatically calculates its own start and end dates based on the range of the items it contains.
    • Read-only: Cluster items are marked as editable: false by default.
    • Interaction: By default, double-clicking a cluster item triggers a fit event, which zooms the timeline to show all items within that cluster.
    • Visuals: It can display 'stripes' (lines and dots connecting to the axis) depending on the showStipes option.

    Note: ClusterItem is an internal class used by the timeline engine to manage item grouping; end-users typically interact with clusters through the timeline's high-level API rather than instantiating this class directly.

  8. Create background items for timeline visualization

    master

    A BackgroundItem is a specialized type of item used to render background elements (like shaded regions or annotations) behind regular timeline items.

    Key characteristics:

    • Non-selectable: Unlike standard items, background items are not attached to the DOM in a way that allows them to be selected by the user.
    • Non-stacking: They do not participate in the vertical stacking logic of regular items (they have stack: false).
    • Required Data: Every background item must include both a start and an end property.

    Data Structure

    When creating a background item, the data object must contain:

    • start: The start timestamp.
    • end: The end timestamp.
    • id: (Optional) A unique identifier.
    • content: (Optional) The content to display.
    • className: (Optional) A custom CSS class name.
    • subgroup: (Optional) The ID of the subgroup this background belongs to.

    Example Usage

    Note: While BackgroundItem is an internal class, it is used when providing data to the timeline that is intended to be rendered as a background. In the public API, this is typically handled by specifying the type: 'background' in your item data objects.

  9. Configure BoxItem data and options

    master

    A BoxItem is a type of timeline item that renders as a box. When creating or updating an item, you must provide a data object. The start property is mandatory and must be a valid timestamp.

    Data Object Properties:

    • start: (Required) The timestamp for the item's position.
    • content: The text or HTML content to display inside the box.
    • className: A custom CSS class name to apply to the item.
    • align: Controls how the item is aligned relative to its start time ('left', 'right', or 'center'). If not provided in data, it falls back to the global timeline options.align.

    Note: If start is missing from the data object, an error will be thrown.

  10. Basic usage of vis.Timeline and vis.DataSet

    master

    To create a timeline, you need a DOM container, a vis.DataSet containing your items, and an options object. The vis.DataSet allows for two-way data binding, making it easy to manage items. Items can represent single points in time or ranges (with start and end dates).

    <!doctype html>
    <html
      >
      <head>
        <title>Timeline</title>
        <script
          type="text/javascript"
          src="https://unpkg.com/vis-timeline@latest/standalone/umd/vis-timeline-graph2d.min.js"
        ></script>
        <link
          href="https://unpkg.com/vis-timeline@latest/styles/vis-timeline-graph2d.min.css"
          rel="stylesheet"
          type="text/css"
        />
        <style type="text/css">
          #visualization {
            width: 600px;
            height: 400px;
            border: 1px solid lightgray;
          }
        </style>
      </head>
      <body
        >
        <div id="visualization"></div
        <script type="text/javascript">
          // DOM element where the Timeline will be attached
          var container = document.getElementById("visualization");
    
          // Create a DataSet (allows two way data-binding)
          var items = new vis.DataSet([
            { id: 1, content: "item 1", start: "2014-04-20" },
            { id: 2, content: "item 2", start: "2014-04-14" },
            { id: 3, content: "item 3", start: "2014-04-18" },
            { id: 4, content: "item 4", start: "2014-04-16", end: "2014-04-19" },
            { id: 5, content: "item 5", start: "2014-04-25" },
            { id: 6, content: "item 6", start: "2014-04-27", type: "point" },
          ]);
    
          // Configuration for the Timeline
          var options = {};
    
          // Create a Timeline
          var timeline = new vis.Timeline(container, items, options);
        </script>
      </body
    </html>
  11. Access collected source data via `taffyData`

    master

    The publish() function accepts a parameter called taffyData. This is a table containing all data collected from the source code related to JSDoc generation. You can query this data using TaffyDB-style syntax to find specific classes, methods, or properties.

    Example: Filtering for a specific name

    var data = taffyData;
    var tmp = data().filter({ name: "Label" }).get();

    This returns an array of all items where the name property matches 'Label'. The resulting objects contain detailed metadata including comment, meta (filename, line number, path, and AST node info), params, kind, and scope.