From 4f9f1a0ea3d1d61c46d8bbc940fc3a966b3430a5 Mon Sep 17 00:00:00 2001 From: Mark Otto Date: Sat, 24 Dec 2016 14:04:44 -0800 Subject: [PATCH] started fixing nested .bd-example stuff, then rewrote the modal docs - better table of contents and overall structure - clearer examples of modal contents, longer modals, and modal options --- docs/components/modal.md | 506 ++++++++++++++++++++++++--------------- 1 file changed, 313 insertions(+), 193 deletions(-) diff --git a/docs/components/modal.md b/docs/components/modal.md index 5b482f93b7..7251c38428 100644 --- a/docs/components/modal.md +++ b/docs/components/modal.md @@ -5,14 +5,28 @@ description: Learn how to use Bootstrap's modals to add dialog prompts to your s group: components --- -Modals are streamlined, but flexible, dialog prompts with the minimum required functionality and smart defaults. +Modals are streamlined, but flexible dialog prompts powered by JavaScript. They support a number of use cases from user notification to completely custom content and feature a handful of helpful subcomponents, sizes, and more. ## Contents * Will be replaced with the ToC, excluding the "Contents" header {:toc} -**Due to how HTML5 defines its semantics, [the `autofocus` HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autofocus) has no effect in Bootstrap modals.** To achieve the same effect, use some custom JavaScript: +## How it works + +Before getting started with Bootstrap's modal component, be sure to read the following as our menu options have recently changed. + +- Modals are built with HTML, CSS, and JavaScript. They're positioned over everything else in the document and remove scroll from the `` so that modal content scrolls instead. +- Clicking on the modal "backdrop" will automatically close the modal. +- Bootstrap only supports one modal window at a time. Nested modals aren't supported as we believe them to be poor user experiences. +- Modal's use `position: fixed`, which can sometimes be a bit particular about it's rendering. Whenever possible, place your modal HTML in a top-level position to avoid potential interference from other elements. You'll likely run into issues when nesting a `.modal` within another fixed element. +- One again, due to `position: fixed`, there are some caveats with using modals on mobile devices. [See our browser support docs]({{ site.baseurl }}/getting-started/browsers-devices/#modals-and-dropdowns-on-mobile) for details. +- Lastly, the `autofocus` HTML attribute has no affect in modals. Here's how you can achieve the same effect with custom JavaScript. + +Keep reading for demos and usage guidelines. + + +- Due to how HTML5 defines its semantics, [the `autofocus` HTML attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-autofocus) has no effect in Bootstrap modals. To achieve the same effect, use some custom JavaScript: {% highlight js %} $('#myModal').on('shown.bs.modal', function () { @@ -20,27 +34,11 @@ $('#myModal').on('shown.bs.modal', function () { }) {% endhighlight %} -{% callout warning %} -#### Multiple open modals not supported +## Examples -Be sure not to open a modal while another is still visible. Showing more than one modal at a time requires custom code. -{% endcallout %} +### Modal components -{% callout warning %} -#### Modal markup placement - -Always try to place a modal's HTML code in a top-level position in your document to avoid other components affecting the modal's appearance and/or functionality. Placing it within a `position: fixed;` element may adversely affect placement. -{% endcallout %} - -{% callout warning %} -#### Mobile device caveats - -There are some caveats regarding using modals on mobile devices. [See our browser support docs]({{ site.baseurl }}/getting-started/browsers-devices/#modals-and-dropdowns-on-mobile) for details. -{% endcallout %} - -### Static example - -A rendered modal with header, body, and set of actions in the footer. +Below is a _static_ modal example (meaning its `position` and `display` have been overridden). Included are the modal header, modal body (required for `padding`), and modal footer (optional). We ask that you include modal headers with dismiss actions whenever possible, or provide another explicit dismiss action.
@@ -50,18 +48,18 @@ A rendered modal with header, body, and set of actions in the footer. -

Modal title

+
Modal title
-

One fine body…

+

Modal body text goes here.

-
- - + + + {% highlight html %} @@ -72,87 +70,65 @@ A rendered modal with header, body, and set of actions in the footer. -

Modal title

+
Modal title
-

One fine body…

+

Modal body text goes here.

- +
- - - + + + {% endhighlight %} ### Live demo -Toggle a modal via JavaScript by clicking the button below. It will slide down and fade in from the top of the page. +Toggle a working modal demo by clicking the button below. It will slide down and fade in from the top of the page. - -
-
{% highlight html %} - -