0
0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-04 16:24:22 +01:00
Bootstrap/docs/4.0/getting-started/javascript.md

135 lines
6.7 KiB
Markdown
Raw Normal View History

2014-07-12 11:20:15 +02:00
---
layout: docs
2015-04-05 08:31:41 +02:00
title: JavaScript
description: Bring Bootstrap to life with our optional JavaScript plugins built on jQuery. Learn about each plugin, our data and programmatic API options, and more.
group: getting-started
toc: true
2014-07-12 11:20:15 +02:00
---
2015-05-29 10:58:52 +02:00
## Individual or compiled
2014-03-17 03:03:53 +01:00
2015-03-09 16:35:45 +01:00
Plugins can be included individually (using Bootstrap's individual `*.js` files), or all at once using `bootstrap.js` or the minified `bootstrap.min.js` (don't include both).
2014-07-12 11:45:15 +02:00
2015-05-29 10:58:52 +02:00
## Dependencies
2014-07-12 11:45:15 +02:00
2017-09-05 00:29:05 +02:00
Some plugins and CSS components depend on other plugins. If you include plugins individually, make sure to check for these dependencies in the docs. Also note that **all plugins depend on jQuery** (this means jQuery must be included **before** the plugin files). [Consult our `package.json`]({{ site.repo }}/blob/v{{ site.current_version }}/package.json) to see which versions of jQuery are supported.
Our dropdowns, popovers and tooltips also depend on [Popper.js](https://popper.js.org/).
2014-03-17 03:03:53 +01:00
2015-05-29 10:58:52 +02:00
## Data attributes
2014-03-17 03:03:53 +01:00
2015-03-09 16:35:45 +01:00
Nearly all Bootstrap plugins can be enabled and configured through HTML alone with data attributes (our preferred way of using JavaScript functionality). Be sure to **only use one set of data attributes on a single element** (e.g., you cannot trigger a tooltip and modal from the same button.)
2014-03-17 03:03:53 +01:00
2015-03-09 16:35:45 +01:00
However, in some situations it may be desirable to disable this functionality. To disable the data attribute API, unbind all events on the document namespaced with `data-api` like so:
2014-03-17 03:03:53 +01:00
{% highlight js %}
$(document).off('.data-api')
{% endhighlight %}
2014-07-12 11:45:15 +02:00
Alternatively, to target a specific plugin, just include the plugin's name as a namespace along with the data-api namespace like this:
2014-03-17 03:03:53 +01:00
{% highlight js %}
$(document).off('.alert.data-api')
{% endhighlight %}
{% capture callout %}
##### Escaping selectors
If you use special selectors, for example: `collapse:Example`, be sure to escape them, because they'll be passed through jQuery.
{% endcapture %}
{% include callout.html content=callout type="warning" %}
## Events
Bootstrap provides custom events for most plugins' unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. `show`) is triggered at the start of an event, and its past participle form (ex. `shown`) is triggered on the completion of an action.
2017-06-17 03:59:43 +02:00
All infinitive events provide [`preventDefault()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault) functionality. This provides the ability to stop the execution of an action before it starts. Returning false from an event handler will also automatically call `preventDefault()`.
{% highlight js %}
$('#myModal').on('show.bs.modal', function (e) {
if (!data) return e.preventDefault() // stops modal from being shown
})
{% endhighlight %}
2015-05-29 10:58:52 +02:00
## Programmatic API
2014-07-12 11:45:15 +02:00
We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.
2014-03-17 03:03:53 +01:00
{% highlight js %}
$('.btn.danger').button('toggle').addClass('fat')
{% endhighlight %}
2014-07-12 11:45:15 +02:00
All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):
2014-03-17 03:03:53 +01:00
{% highlight js %}
$('#myModal').modal() // initialized with defaults
$('#myModal').modal({ keyboard: false }) // initialized with no keyboard
$('#myModal').modal('show') // initializes and invokes show immediately
{% endhighlight %}
2014-07-12 11:45:15 +02:00
Each plugin also exposes its raw constructor on a `Constructor` property: `$.fn.popover.Constructor`. If you'd like to get a particular plugin instance, retrieve it directly from an element: `$('[rel="popover"]').data('popover')`.
### Asynchronous functions and transitions
All programmatic API methods are **asynchronous** and returns to the caller once the transition is started but **before it ends**.
In order to execute an action once the transition is complete, you can listen to the corresponding event.
{% highlight js %}
$('#myCollapse').on('shown.bs.collapse', function (e) {
// Action to execute once the collapsible area is expanded
})
{% endhighlight %}
In addition a method call on a **transitioning component will be ignored**.
{% highlight js %}
$('#myCarousel').on('slid.bs.carousel', function (e) {
$('#myCarousel').carousel('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})
2014-07-12 11:45:15 +02:00
$('#myCarousel').carousel('1') // Will start sliding to the slide 1 and returns to the caller
$('#myCarousel').carousel('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!
{% endhighlight %}
### Default settings
2017-09-26 13:50:35 +02:00
You can change the default settings for a plugin by modifying the plugin's `Constructor.Default` object:
2014-03-17 03:03:53 +01:00
{% highlight js %}
$.fn.modal.Constructor.Default.keyboard = false // changes default for the modal plugin's `keyboard` option to false
2014-03-17 03:03:53 +01:00
{% endhighlight %}
## No conflict
2014-07-12 11:45:15 +02:00
Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call `.noConflict` on the plugin you wish to revert the value of.
2014-07-12 11:45:15 +02:00
2014-03-17 03:03:53 +01:00
{% highlight js %}
var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
2014-03-17 03:03:53 +01:00
{% endhighlight %}
2015-05-29 10:58:52 +02:00
## Version numbers
Merge branch 'master' into v4 Conflicts: Gruntfile.js dist/css/bootstrap-theme.css dist/css/bootstrap-theme.css.map dist/css/bootstrap-theme.min.css dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css dist/js/bootstrap.min.js docs/_data/glyphicons.yml docs/_includes/components/alerts.html docs/_includes/components/badges.html docs/_includes/components/breadcrumbs.html docs/_includes/components/button-dropdowns.html docs/_includes/components/button-groups.html docs/_includes/components/dropdowns.html docs/_includes/components/glyphicons.html docs/_includes/components/input-groups.html docs/_includes/components/jumbotron.html docs/_includes/components/labels.html docs/_includes/components/list-group.html docs/_includes/components/media.html docs/_includes/components/navbar.html docs/_includes/components/navs.html docs/_includes/components/page-header.html docs/_includes/components/pagination.html docs/_includes/components/panels.html docs/_includes/components/progress-bars.html docs/_includes/components/responsive-embed.html docs/_includes/components/thumbnails.html docs/_includes/components/wells.html docs/_includes/css/buttons.html docs/_includes/css/code.html docs/_includes/css/forms.html docs/_includes/css/grid.html docs/_includes/css/helpers.html docs/_includes/css/images.html docs/_includes/css/less.html docs/_includes/css/tables.html docs/_includes/css/type.html docs/_includes/customizer-variables.html docs/_includes/getting-started/accessibility.html docs/_includes/getting-started/disabling-responsiveness.html docs/_includes/getting-started/download.html docs/_includes/getting-started/whats-included.html docs/_includes/js/alerts.html docs/_includes/js/buttons.html docs/_includes/js/carousel.html docs/_includes/js/collapse.html docs/_includes/js/modal.html docs/_includes/js/overview.html docs/_includes/js/popovers.html docs/_includes/js/tabs.html docs/_includes/js/tooltips.html docs/_includes/nav/components.html docs/_includes/nav/javascript.html docs/_jade/customizer-variables.jade docs/_layouts/default.html docs/about.html docs/assets/css/docs.min.css docs/assets/css/src/docs.css docs/assets/js/customize.min.js docs/assets/js/raw-files.min.js docs/assets/js/src/customizer.js docs/customize.html docs/dist/css/bootstrap-theme.css.map docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css less/glyphicons.less less/mixins/vendor-prefixes.less less/navbar.less less/popovers.less less/tables.less less/theme.less less/tooltip.less less/variables.less package.json scss/_carousel.scss scss/_close.scss scss/_forms.scss test-infra/npm-shrinkwrap.json
2015-01-04 05:08:58 +01:00
The version of each of Bootstrap's jQuery plugins can be accessed via the `VERSION` property of the plugin's constructor. For example, for the tooltip plugin:
{% highlight js %}
$.fn.tooltip.Constructor.VERSION // => "{{ site.current_version }}"
{% endhighlight %}
2015-05-29 10:58:52 +02:00
## No special fallbacks when JavaScript is disabled
Merge branch 'master' into derp Conflicts: _config.yml dist/css/bootstrap-theme.css.map dist/css/bootstrap.css dist/css/bootstrap.css.map dist/css/bootstrap.min.css docs/_includes/components/glyphicons.html docs/_includes/css/forms.html docs/_includes/css/tables.html docs/_includes/getting-started/browser-device-support.html docs/_includes/header.html docs/_includes/js/affix.html docs/_includes/js/alerts.html docs/_includes/js/buttons.html docs/_includes/js/dropdowns.html docs/_includes/js/overview.html docs/_includes/js/popovers.html docs/_includes/js/tooltips.html docs/_includes/nav/javascript.html docs/assets/css/docs.min.css docs/assets/css/src/docs.css docs/assets/js/customize.min.js docs/assets/js/docs.min.js docs/assets/js/raw-files.min.js docs/browser-bugs.html docs/dist/css/bootstrap-theme.css.map docs/dist/css/bootstrap.css docs/dist/css/bootstrap.css.map docs/dist/css/bootstrap.min.css docs/examples/blog/index.html docs/examples/carousel/index.html docs/examples/cover/index.html docs/examples/dashboard/index.html docs/examples/grid/index.html docs/examples/jumbotron-narrow/index.html docs/examples/jumbotron/index.html docs/examples/justified-nav/index.html docs/examples/navbar-fixed-top/index.html docs/examples/navbar-static-top/index.html docs/examples/navbar/index.html docs/examples/non-responsive/index.html docs/examples/offcanvas/index.html docs/examples/signin/index.html docs/examples/starter-template/index.html docs/examples/sticky-footer-navbar/index.html docs/examples/sticky-footer/index.html docs/examples/theme/index.html docs/examples/tooltip-viewport/index.html less/code.less less/panels.less less/variables.less
2014-08-03 03:30:59 +02:00
Bootstrap's plugins don't fall back particularly gracefully when JavaScript is disabled. If you care about the user experience in this case, use [`<noscript>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/noscript) to explain the situation (and how to re-enable JavaScript) to your users, and/or add your own custom fallbacks.
{% capture callout %}
##### Third-party libraries
**Bootstrap does not officially support third-party JavaScript libraries** like Prototype or jQuery UI. Despite `.noConflict` and namespaced events, there may be compatibility problems that you need to fix on your own.
{% endcapture %}
{% include callout.html content=callout type="warning" %}
## Util
All Bootstrap's JavaScript files depend on `util.js` and it has to be included alongside the other JavaScript files. If you're using the compiled (or minified) `bootstrap.js`, there is no need to include this—it's already there.
`util.js` includes utility functions and a basic helper for `transitionEnd` events as well as a CSS transition emulator. It's used by the other plugins to check for CSS transition support and to catch hanging transitions.