Skip to content

Improve readme to get started with plotly.js JSON interface for non-JavaScript developers and adjust dist/README #5705

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jun 3, 2021
Merged

Improve readme to get started with plotly.js JSON interface for non-JavaScript developers and adjust dist/README #5705

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
66b80c0
revise README
archmoj Jun 2, 2021
a0bd258
revise readme
archmoj Jun 2, 2021
866ca5a
reorder items
archmoj Jun 2, 2021
fadac71
place mathjax note close to cdn
archmoj Jun 2, 2021
394d9f4
point to bundles - simplify dist/README
archmoj Jun 3, 2021
9d929b3
move up dist-min
archmoj Jun 3, 2021
4da8c59
revise stats and cleanup extra info
archmoj Jun 3, 2021
4bc79dd
rename and use dist in function and variable names
archmoj Jun 3, 2021
a2bccfd
add npm and CDN links for main bundles
archmoj Jun 3, 2021
d6b5498
add CUSTOM_BUNDLE file, how to install deps, more edits
archmoj Jun 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Alternative ways to require or build plotly.js
Depending on your needs, to bundle plotly.js into your application one of [the browserified distributed plotly.js packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) on npm could be used.
Depending on your needs you may require/import one of [the distributed plotly.js packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) or [a plotly.js/lib index file](https://github.com/plotly/plotly.js/tree/master/lib) and integrate it into your application.

The sections below provide additional info in respect to alternative building frameworks.

## Browserify example

Expand All @@ -16,10 +18,7 @@ then simply run
browserify index.js > bundle.js
```



The sections below provide additional info in respect to alternative building frameworks.

---
## Webpack

For plotly.js to build with Webpack you will need to install [ify-loader@v1.1.0+](https://github.com/hughsk/ify-loader) and add it to your `webpack.config.json`. This adds Browserify transform compatibility to Webpack which is necessary for some plotly.js dependencies.
Expand All @@ -39,6 +38,7 @@ A repo that demonstrates how to build plotly.js with Webpack can be found [here]
...
```

---
## Angular CLI

Since Angular uses webpack under the hood and doesn't allow easily to change it's webpack configuration, there is some work needed using a `custom-webpack` builder to get things going.
Expand Down Expand Up @@ -99,3 +99,4 @@ module.exports = {

It's important to set `projects.x.architect.build.builder` and `projects.x.architect.build.options.customWebpackConfig`.
If you have more projects in your `angular.json` make sure to adjust their settings accordingly.
---
56 changes: 56 additions & 0 deletions CUSTOM_BUNDLE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Custom bundle
You can simply make custom bundles yourself, if none of the [distributed packages](https://github.com/plotly/plotly.js/blob/master/dist/README.md) meet your needs, or you want to make a more optimized bundle file with/without specific traces and transforms.

Install plotly.js, move to plotly.js folder then install plotly.js dependencies:
```sh
npm i plotly.js@2.0.0-rc.2
cd node_modules/plotly.js
npm i
```

By default all traces and transforms are included in the bundle if you simply run:
```sh
npm run partial-bundle
```

Use the `traces` option to include just the trace types you need.
```sh
npm run partial-bundle -- --traces scatter,scattergl,scatter3d
```
Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
[This behaviour may change in the future](https://github.com/plotly/plotly.js/pull/5535), so we recommend that you explicitly include `scatter` anyway if you need it in your bundle.

Use the `transforms` option to specify which should be included.
```sh
npm run partial-bundle -- --transforms sort,filter
```

Or use `transforms none` to exclude them all.
```sh
npm run partial-bundle -- --transforms none
```

Use the `out` option to change the bundle filename (default `custom`).
The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
```sh
npm run partial-bundle -- --out myBundleName
```

Use the `unminified` option to disable compression.
```sh
npm run partial-bundle -- --unminified
```

# Example illustrating use of different options together
To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
```sh
npm run partial-bundle -- \
--unminified \
--out myScatters \
--traces scatter,scattergl,scatter3d \
--transforms none
```
Or simply on one line:
```sh
npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
```
167 changes: 67 additions & 100 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,21 +18,19 @@ Plotly.js can be used to produce dozens of chart types and visualizations, inclu

## Table of contents

* [Quick start options](#quick-start-options)
* [Partial bundles](#partial-bundles)
* [Load from npm (Node.js Package Manager)](#load-from-npm-nodejs-package-manager)
* [Load from Content Delivery Network (CDN)](#load-from-content-delivery-network-cdn)
* [Bundles](#bundles)
* [Alternative ways to require or build plotly.js](#alternative-ways-to-require-or-build-plotlyjs)
* [Bugs and feature requests](#bugs-and-feature-requests)
* [Documentation](#documentation)
* [Bugs and feature requests](#bugs-and-feature-requests)
* [Contributing](#contributing)
* [Community](#community)
* [Versioning](#versioning)
* [Notable contributors](#creators)
* [Notable contributors](#notable-contributors)
* [Copyright and license](#copyright-and-license)
* [Community](#community)

---
## Quick start options

### Install with npm
## Load from npm (Node.js Package Manager)

```sh
npm install plotly.js-dist-min
Expand All @@ -42,95 +40,66 @@ and import plotly.js as

```js
import Plotly from 'plotly.js-dist-min'
// Or using require,
```
Or
```js
var Plotly = require('plotly.js-dist-min')
```

### Use the plotly.js CDN hosted by Fastly
---
## Load from Content Delivery Network (CDN)
Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>.

#### A minified plotly.js X.Y.Z release
### Usage example
```html
<script src="https://cdn.plot.ly/plotly-1.58.4.min.js" charset="utf-8"></script>
<head>
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script>
</head>
<body>
<div id="gd"></div>

<script>
Plotly.newPlot("gd", {
"data": [{
"y": [1, 2, 3]
}],
"layout": {
"width": 600,
"height": 400
}
});
</script>
</body>
```
In the example above `Plotly` object is added to the window scope by the script in the `head` section.
The `newPlot` method is then used to draw an interactive figure as described by `data` and `layout` into the desired `div` here named `gd`.
As demonstrated in the example above basic knowledge of `html` and [JSON](https://en.wikipedia.org/wiki/JSON) syntax is enough to get started i.e. with/without JavaScript!
To learn and build more with plotly.js please visit [plotly.js documentation](https://plotly.com/javascript).

#### An un-minified version is also available
### Un-minified versions are also available on CDN
While non-minified source files may contain characters outside UTF-8, it is recommended that you specify the `charset` when loading those bundles.
```html
<script src="https://cdn.plot.ly/plotly-1.58.4.js" charset="utf-8"></script>
```

and use the `Plotly` object in the window scope.

##### Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.

Fastly supports Plotly.js with free CDN service. Read more at <https://www.fastly.com/open-source>

### Download the latest release or a release candidate (rc)

[Latest and rc releases on GitHub](https://github.com/plotly/plotly.js/releases/)

and use the plotly.js `dist` file(s). More info [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md).

#### Read the [Getting started page](https://plotly.com/javascript/getting-started/) for more examples.

---
## Partial bundles

There are two kinds of plotly.js partial bundles:
1. The official partial bundles that are distributed to `npm` and the CDN, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
2. Custom bundles you can create yourself, if none of the distributed packages meet your needs.

Use the `traces` option to include just the trace types you need.
```sh
npm run partial-bundle -- --traces scatter,scattergl,scatter3d
```
Please note that the `scatter` trace is currently included in all bundles and cannot be removed.
[This behaviour may change in the future](https://github.com/plotly/plotly.js/pull/5535), so we recommend that you explicitly include `scatter` anyway if you need it in your bundle.

By default all transforms are included in the bundle.
Use the `transforms` option to specify which should be included.
```sh
npm run partial-bundle -- --transforms sort,filter
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.js" charset="utf-8"></script>
```

Or use `transforms none` to exclude them all.
```sh
npm run partial-bundle -- --transforms none
```

Use the `out` option to change the bundle filename (default `custom`).
The new bundle will be created in the `dist/` directory and named `plotly-<out>.min.js` or `plotly-<out>.js` if unminified.
```sh
npm run partial-bundle -- --out myBundleName
```
> Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.4. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.

Use the `unminified` option to disable compression.
```sh
npm run partial-bundle -- --unminified
### To support MathJax
Load relevant MathJax (v2) files *Before* the plotly.js script tag:
```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script>
```

### Example illustrating use of different options together
To create an unminified custom bundle named `myScatters` including `scatter`, `scattergl` and `scatter3d` traces without any transforms:
```sh
npm run partial-bundle -- \
--unminified \
--out myScatters \
--traces scatter,scattergl,scatter3d \
--transforms none
```
Or simply on one line:
```sh
npm run partial-bundle -- --unminified --out myScatters --traces scatter,scattergl,scatter3d --transforms none
```
## Bundles
There are two kinds of plotly.js bundles:
1. Complete and partial official bundles that are distributed to `npm` and the `CDN`, described in [the dist README](https://github.com/plotly/plotly.js/blob/master/dist/README.md).
2. Custom bundles you can create yourself to optimize the size of bundle depending on your needs. Please visit [CUSTOM_BUNDLE](https://github.com/plotly/plotly.js/blob/master/CUSTOM_BUNDLE.md) for more information.

---
## Alternative ways to require or build plotly.js
If your library needs to bundle or directly require [plotly.js/lib/index.js](https://github.com/plotly/plotly.js/blob/master/lib/index.js) or parts of its modules similar to [index-basic](https://github.com/plotly/plotly.js/blob/master/lib/index-basic.js) in some other way than via an official or a custom bundle, or in case you want to tweak the default build configurations of `browserify` or `webpack`, etc. then please visit [`BUILDING.md`](https://github.com/plotly/plotly.js/blob/master/BUILDING.md).

---
## Bugs and feature requests

Have a bug or a feature request? Please [open a Github issue](https://github.com/plotly/plotly.js/issues/new) keeping in mind the [issue guidelines](https://github.com/plotly/plotly.js/blob/master/.github/ISSUE_TEMPLATE.md). You may also want to read about [how changes get made to Plotly.js](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md)

---
## Documentation

Expand All @@ -139,32 +108,16 @@ Official plotly.js documentation is hosted at [https://plotly.com/javascript](ht
These pages are generated by the Plotly [graphing-library-docs repo](https://github.com/plotly/graphing-library-docs) built with [Jekyll](https://jekyllrb.com/) and publicly hosted on GitHub Pages.
For more info about contributing to Plotly documentation, please read through [contributing guidelines](https://github.com/plotly/graphing-library-docs/blob/master/README.md).

### To support MathJax
Load relevant MathJax (v2) files *Before* the plotly.js script tag:
```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>
<script src="https://cdn.plot.ly/plotly-2.0.0-rc.2.min.js"></script>
```

---
## Contributing

Please read through our [contributing guidelines](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md). Included are directions for opening issues, using plotly.js in your project and notes on development.
## Bugs and feature requests

---
## Community
Have a bug or a feature request? Please [open a Github issue](https://github.com/plotly/plotly.js/issues/new) keeping in mind the [issue guidelines](https://github.com/plotly/plotly.js/blob/master/.github/ISSUE_TEMPLATE.md). You may also want to read about [how changes get made to Plotly.js](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md)

* Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news.
* Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or
on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).
* Developers should use the keyword `plotly` on packages which modify or add to the functionality of plotly.js when distributing through [npm](https://www.npmjs.com/browse/keyword/plotly).

---
## Versioning

This project is maintained under the [Semantic Versioning guidelines](https://semver.org/).
## Contributing

See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.
Please read through our [contributing guidelines](https://github.com/plotly/plotly.js/blob/master/CONTRIBUTING.md). Included are directions for opening issues, using plotly.js in your project and notes on development.

---
## Notable contributors
Expand Down Expand Up @@ -197,3 +150,17 @@ Plotly.js is at the core of a large and dynamic ecosystem with many contributors
Code and documentation copyright 2021 Plotly, Inc.

Code released under the [MIT license](https://github.com/plotly/plotly.js/blob/master/LICENSE).

### Versioning

This project is maintained under the [Semantic Versioning guidelines](https://semver.org/).

See the [Releases section](https://github.com/plotly/plotly.js/releases) of our GitHub project for changelogs for each release version of plotly.js.

---
## Community

* Follow [@plotlygraphs](https://twitter.com/plotlygraphs) on Twitter for the latest Plotly news.
* Implementation help may be found on community.plot.com (tagged [`plotly-js`](https://community.plotly.com/c/plotly-js)) or
on Stack Overflow (tagged [`plotly`](https://stackoverflow.com/questions/tagged/plotly)).
* Developers should use the keyword `plotly` on packages which modify or add to the functionality of plotly.js when distributing through [npm](https://www.npmjs.com/browse/keyword/plotly).
Loading