mirror of
https://github.com/twbs/bootstrap.git
synced 2025-01-18 10:52:19 +01:00
Add some details on "javascript" page (#36363)
* docs: Add more details on "getting-started -> javascript" page & group jQuery stuff * Update after feedback * Rewrite some content - Shorten copy here and there - Reduce some callouts that are entire sections with h2 headings - Re-arrange a couple things Co-authored-by: Mark Otto <markdotto@gmail.com> Co-authored-by: Mark Otto <markd.otto@gmail.com>
This commit is contained in:
GeoSot
GitHub
parent
8b85267739
commit
651dae6d0f
@ -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
|
||||
|
||||
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...
|
||||
})
|
||||
```
|
||||
{{< /callout >}}
|
||||
|
||||
## Programmatic API
|
||||
|
||||
All constructors accept an optional options object or nothing (which initiates a plugin with its default behavior):
|
||||
|
||||
```js
|
||||
const myModalEl = document.getElementById('myModal')
|
||||
const myModalEl = document.querySelector('#myModal')
|
||||
|
||||
const modal = new bootstrap.Modal(myModalEl) // initialized with defaults
|
||||
const modal1 = new bootstrap.Modal(myModalEl, { keyboard: false }) // initialized with no keyboard
|
||||
|
||||
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. In order to retrieve it directly from an element, do this: `bootstrap.Popover.getInstance(myPopoverEl)`.
|
||||
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
|
||||
bootstrap.Popover.getInstance(myPopoverEl)
|
||||
```
|
||||
|
||||
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)
|
||||
```
|
||||
|
||||
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,6 +185,19 @@ 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 !!
|
||||
```
|
||||
|
||||
#### `dispose` method
|
||||
|
||||
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
|
||||
const myModal = document.querySelector('#myModal')
|
||||
myModal.hide() // it is asynchronous
|
||||
|
||||
myModal.addEventListener('shown.bs.hidden', event => {
|
||||
myModal.dispose()
|
||||
})
|
||||
```
|
||||
|
||||
### Default settings
|
||||
|
||||
You can change the default settings for a plugin by modifying the plugin's `Constructor.Default` object:
|
||||
@ -193,32 +207,24 @@ You can change the default settings for a plugin by modifying the plugin's `Cons
|
||||
bootstrap.Modal.Default.keyboard = false
|
||||
```
|
||||
|
||||
## No conflict (only if you use jQuery)
|
||||
## Methods and properties
|
||||
|
||||
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.
|
||||
Every Bootstrap plugin exposes the following methods and static properties.
|
||||
|
||||
```js
|
||||
const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
|
||||
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality
|
||||
```
|
||||
{{< 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 >}}
|
||||
|
||||
## Version numbers
|
||||
|
||||
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:
|
||||
|
||||
```js
|
||||
bootstrap.Tooltip.VERSION // => "{{< param current_version >}}"
|
||||
```
|
||||
|
||||
## No special fallbacks when JavaScript is disabled
|
||||
|
||||
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.
|
||||
|
||||
{{< callout warning >}}
|
||||
##### 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.
|
||||
{{< /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.
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-bs-`, as in `data-bs-animation=""`. Make sure to change the case type of the option name from camelCase to kebab-case when passing the options via data attributes. For example, use `data-bs-custom-class="beautifier"` instead of `data-bs-customClass="beautifier"`.
|
||||
As options can be passed via data attributes or JavaScript, you can append an option name to `data-bs-`, as in `data-bs-animation="{value}"`. Make sure to change the case type of the option name from "_camelCase_" to "_kebab-case_" when passing the options via data attributes. For example, use `data-bs-custom-class="beautifier"` instead of `data-bs-customClass="beautifier"`.
|
||||
|
||||
As of Bootstrap 5.2.0, all components support an **experimental** reserved data attribute `data-bs-config` that can house simple component configuration as a JSON string. When an element has `data-bs-config='{"delay":0, "title":123}'` and `data-bs-title="456"` attributes, the final `title` value will be `456` and the separate data attributes will override values given on `data-bs-config`. In addition, existing data attributes are able to house JSON values like `data-bs-delay='{"show":0,"hide":150}'`.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user