From 45971dbc04214d19f4feb9360e877728b41978ed Mon Sep 17 00:00:00 2001 From: Nicolas Coden Date: Wed, 21 Mar 2018 21:52:38 +0100 Subject: [PATCH] docs: update & improve Js installation docs for UMD modules Changes: * remove section about "dist vs source files": only dist files should be imported for now * add import examples for ESM, AMD & CommonJS * simplify section about HTML imports --- docs/pages/javascript.md | 60 +++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/docs/pages/javascript.md b/docs/pages/javascript.md index f4c476dc5..65db0005d 100644 --- a/docs/pages/javascript.md +++ b/docs/pages/javascript.md @@ -11,47 +11,57 @@ You can get the Foundation JavaScript files from a ZIP download, package manager Once you have the files, add links to jQuery and Foundation as ` ``` -
-

Make sure Foundation loads after jQuery.

-
- -### Babel Required -Our JavaScript uses some features of ECMAScript 2015. **If you use Foundation with a build system, you'll need to compile our code to ES5.** We use [Babel](https://babeljs.io/) in our templates to do this. Babel has [plugins](https://babeljs.io/docs/setup/) for every build system imaginable, so integrating it into an existing setup is easy. +### Import in HTML -When configuring Babel to work with Foundation, you only need to include the `es2015` preset. At the root of your project, add a file called `.babelrc` with these contents to load that configuration: +You can import in your HTML the complete Foundation library `foundation.min.js` like above, but also each plugin individually. -```json -{ - "presets": ["es2015"] -} +```html + + + + + + ``` -### File Structure +Know that they all require `foundation.core.js` to be loaded *first*. Some plugins also require specific utility libraries that ship with Foundation—refer to a plugin's documentation to find out which plugins require what, and see the [JavaScript Utilities](javascript-utilities.html) page for more information. -All of Foundation's plugins ship both as importable ES2016 modules, and as individual precompiled "drop in" files, named `foundation.tabs.js`, `foundation.accordion.js`, and so on. These files are also combined into one big file called `foundation.js`, which allows you to get every plugin at once. The precompiled files live in the `dist` folder, while the importable modules live in the `js` folder. +
+

Loading many individual files like this creates a lot of network overhead, especially for users on mobile networks. To keep your pages loading quick, we recommend using a tool like Grunt or Gulp to combine all of your JavaScript files into one.

+
-If you're not familiar with module bundling, you'll probably want to reference the precompiled files from `dist`. +### Import in JavaScript -If you're only using certain plugins, know that they all require `foundation.core.js` and `foundation.util.mediaQuery.js` to be loaded *first*. Some plugins also require specific utility libraries that ship with Foundation—refer to a plugin's documentation to find out which plugins require what, and see the [JavaScript Utilities](javascript-utilities.html) page for more information. +Foundation is exported as [UMD modules](http://bob.yexley.net/umd-javascript-that-runs-anywhere/). This means that Foundation and its plugins can be imported in any JavaScript environnement. -```html - - - - - - +For example with [ES6](https://github.com/lukehoban/es6features#readme) (the ESM format): +```js +import Foundation from 'foundation-sites'; +const $dropdown = new Foundation.Dropdown('#mydropdown'); +// Or +import { Dropdown } from 'foundation-sites'; +const $dropdown = new Dropdown('#mydropdown'); ``` -
-

Loading many individual files like this creates a lot of network overhead, especially for users on mobile networks. To keep your pages loading quick, we recommend using a tool like Grunt or Gulp to combine all of your JavaScript files into one.

-
+With [RequireJs](http://requirejs.org/) (the AMD format): +```js +define(['foundation'], function(Foundation) { + var $dropdown = new Foundation.Dropdown('#mydropdown'); +}); +``` + +With [Node.js](https://www.safaribooksonline.com/library/view/learning-javascript-design/9781449334840/ch11s03.html) (the CommonJs format): +```js +var Foundation = require('foundation-sites'); +var $dropdown = new Dropdown('#mydropdown'); +``` --- -- 2.47.2