Fix toast documentation page.

diff --git a/js/tests/visual/toast.html b/js/tests/visual/toast.html
index 0daf8b521c165640788d7a9a35e14be0ad9d59f2..6897022c06edb8078806ca8a64d4ab6eaa1a9c24 100644 (file)
--- a/js/tests/visual/toast.html
+++ b/js/tests/visual/toast.html
@@ -26,7 +26,7 @@
     </div>
 
     <div class="notifications">
-      <div class="toast" data-delay='{"show": 0, "hide": 2000}'>
+      <div id="toastAutoHide" class="toast">
         <div class="toast-header">
           <img class="rounded mr-2" data-src="holder.js/20x20?size=1&text=.&bg=#007aff" alt="">
           <strong class="mr-auto">Bootstrap</strong>
@@ -54,6 +54,10 @@
     <script src="../../dist/toast.js"></script>
     <script>
       $(function () {
+        $('#toastAutoHide').attr('data-delay', JSON.stringify({
+          show: 0,
+          hide: 2000
+        }))
         $('.toast').toast()
 
         $('#btnShowToast').on('click', function () {

diff --git a/site/docs/4.1/assets/js/src/application.js b/site/docs/4.1/assets/js/src/application.js
index 40dbaea453a7de5321846923c7906c9640a728e6..40c3f1e94e56055855a8f9d435931153a8b7296e 100644 (file)
--- a/site/docs/4.1/assets/js/src/application.js
+++ b/site/docs/4.1/assets/js/src/application.js
@@ -24,6 +24,12 @@
 
     $('[data-toggle="popover"]').popover()
 
+    $('.toast')
+      .toast({
+        autohide: false
+      })
+      .toast('show')
+
     // Demos within modals
     $('.tooltip-test').tooltip()
     $('.popover-test').popover()

diff --git a/site/docs/4.1/components/toasts.md b/site/docs/4.1/components/toasts.md
index df5d2e827e917e7c10e6b0671a3b8c9567807bd2..54e0a1c52cd10f74b639434206f20dbef905f85e 100644 (file)
--- a/site/docs/4.1/components/toasts.md
+++ b/site/docs/4.1/components/toasts.md
@@ -8,6 +8,16 @@ toc: true
 
 Toasts are lightweight notifications designed to mimic the push notifications that have been popularized by mobile and desktop operating systems. They're built with flexbox, so they're easy to align and position.
 
+## Overview
+
+Things to know when using the toast plugin:
+
+- If you're building our JavaScript from source, it [requires `util.js`]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/javascript/#util).
+- Toast are opt-in for performance reasons, so **you must initialize them yourself**.
+- Toast will auto hide if you do not specify `autohide: false`
+
+Got all that? Great, let's see how they work with some examples.
+
 ## Examples
 
 A basic toast can include a header (though it doesn't strictly need one) with whatever contents you like. The header is also `display: flex`, so `.mr-auto` and `.ml-auto` can be used for easy pushing of content, as well as all our flexbox utilities.
@@ -167,3 +177,116 @@ You can also get fancy with flexbox utilities.
 {% endcapture %}
 {% include example.html content=example %}
 </div>
+
+## JavaScript behavior
+
+### Usage
+
+Initialize toasts via JavaScript:
+
+{% highlight js %}
+$('.toast').toast(option)
+{% endhighlight %}
+
+### Options
+
+Options can be passed via data attributes or JavaScript. For data attributes, append the option name to `data-`, as in `data-animation=""`.
+
+<table class="table table-bordered table-striped">
+  <thead>
+    <tr>
+      <th style="width: 100px;">Name</th>
+      <th style="width: 100px;">Type</th>
+      <th style="width: 50px;">Default</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>animation</td>
+      <td>boolean</td>
+      <td>true</td>
+      <td>Apply a CSS fade transition to the toast</td>
+    </tr>
+    <tr>
+      <td>autohide</td>
+      <td>boolean</td>
+      <td>true</td>
+      <td>Auto hide the toast</td>
+    </tr>
+    <tr>
+      <td>delay</td>
+      <td>number | object</td>
+      <td>
+        <code>{ show: 0, hide: 500 }</code>
+      </td>
+      <td>
+        <p>Delay showing and hiding the toast (ms)</p>
+        <p>If a number is supplied, delay is applied to both hide/show</p>
+        <p>Object structure is: <code>delay: { "show": 500, "hide": 100 }</code></p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+### Methods
+
+{% include callout-danger-async-methods.md %}
+
+#### `$().toast(options)`
+
+Attaches a toast handler to an element collection.
+
+#### `.toast('show')`
+
+Reveals an element's toast. **Returns to the caller before the toast has actually been shown** (i.e. before the `shown.bs.toast` event occurs).
+You have to manually call this method, instead your toast won't show.
+
+{% highlight js %}$('#element').toast('show'){% endhighlight %}
+
+#### `.toast('hide')`
+
+Hides an element's toast. **Returns to the caller before the toast has actually been hidden** (i.e. before the `hidden.bs.toast` event occurs). You have to manually call this method if you made `autohide` to `false`.
+
+{% highlight js %}$('#element').toast('hide'){% endhighlight %}
+
+#### `.toast('dispose')`
+
+Hides an element's toast. Your toast will remain on the DOM but won't show anymore.
+
+{% highlight js %}$('#element').toast('dispose'){% endhighlight %}
+
+### Events
+
+<table class="table table-bordered table-striped">
+  <thead>
+    <tr>
+      <th style="width: 150px;">Event Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>show.bs.toast</td>
+      <td>This event fires immediately when the <code>show</code> instance method is called.</td>
+    </tr>
+    <tr>
+      <td>shown.bs.toast</td>
+      <td>This event is fired when the toast has been made visible to the user.</td>
+    </tr>
+    <tr>
+      <td>hide.bs.toast</td>
+      <td>This event is fired immediately when the <code>hide</code> instance method has been called.</td>
+    </tr>
+    <tr>
+      <td>hidden.bs.toast</td>
+      <td>This event is fired when the toast has finished being hidden from the user.</td>
+    </tr>
+  </tbody>
+</table>
+
+{% highlight js %}
+$('#myToast').on('hidden.bs.toast', function () {
+  // do something…
+})
+{% endhighlight %}