@@ -49,39 +49,95 @@ properties once, and handle the actual animation with transforms.
### Page-specific JavaScript
Certain pages may require the use of a third party library, such as [d3][d3] for
the User Activity Calendar and [Chart.js][chartjs] for the Graphs pages. These
libraries increase the page size significantly, and impact load times due to
bandwidth bottlenecks and the browser needing to parse more JavaScript.
In cases where libraries are only used on a few specific pages, we use
"page-specific JavaScript" to prevent the main `main.js` file from
becoming unnecessarily large.
Steps to split page-specific JavaScript from the main `main.js`:
1. Create a directory for the specific page(s), e.g. `graphs/`.
1. In that directory, create a `namespace_bundle.js` file, e.g. `graphs_bundle.js`.
1. Add the new "bundle" file to the list of entry files in `config/webpack.config.js`.
- For example: `graphs: './graphs/graphs_bundle.js',`.
1. Move code reliant on these libraries into the `graphs` directory.
1. In `graphs_bundle.js` add CommonJS `require('./path_to_some_component.js');` statements to load any other files in this directory. Make sure to use relative urls.
1. In the relevant views, add the scripts to the page with the following:
```haml
-content_for:page_specific_javascriptsdo
=webpack_bundle_tag'lib_chart'
=webpack_bundle_tag'graphs'
```
The above loads `chart.js` and `graphs_bundle.js` for this page only. `chart.js`
is separated from the bundle file so it can be cached separately from the bundle
and reused for other pages that also rely on the library. For an example, see
[this Haml file][page-specific-js-example].
Webpack has been configured to automatically generate entry point bundles based
on the file structure within `app/assets/javascripts/pages/*`. The directories
within the `pages` directory are meant to correspond to Rails controllers and
actions. These auto-generated bundles will be automatically included on the
corresponding pages.
For example, if you were to visit [gitlab.com/gitlab-org/gitlab-ce/issues](https://gitlab.com/gitlab-org/gitlab-ce/issues),
you would be accessing the `app/controllers/projects/issues_controller.rb`
controller with the `index` action. If a corresponding file exists at
`pages/projects/issues/index/index.js`, it will be compiled into a webpack
bundle and included on the page.
> **Note:** Previously we had encouraged the use of
> `content_for :page_specific_javascripts` within haml files, along with
> manually generated webpack bundles. However under this new system you should
> not ever need to manually add an entry point to the `webpack.config.js` file.
In addition to these page-specific bundles, the code within `main.js` and
`commons/index.js` are imported on _all_ pages.
#### Important Tips and Considerations:
- If you are unsure what controller and action corresponds to a given page, you
can find this out by checking `document.body.dataset.page` while on any page
within gitlab.com.
- Since `main.js` and `commons/index.js` are imported on all pages, it is
important to not add anything to these bundles unless it is truly needed
_everywhere_. This includes ubiquitous libraries like `vue`, `axios`, and
`jQuery`, as well as code for the main navigation and sidebar.
- Page-specific javascript entry points should be as lite as possible. These
files are exempt from tests, and should be used primarily for instantiation
and dependency injection of classes and methods that live in modules outside
of the entry point script. Just import, read the DOM, instantiate, and
nothing else.
-**DO NOT ASSUME** that the DOM has been fully loaded and available when an
entry point script is run. If you require that some code be run after the
DOM has loaded, you must attach an event handler to the `DOMContentLoaded`
