diff options
Diffstat (limited to 'site/content/docs/5.2/getting-started/javascript.md')
| -rw-r--r-- | site/content/docs/5.2/getting-started/javascript.md | 155 |
1 files changed, 100 insertions, 55 deletions
diff --git a/site/content/docs/5.2/getting-started/javascript.md b/site/content/docs/5.2/getting-started/javascript.md index 0b79ef8912..fa157e006c 100644 --- a/site/content/docs/5.2/getting-started/javascript.md +++ b/site/content/docs/5.2/getting-started/javascript.md @@ -10,7 +10,7 @@ toc: true Plugins can be included individually (using Bootstrap's individual `js/dist/*.js`), or all at once using `bootstrap.js` or the minified `bootstrap.min.js` (don't include both). -If you use a bundler (Webpack, Rollup...), you can use `/js/dist/*.js` files which are UMD ready. +If you use a bundler (Webpack, Parcel, Vite...), you can use `/js/dist/*.js` files which are UMD ready. ## Usage with JavaScript frameworks @@ -19,7 +19,7 @@ While the Bootstrap CSS can be used with any framework, **the Bootstrap JavaScri A better alternative for those using this type of frameworks is to use a framework-specific package **instead of** the Bootstrap JavaScript. Here are some of the most popular options: - React: [React Bootstrap](https://react-bootstrap.github.io/) -- Vue: [BootstrapVue](https://bootstrap-vue.org/) +- Vue: [BootstrapVue](https://bootstrap-vue.org/) (currently only supports Vue 2 and Bootstrap 4) - Angular: [ng-bootstrap](https://ng-bootstrap.github.io/) ## Using Bootstrap as a module @@ -89,22 +89,19 @@ To fix this, you can use an `importmap` to resolve the arbitrary module names to Some plugins and CSS components depend on other plugins. If you include plugins individually, make sure to check for these dependencies in the docs. -Our dropdowns, popovers and tooltips also depend on [Popper](https://popper.js.org/). - -## Still want to use jQuery? It's possible! - -Bootstrap 5 is designed to be used without jQuery, but it's still possible to use our components with jQuery. **If Bootstrap detects `jQuery` in the `window` object** it'll add all of our components in jQuery's plugin system; this means you'll be able to do `$('[data-bs-toggle="tooltip"]').tooltip()` to enable tooltips. The same goes for our other components. +Our dropdowns, popovers, and tooltips also depend on [Popper](https://popper.js.org/). ## Data attributes 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.) -{{< callout warning >}} +{{< markdown >}} +{{< partial "js-data-attributes.md" >}} +{{< /markdown >}} + ## Selectors -Currently to query DOM elements we use the native methods `querySelector` and `querySelectorAll` for performance reasons, so you have to use [valid selectors](https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier). -If you use special selectors, for example: `collapse:Example` be sure to escape them. -{{< /callout >}} +We use the native `querySelector` and `querySelectorAll` methods to query DOM elements for performance reasons, so you must use [valid selectors](https://www.w3.org/TR/CSS21/syndata.html#value-def-identifier). If you use special selectors like `collapse:Example`, be sure to escape them. ## Events @@ -113,7 +110,7 @@ Bootstrap provides custom events for most plugins' unique actions. Generally, th 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()`. ```js -const myModal = document.getElementById('myModal') +const myModal = document.querySelector('#myModal') myModal.addEventListener('show.bs.modal', event => { if (!data) { @@ -122,58 +119,62 @@ myModal.addEventListener('show.bs.modal', event => { }) ``` -{{< callout warning >}} -## jQuery events +## Programmatic API -Bootstrap will detect jQuery if `jQuery` is present in the `window` object and there is no `data-bs-no-jquery` attribute set on `<body>`. If jQuery is found, Bootstrap will emit events thanks to jQuery's event system. So if you want to listen to Bootstrap's events, you'll have to use the jQuery methods (`.on`, `.one`) instead of `addEventListener`. +All constructors accept an optional options object or nothing (which initiates a plugin with its default behavior): ```js -$('#myTab a').on('shown.bs.tab', () => { - // do something... -}) -``` -{{< /callout >}} +const myModalEl = document.querySelector('#myModal') -## Programmatic API +const modal = new bootstrap.Modal(myModalEl) // initialized with defaults -All constructors accept an optional options object or nothing (which initiates a plugin with its default behavior): +const configObject = { keyboard: false } +const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard +``` + +If you'd like to get a particular plugin instance, each plugin exposes a `getInstance` method. For example, to retrieve an instance directly from an element: ```js -const myModalEl = document.getElementById('myModal') +bootstrap.Popover.getInstance(myPopoverEl) +``` -const modal = new bootstrap.Modal(myModalEl) // initialized with defaults -const modal1 = new bootstrap.Modal(myModalEl, { keyboard: false }) // initialized with no keyboard +This method will return `null` if an instance is not initiated over the requested element. + +Alternatively, `getOrCreateInstance` can be used to get the instance associated with a DOM element, or create a new one in case it wasn't initialized. + +```js +bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject) ``` -If you'd like to get a particular plugin instance, each plugin exposes a `getInstance` method. In order to retrieve it directly from an element, do this: `bootstrap.Popover.getInstance(myPopoverEl)`. +In case an instance wasn't initialized, it may accept and use an optional configuration object as second argument. ### CSS selectors in constructors -You can also use a CSS selector as the first argument instead of a DOM element to initialize the plugin. Currently the element for the plugin is found by the `querySelector` method since our plugins support a single element only. +In addition to the `getInstance` and `getOrCreateInstance` methods, all plugin constructors can accept a DOM element or a valid [CSS selector](#selectors) as the first argument. Plugin elements are found with the `querySelector` method since our plugins only support a single element. ```js const modal = new bootstrap.Modal('#myModal') const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]') +const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas') +const alert = bootstrap.Alert.getOrCreateInstance('#myAlert') ``` ### Asynchronous functions and transitions -All programmatic API methods are **asynchronous** and return 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. +All programmatic API methods are **asynchronous** and return 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. ```js -const myCollapseEl = document.getElementById('myCollapse') +const myCollapseEl = document.querySelector('#myCollapse') myCollapseEl.addEventListener('shown.bs.collapse', event => { // Action to execute once the collapsible area is expanded }) ``` -In addition a method call on a **transitioning component will be ignored**. +In addition, a method call on a **transitioning component will be ignored**. ```js -const myCarouselEl = document.getElementById('myCarousel') +const myCarouselEl = document.querySelector('#myCarousel') const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance myCarouselEl.addEventListener('slid.bs.carousel', event => { @@ -184,41 +185,46 @@ carousel.to('1') // Will start sliding to the slide 1 and returns to the caller carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !! ``` -### Default settings +#### `dispose` method -You can change the default settings for a plugin by modifying the plugin's `Constructor.Default` object: +While it may seem correct to use the `dispose` method immediately after `hide()`, it will lead to incorrect results. Here's an example of the problem use: ```js -// changes default for the modal plugin's `keyboard` option to false -bootstrap.Modal.Default.keyboard = false -``` - -## No conflict (only if you use jQuery) - -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. +const myModal = document.querySelector('#myModal') +myModal.hide() // it is asynchronous -```js -const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value -$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality +myModal.addEventListener('shown.bs.hidden', event => { + myModal.dispose() +}) ``` -## Version numbers +### Default settings -The version of each of Bootstrap's plugins can be accessed via the `VERSION` property of the plugin's constructor. For example, for the tooltip plugin: +You can change the default settings for a plugin by modifying the plugin's `Constructor.Default` object: ```js -bootstrap.Tooltip.VERSION // => "{{< param current_version >}}" +// changes default for the modal plugin's `keyboard` option to false +bootstrap.Modal.Default.keyboard = false ``` -## No special fallbacks when JavaScript is disabled +## Methods and properties -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. +Every Bootstrap plugin exposes the following methods and static properties. -{{< callout warning >}} -##### Third-party libraries +{{< bs-table "table" >}} +| Method | Description | +| --- | --- | +| `dispose` | Destroys an element's modal. (Removes stored data on the DOM element) | +| `getInstance` | *Static* method which allows you to get the modal instance associated with a DOM element. | +| `getOrCreateInstance` | *Static* method which allows you to get the modal instance associated with a DOM element, or create a new one in case it wasn't initialized. | +{{< /bs-table >}} -**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. -{{< /callout >}} +{{< bs-table "table" >}} +| Static property | Description | +| --- | --- | +| `NAME` | Returns the plugin name. (Example: `bootstrap.Tooltip.NAME`) | +| `VERSION` | The version of each of Bootstrap's plugins can be accessed via the `VERSION` property of the plugin's constructor (Example: `bootstrap.Tooltip.VERSION`) | +{{< /bs-table >}} ## Sanitizer @@ -283,10 +289,49 @@ myDefaultAllowList['*'].push(myCustomRegex) If you want to bypass our sanitizer because you prefer to use a dedicated library, for example [DOMPurify](https://www.npmjs.com/package/dompurify), you should do the following: ```js -const yourTooltipEl = document.getElementById('yourTooltip') +const yourTooltipEl = document.querySelector('#yourTooltip') const tooltip = new bootstrap.Tooltip(yourTooltipEl, { sanitizeFn(content) { return DOMPurify.sanitize(content) } }) ``` + +## Optionally using jQuery + +**You don't need jQuery in Bootstrap 5**, but it's still possible to use our components with jQuery. If Bootstrap detects `jQuery` in the `window` object, it'll add all of our components in jQuery's plugin system. This allows you to do the following: + +```js +$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration + +$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration + +$('#myTooltip').tooltip('show') // to trigger `show` method +``` + +The same goes for our other components. + +### No conflict + +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. + +```js +const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value +$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality +``` + +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. + +### jQuery events + +Bootstrap will detect jQuery if `jQuery` is present in the `window` object and there is no `data-bs-no-jquery` attribute set on `<body>`. If jQuery is found, Bootstrap will emit events thanks to jQuery's event system. So if you want to listen to Bootstrap's events, you'll have to use the jQuery methods (`.on`, `.one`) instead of `addEventListener`. + +```js +$('#myTab a').on('shown.bs.tab', () => { + // do something... +}) +``` + +## Disabled JavaScript + +Bootstrap's plugins have no special fallback 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. |