Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/walterra/d3-milestones
A d3 based timeline visualization.
https://github.com/walterra/d3-milestones
d3js dataviz timeline visualization
Last synced: 5 days ago
JSON representation
A d3 based timeline visualization.
- Host: GitHub
- URL: https://github.com/walterra/d3-milestones
- Owner: walterra
- License: other
- Created: 2018-01-02T15:10:15.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2023-01-24T15:42:00.000Z (almost 2 years ago)
- Last Synced: 2024-04-15T00:50:20.342Z (7 months ago)
- Topics: d3js, dataviz, timeline, visualization
- Language: JavaScript
- Homepage: https://walterra.github.io/d3-milestones
- Size: 5.23 MB
- Stars: 136
- Watchers: 11
- Forks: 25
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-starred - walterra/d3-milestones - A d3 based timeline visualization. (others)
README
[](https://www.npmjs.com/package/d3-milestones)
[](https://www.npmjs.com/package/d3-milestones)
[](https://www.npmjs.com/package/d3-milestones)
[](https://github.com/walterra/d3-milestones/actions/workflows/ci.yml)
# d3-milestones
A d3 based timeline visualization.
- NPM: https://www.npmjs.com/package/d3-milestones
- Github: https://github.com/walterra/d3-milestones
- Storybook demos: https://walterra.github.io/d3-milestones
If you're using `d3-milestones` out in the wild I'd love to see what you came up with, just ping me on [twitter.com/walterra](https://www.twitter.com/walterra).
## Installing
`yarn add d3-milestones`.
The most quick way to get going is to use `unpkg.com` as a CDN to include the library directly into your HTML file.
```html
milestones('#timeline')
.mapping({
'timestamp': 'year',
'text': 'title'
})
.parseTime('%Y')
.aggregateBy('year')
.render([
{ year: 789, title: 'Vikings begin attacks on England.' },
{ year: 840, title: 'Vikings found Dublin in Ireland.' }
...
{ year: 1050, title: 'The city of Oslo is founded in Norway.' },
{ year: 1066, title: 'Battle of Hastings.' }
]);
```
Head over here to see this example in action: https://beta.observablehq.com/@walterra/vikings-timeline.
## Examples
Examples are included using storybook:
- [Vikings Timeline](https://walterra.github.io/d3-milestones/?path=/story/d3-milestones--vikings)
- [Windows/macOS Timeline](https://walterra.github.io/d3-milestones/?path=/story/d3-milestones--os-category-labels)
## API Reference
### General Usage
To initialize *d3-milestones*, pass a DOM Id to its main factory:
```javascript
const vis = milestones('#wrapper');
```
The returned object exposes the following API:
# vis.aggregateBy(interval)
Sets the aggregation interval for the event data, where *interval* can be one of `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter` or `year`.
# vis.distribution(string)
Sets the label distribution, can be `top-bottom`, `top` or `bottom`. Defaults to `top-bottom`. The options don't change for vertical layouts. `top` refers to labels on the left and `bottom` to labels on the right for that layout.
# vis.mapping(configObject)
Sets overrides for the default attributes for the expected data structure of an event. This defaults to:
```js
{
category: undefined,
entries: undefined,
timestamp: 'timestamp',
text: 'text',
url: 'url'
};
```
The method allows you to override single or multiple attributes to map them to fields in your original data with a single call like:
```js
vis.mapping({
'timestamp': 'year',
'text': 'title'
})
```
# vis.optimize(boolean)
Enables/Disables the label optimizer. When enabled, the optimizer attempts to avoid label overlap by vertically displacing labels.
# vis.autoResize(boolean)
Enables/Disables auto resizing. Enabled by default, this adds listeners to resizing events of the browser window.
# vis.orientation(string)
Sets the orientation of the timeline, can be either `horizontal` or `vertical`. Defaults to `horizontal`.
# vis.parseTime(specifier)
Specifies the formatter for the timestamp field. The specifier string is expected to resemble a format described here: https://github.com/d3/d3-time-format#locale_format
# vis.labelFormat(specifier)
The `labelFormat` for the time label for each milestones defaults to `'%Y-%m-%d %H:%M'`. Using `aggregateBy`, `labelFormat` will be set automatically to a reasonable format corresponding to the aggregation level. Still, this method is available to override this behavior with a custom `labelFormat`.
# vis.urlTarget(string)
Customizes the `target` attribute when labels are provided with a URL. Can be `_blank`, `_self`, `_parent` or `_top`.
# vis.useLabels(boolean)
Enables/Disables the display of labels.
# vis.render([data])
When called without `data` this triggers re-rendering the existing visualization.
`data` is expected to be an array of event objects with fields matching either the expected defaults (`timestamp` and `text` attribute) or the provided mapping via `.mapping()`.
# vis.onEventClick(function)
Set a callback which is executed when the text or image is clicked.
```js
vis.onEventClick((d) => {
console.log('click', d);
alert(`
${d.text} | ${d.timestamp}
${JSON.stringify(d.attributes)}
`);
})
```
# vis.onEventMouseOver(function)
Set a callback which is executed when the mouse cursor is over text or image.
```js
vis.onEventMouseOver((d) => {
console.log('mouseover', d);
})
```
# vis.onEventMouseLeave(function)
Set a callback which is executed when the mouse cursor is leaving text or image.
```js
vis.onEventMouseLeave((d) => {
console.log('mouseleave', d);
})
```
## Disclaimer on DevOps/CI Observability
This repository uses [Elastic APM](https://www.elastic.co/observability/application-performance-monitoring) to track performance of functional tests. It uses `@elastic/apm-rum` as a `devDependency` to be run only as part of the tests. No telemetry library is part of the published package.
## More
`d3-milestones` is also available as a visualization plugin for Kibana here: https://github.com/walterra/kibana-milestones-vis