hangar-tech/biofriction-wp-theme
hangar-tech
/
biofriction-wp-theme
3
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
biofriction-wp-theme/node_modules/foundation-sites/docs/pages/javascript.md

12 KiB
Raw Blame History

title description video
JavaScript Our JavaScript is easy to set up and only requires jQuery to get going. Mf5ZZfKTe-I

Installing

You can get the Foundation JavaScript files from a ZIP download, package manager, or CDN. Check out the Installation page to learn more.

Once you have the files, add links to jQuery and Foundation as <script> tags at the bottom of your page, just before the closing <body> tag.

<!-- jQuery must be imported before Foundation -->
<script src="js/jquery.min.js"></script>
<!-- this will include every plugin and utility required by Foundation -->
<script src="js/foundation.min.js"></script>

Import in HTML

You can import in your HTML the complete Foundation library foundation.min.js like above, but also each plugin individually.

<!-- Example of selectively including files -->
<script src="js/jquery.min.js"></script> <!-- Required -->
<script src="js/foundation.core.min.js"></script>  <!-- Required -->
<script src="js/foundation.util.mediaQuery.min.js"></script>
<script src="js/foundation.tabs.min.js"></script>
<script src="js/foundation.accordion.min.js"></script>

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 page for more information.

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.

Import in JavaScript

By default, Foundation is exported as UMD modules. This means that Foundation and its plugins can be imported and used in any JavaScript environment.

For example with ES6 (the ESM format):

import Foundation from 'foundation-sites';
const $dropdown = new Foundation.Dropdown($('#mydropdown'));
// Or
import { Dropdown } from 'foundation-sites';
const $dropdown = new Dropdown($('#mydropdown'));

With RequireJs (the AMD format):

define(['foundation'], function(Foundation) {
  var $dropdown = new Foundation.Dropdown($('#mydropdown'));
});

With Node.js (the CommonJs format):

var Foundation = require('foundation-sites');
var $dropdown = new Dropdown($('#mydropdown'));

Available formats

Foundation is provided in bundles of various module formats so you can pick the one that matches the best your needs. If you don't know these terms yet, take a look at this 10-minute introduction to module formats in JavaScript. You will find in the dist/js folder the following bundles:

  • foundation.js UMD Default
    Compatible with most environments and tools (AMD, CJS, ESM...). It works almost everywhere by checking the module format of your environments and then using it, which makes the bundle a little heavier.

  • foundation.cjs.js CommonJS
    Dedicated to Node.js and older bundlers like Browserify or Webpack v1.

  • foundation.esm.js ES6 Modules (module in package.json)
    Everything is transpiled to ES5 but the modules. Dedicated to modern bundlers, like Webpack 2+ or Rollup. They will automatically use this bundle and parse the ES6 modules to remove the unused code (see tree shaking below).

  • foundation.es6.js ES6 (esnext in package.json)
    Unlike the other bundles, this bundle is not transpiled. It contains all the Foundation sources in ES6 in a single file. Use it if you want to manually transpile it for your own targets.

Tree Shaking

Many bundlers like Webpack, Rollup or Parcel support tree shaking. It consists of the removing the unused code parts from your codebase or your dependencies. Take a look at these articles to know how it works and how to enable it: How To Clean Up Your JavaScript Build With Tree Shaking, Why Webpack 2's Tree Shaking is not as effective as you think and Reduce JavaScript Payloads with Tree Shaking.

As tree shaking is only available in ES6, we recommend to import plugins like the following:

// Only Dropdown and DropdownMenu will be included in your application.
import { Dropdown, DropdownMenu } from 'foundation-sites';

Sadly, the "static analysis" promised by these bundlers to detect unused code in dependencies does not always work. Depending on your build environment, you may have to manually import the Foundation plugins to make it work correctly:

// /!\ Don't use this if tree shaking works with standard named imports.
// Only Dropdown and DropdownMenu will be included in your application.
import { Dropdown } from 'foundation-sites/js/foundation.dropdown';
import { DropdownMenu } from 'foundation-sites/js/foundation.dropdownMenu';

Initializing

The .foundation() function on the jQuery object will kick off every Foundation plugin at once.

$(document).foundation();

You can also selectively initialize plugins by calling the .foundation(); method on one or more elements with a plugin.

$('#foo').foundation(); // initialize all plugins within the element `#foo`
$('.has-tip').foundation(); // initialize all tooltips on the page.

Using Plugins

Plugins are attached to HTML elements using data attributes. The data attribute will match the name of the plugin. For example, adding data-accordion to an element creates an accordion, while adding data-tooltip creates a tooltip link.

<p><span data-tooltip aria-haspopup="true" class="has-tip" tabindex="1" title="Fancy word for a beetle.">Scarabaeus</span></p>

A single element can only have one Foundation plugin on it at a time. However, most plugins can be nested inside other ones.

Configuring Plugins

Each plugin has a set of configuration settings that customize how it works. For example, you change how fast an accordion slides up and down, or if tooltips should appear on touch devices.

Plugin settings can be changed globally by changing the DEFAULTS property on the plugin.

Foundation.Accordion.defaults.slideSpeed = 500;
Foundation.Accordion.defaults.multiExpand = true;

An individual instance of a plugin can also have different settings. These can be set in the HTML or in JavaScript.

In the HTML, each setting can be defined as an individual data attribute. Note that camelCased options are converted to hyphenated words. In the below example, `multiExpand` becomes `data-multi-expand`.

<div data-accordion data-slide-speed="500" data-multi-expand="true"></div>

Data options can also be set in bulk on one attribute, data-options. Options are written with the format key: value;, with a semicolon separating each option. The above example can be written using data-options like so:

<div data-accordion data-options="slideSpeed: 500; multiExpand: true;"></div>

There is one exception to this rule above, in the Sticky plugin. Because of the way you pass top and bottom anchors to that plugin, you can't include them in your data-options attribute. If you are using a single anchor or no declared anchor at all, you can still use data-options, and you can use it for all other options available.

Setting options with JavaScript involves passing an object into the constructor function, like this: 
var options = {multiExpand: true, allowAllClosed: false};
var accordion = new Foundation.Accordion($('#some-accordion'), options);

It's worth noting that options passed to plugins via JavaScript take the highest precedence, and will overwrite any default values or options applied via the data-some-option tag. This is also how the data-options="someOption:true; someOtherOption:false" options are passed into constructor functions. So, if you were to say:

<div data-accordion data-slide-speed="500" data-options="slideSpeed:250;">...</div>

your accordion element would have a slide speed of 250 milliseconds.

Adding Plugins After Page Load

If you add new HTML to the DOM, any plugins on those elements won't be initialized by default. Re-call the .foundation() function to check for new plugins.

$.ajax('assets/partials/kitten-carousel.html', function(data) {
  $('#kitten-carousel').html(data).foundation();
});

Adding Content to Plugins

In previous versions of Foundation, there was a method for plugins called reflow, though it's inclusion on plugins wasn't universal. For Foundation 6 we've added a global reInit method that will remove and reapply event listeners, update the plugin's instance data for relevant information, like a new tab or content pane being added, and reset any cached data the plugin may rely on.

This method can be called on a plugin class:

Foundation.reInit('tooltip');

an array of plugin classes:

Foundation.reInit(['tooltip', 'accordion', 'reveal']);

or an individual element or collection of elements selected with jQuery:

Foundation.reInit($('#some-plugin'));
Foundation.reInit($('.some-plugin-class'));

If passing strings, it is required to pass proper camelCased or kebab-cased plugin names. Passing DropdownMenu or dropdown-menu are equivalent.

Programmatic Use

Plugins can be created programmatically in JavaScript. Every plugin is a class on the global Foundation object, with a constructor that accepts two parameters: an element to attach to, and an object of options.

var $accordion = new Foundation.Accordion($('#accordion'), {
  slideSpeed: 500,
  multiExpand: true
});

Most plugins have a public API that allows you to manipulate it through JavaScript. Refer to a plugin's documentation to learn what functions are available. Invoking methods is easy as pie:

$('#reveal').foundation('open'); //will open a Reveal modal with id `reveal`.

$('[data-tabs]').eq(0).foundation('selectTab', $('#example')); //will change the first Tabs on the page to whatever panel you choose.

$('.tooltip').foundation('_destroy'); //will destroy all Tooltips on the page.

You can use any jQuery selector you like, and if the selector encompasses multiple plugins, they will all have the same the chosen method invoked. You pass arguments just like you would any in other JavaScript function(comma, delimited, so, easy). We did make an effort to reduce the number of public methods that require arguments, but check the plugin's page to see if it requires additional information.

If you are creating your plugins programmatically, you can, of course, invoke methods directly:

var $modal = new Foundation.Reveal($('#some-modal'), options);
$modal.open();

Plugin methods prefixed with an underscore are considered part of the internal API, which means they could change, break, or disappear without warning. We recommend sticking to only the public API, which is documented on each plugin's page.

Events

Every plugin fires DOM events when certain functions finish. For example, you can listen for when tabs change, or an off-canvas menu opens, and create a callback to respond to it.

$('[data-tabs]').on('change.zf.tabs', function() {
  console.log('Those tabs sure did change!');
});

Refer to each plugin's documentation to see a list of events it fires, and when they fire.

Starting with Foundation 6, we removed callbacks as plugin settings. All use of callbacks with plugins should be done as event listeners.