Merge pull request #202 from plotly/expose-trace-modules

Expose trace modules

Author: mdtusz

.npmignore

@@ -9,3 +9,12 @@ test
 dist/extras/mathjax
 
 circle.yml
+docker-compose.yml
+bower.json
+
+.ackrc
+.agignore
+.eslintignore
+.eslintrc
+
+npm-debug.log

CONTRIBUTING.md

@@ -106,9 +106,10 @@ To view the results of a run on CircleCI, download the `build/test_images/` and
 ### Repo organization
 
 - Distributed files are in `dist/`
+- CommonJS require-able modules are in `lib/`
 - Sources files are in `src/`, including the index
 - Build and repo management scripts are in `tasks/`
-- All tasks can be run using [`npm run-srcript`](https://docs.npmjs.com/cli/run-script)
+- All tasks can be run using [`npm run-script`](https://docs.npmjs.com/cli/run-script)
 - Tests are `test/`, they are partitioned into `image` and `jasmine` tests
 - Test dashboard and image viewer code is in `devtools/`
 - Non-distributed, built files are in `build/` (most files in here are git-ignored, the css and font built files are exceptions)

README.md

@@ -1,6 +1,6 @@
 <a href="https://plot.ly/javascript/"><img src="http://images.plot.ly/logo/[email protected]" height="70"></a>
 
-[![npm version](https://badge.fury.io/js/plotly.js.svg)](https://badge.fury.io/js/plotly.js) 
+[![npm version](https://badge.fury.io/js/plotly.js.svg)](https://badge.fury.io/js/plotly.js)
 [![circle ci](https://circleci.com/gh/plotly/plotly.js.png?&style=shield&circle-token=1f42a03b242bd969756fc3e53ede204af9b507c0)](https://circleci.com/gh/plotly/plotly.js)
 
 Built on top of [d3.js](http://d3js.org/) and [stack.gl](http://stack.gl/),
@@ -10,6 +10,7 @@ chart types, including 3D charts, statistical graphs, and SVG maps.
 ## Table of contents
 
 * [Quick start options](#quick-start-options)
+* [Modules](#modules)
 * [Bugs and feature requests](#bugs-and-feature-requests)
 * [Documentation](#documentation)
 * [Contributing](#contributing)
@@ -38,9 +39,46 @@ npm install plotly.js
 ```html
 <!-- Latest compiled and minified plotly.js JavaScript -->
 <script type="text/javascript" src="https://cdn.plot.ly/plotly-latest.min.js"></script>
+
+<!-- OR use a specific plotly.js release (e.g. version 1.5.0)-->
+<script type="text/javascript" src="https://cdn.plot.ly/plotly-1.5.0.min.js"></script>
 ```
 
-Read the [Getting started page](https://plot.ly/javascript/getting-started/) for examples.
+Read the [Getting started page](https://plot.ly/javascript/getting-started/) for more examples.
+
+## Modules
+
+If you would like to reduce the bundle size of plotly.js, you can create a *custom* bundle by using `plotly.js/lib/core`, and loading only the trace types that you need (e.g. `pie` or `choropleth`). The recommended way to do this is by creating a *bundling file*: 
+
+```javascript
+// in custom-plotly.js
+var plotlyCore = require('plotly.js/lib/core');
+
+// Load in the trace types for pie, and choropleth
+plotlyCore.register([
+    require('plotly.js/lib/pie'),
+    require('plotly.js/lib/choropleth');
+]);
+
+module.exports = customPlotly;
+```
+
+Then elsewhere in your code:
+
+```javascript
+var Plotly = require('./path/to/custom-plotly');
+```
+
+**IMPORTANT**: the plotly.js code base contains some non-ascii characters. Therefore, please make sure to set the `chartset` attribute to `"utf-8"` in the script tag that imports your plotly.js bundle. For example:
+
+```html
+<script type="text/javascript" src="my-plotly-bundle.js" charset="utf-8"></script>
+```
+
+
+#### Webpack Usage with Modules
+
+Browserify [transforms](https://github.com/substack/browserify-handbook#transforms) are required to build plotly.js, namely, [glslify](https://github.com/stackgl/glslify) to transform WebGL shaders and [cwise](https://github.com/scijs/cwise) to compile component-wise array operations. To make the trace module system work with Webpack, you will need to install [ify-loader](https://github.com/hughsk/ify-loader) and add it to your `webpack.config.json` for your build to correctly bundle plotly.js files.
 
 ## Bugs and feature requests
 

lib/bar.js

@@ -0,0 +1,9 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+module.exports = require('../src/traces/bar');

lib/box.js

@@ -0,0 +1,9 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+module.exports = require('../src/traces/box');

lib/choropleth.js

@@ -0,0 +1,9 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+module.exports = require('../src/traces/choropleth');

lib/contour.js

@@ -0,0 +1,9 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+module.exports = require('../src/traces/contour');

lib/core.js

@@ -0,0 +1,9 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+module.exports = require('../src/core');

lib/heatmap.js

@@ -0,0 +1,9 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+module.exports = require('../src/traces/heatmap');

lib/histogram.js

@@ -0,0 +1,9 @@
+/**
+* Copyright 2012-2016, Plotly, Inc.
+* All rights reserved.
+*
+* This source code is licensed under the MIT license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+
+module.exports = require('../src/traces/histogram');