From 769c8d824600fbf521e3976cc4a3c6152ed4e8ce Mon Sep 17 00:00:00 2001 From: Martijn Cuppens Date: Thu, 23 May 2019 11:56:03 +0200 Subject: Helpers & utilities split (#28445) --- site/content/docs/4.3/helpers/clearfix.md | 38 ++++ site/content/docs/4.3/helpers/embed.md | 72 ++++++ site/content/docs/4.3/helpers/position.md | 33 +++ site/content/docs/4.3/helpers/screen-readers.md | 25 +++ site/content/docs/4.3/helpers/stretched-link.md | 76 +++++++ site/content/docs/4.3/helpers/text.md | 25 +++ site/content/docs/4.3/utilities/api.md | 261 ++++++++++++++++++++++ site/content/docs/4.3/utilities/borders.md | 1 - site/content/docs/4.3/utilities/clearfix.md | 37 --- site/content/docs/4.3/utilities/embed.md | 72 ------ site/content/docs/4.3/utilities/position.md | 26 --- site/content/docs/4.3/utilities/screen-readers.md | 25 --- site/content/docs/4.3/utilities/stretched-link.md | 76 ------- site/content/docs/4.3/utilities/text.md | 16 -- 14 files changed, 530 insertions(+), 253 deletions(-) create mode 100644 site/content/docs/4.3/helpers/clearfix.md create mode 100644 site/content/docs/4.3/helpers/embed.md create mode 100644 site/content/docs/4.3/helpers/position.md create mode 100644 site/content/docs/4.3/helpers/screen-readers.md create mode 100644 site/content/docs/4.3/helpers/stretched-link.md create mode 100644 site/content/docs/4.3/helpers/text.md create mode 100644 site/content/docs/4.3/utilities/api.md delete mode 100644 site/content/docs/4.3/utilities/clearfix.md delete mode 100644 site/content/docs/4.3/utilities/embed.md delete mode 100644 site/content/docs/4.3/utilities/screen-readers.md delete mode 100644 site/content/docs/4.3/utilities/stretched-link.md (limited to 'site/content/docs') diff --git a/site/content/docs/4.3/helpers/clearfix.md b/site/content/docs/4.3/helpers/clearfix.md new file mode 100644 index 000000000..bbae9a359 --- /dev/null +++ b/site/content/docs/4.3/helpers/clearfix.md @@ -0,0 +1,38 @@ +--- +layout: docs +title: Clearfix +description: Quickly and easily clear floated content within a container by adding a clearfix utility. +group: helpers +aliases: "/docs/4.3/helpers/" +--- + +Easily clear `float`s by adding `.clearfix` **to the parent element**. Can also be used as a mixin. + +{{< highlight html >}} +
...
+{{< /highlight >}} + +{{< highlight scss >}} +// Mixin itself +@mixin clearfix() { + &::after { + display: block; + content: ""; + clear: both; + } +} + +// Usage as a mixin +.element { + @include clearfix; +} +{{< /highlight >}} + +The following example shows how the clearfix can be used. Without the clearfix the wrapping div would not span around the buttons which would cause a broken layout. + +{{< example >}} +
+ + +
+{{< /example >}} diff --git a/site/content/docs/4.3/helpers/embed.md b/site/content/docs/4.3/helpers/embed.md new file mode 100644 index 000000000..f6f69c2dc --- /dev/null +++ b/site/content/docs/4.3/helpers/embed.md @@ -0,0 +1,72 @@ +--- +layout: docs +title: Embeds +description: Create responsive video or slideshow embeds based on the width of the parent by creating an intrinsic ratio that scales on any device. +group: helpers +toc: true +--- + +## About + +Rules are directly applied to ` + +{{< /example >}} + +## Aspect ratios + +Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided: + +{{< highlight html >}} + +
+ +
+ + +
+ +
+ + +
+ +
+ + +
+ +
+{{< /highlight >}} + +Within `_variables.scss`, you can change the aspect ratios you want to use. Here's an example of the `$embed-responsive-aspect-ratios` map: + +{{< highlight scss >}} +$embed-responsive-aspect-ratios: ( + "21by9": ( + x: 21, + y: 9 + ), + "16by9": ( + x: 16, + y: 9 + ), + "4by3": ( + x: 4, + y: 3 + ), + "1by1": ( + x: 1, + y: 1 + ) +); +{{< /highlight >}} diff --git a/site/content/docs/4.3/helpers/position.md b/site/content/docs/4.3/helpers/position.md new file mode 100644 index 000000000..921e47a9f --- /dev/null +++ b/site/content/docs/4.3/helpers/position.md @@ -0,0 +1,33 @@ +--- +layout: docs +title: Position +description: Use these helpers for quickly configuring the position of an element. +group: helpers +toc: true +--- + +## Fixed top + +Position an element at the top of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add additional CSS. + +{{< highlight html >}} +
...
+{{< /highlight >}} + +## Fixed bottom + +Position an element at the bottom of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add additional CSS. + +{{< highlight html >}} +
...
+{{< /highlight >}} + +## Sticky top + +Position an element at the top of the viewport, from edge to edge, but only after you scroll past it. The `.sticky-top` utility uses CSS's `position: sticky`, which isn't fully supported in all browsers. + +**IE11 and IE10 will render `position: sticky` as `position: relative`.** As such, we wrap the styles in a `@supports` query, limiting the stickiness to only browsers that can render it properly. + +{{< highlight html >}} +
...
+{{< /highlight >}} diff --git a/site/content/docs/4.3/helpers/screen-readers.md b/site/content/docs/4.3/helpers/screen-readers.md new file mode 100644 index 000000000..501b9c311 --- /dev/null +++ b/site/content/docs/4.3/helpers/screen-readers.md @@ -0,0 +1,25 @@ +--- +layout: docs +title: Screen readers +description: Use screen reader utilities to hide elements on all devices except screen readers. +group: helpers +--- + +Hide an element to all devices **except screen readers** with `.sr-only`. Use `.sr-only-focusable` to show the element only when it's focused (e.g. by a keyboard-only user). Can also be used as mixins. + +{{< example >}} +

Title for screen readers

+Skip to main content +{{< /example >}} + +{{< highlight scss >}} +// Usage as a mixin + +.sr-only-title { + @include sr-only; +} + +.skip-navigation { + @include sr-only-focusable; +} +{{< /highlight >}} diff --git a/site/content/docs/4.3/helpers/stretched-link.md b/site/content/docs/4.3/helpers/stretched-link.md new file mode 100644 index 000000000..9b5b3a517 --- /dev/null +++ b/site/content/docs/4.3/helpers/stretched-link.md @@ -0,0 +1,76 @@ +--- +layout: docs +title: Stretched link +description: Make any HTML element or Bootstrap component clickable by "stretching" a nested link via CSS. +group: helpers +--- + +Add `.stretched-link` to a link to make its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block) clickable via a `::after` pseudo element. In most cases, this means that an element with `position: relative;` that contains a link with the `.stretched-link` class is clickable. + +Cards have `position: relative` by default in Bootstrap, so in this case you can safely add the `.stretched-link` class to a link in the card without any other HTML changes. + +Multiple links and tap targets are not recommended with stretched links. However, some `position` and `z-index` styles can help should this be required. + +{{< example >}} +
+ {{< placeholder width="100%" height="180" class="card-img-top" text="false" title="Card image cap" >}} +
+
Card with stretched link
+

Some quick example text to build on the card title and make up the bulk of the card's content.

+ Go somewhere +
+
+{{< /example >}} + +Most custom components do not have `position: relative` by default, so we need to add the `.position-relative` here to prevent the link from stretching outside the parent element. + +{{< example >}} +
+ {{< placeholder width="144" height="144" class="flex-shrink-0 mr-3" text="false" title="Generic placeholder image" >}} +
+
Custom component with stretched link
+

Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.

+ Go somewhere +
+
+{{< /example >}} + +Columns are `position: relative` by default, so clickable columns only require the `.stretched-link` class on a link. However, stretching a link over an entire `.row` requires `.position-static` on the column and `.position-relative` on the row. + +{{< example >}} +
+
+ {{< placeholder width="100%" height="200" class="w-100" text="false" title="Generic placeholder image" >}} +
+
+
Columns with stretched link
+

Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.

+ Go somewhere +
+
+{{< /example >}} + +## Identifying the containing block + +If the stretched link doesn't seem to work, the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block) will probably be the cause. The following CSS properties will make an element the containing block: + +- A `position` value other than `static` +- A `transform` or `perspective` value other than `none` +- A `will-change` value of `transform` or `perspective` +- A `filter` value other than `none` or a `will-change` value of `filter` (only works on Firefox) + +{{< example >}} +
+ {{< placeholder width="100%" height="180" class="card-img-top" text="false" title="Card image cap" >}} +
+
Card with stretched links
+

Some quick example text to build on the card title and make up the bulk of the card's content.

+

+ Stretched link will not work here, because position: relative is added to the link +

+

+ This stretched link will only be spread over the p-tag, because a transform is applied to it. +

+
+
+{{< /example >}} diff --git a/site/content/docs/4.3/helpers/text.md b/site/content/docs/4.3/helpers/text.md new file mode 100644 index 000000000..bd5709942 --- /dev/null +++ b/site/content/docs/4.3/helpers/text.md @@ -0,0 +1,25 @@ +--- +layout: docs +title: Text +description: Documentation and examples for common text utilities to control alignment, wrapping, weight, and more. +group: helpers +toc: true +--- + +## Text truncation + +For longer content, you can add a `.text-truncate` class to truncate the text with an ellipsis. **Requires `display: inline-block` or `display: block`.** + +{{< example >}} + +
+
+ Praeterea iter est quasdam res quas ex communi. +
+
+ + + + Praeterea iter est quasdam res quas ex communi. + +{{< /example >}} diff --git a/site/content/docs/4.3/utilities/api.md b/site/content/docs/4.3/utilities/api.md new file mode 100644 index 000000000..7f587b0b6 --- /dev/null +++ b/site/content/docs/4.3/utilities/api.md @@ -0,0 +1,261 @@ +--- +layout: docs +title: Utility API +description: The utility API is a Sass based tool to generate utility classes. +group: utilities +aliases: "/docs/4.3/utilities/" +toc: true +--- + +The bootstrap utilities are generated with the utility API which can be used to change or extend Bootstraps utility classes. If you don't have any idea what sass maps are, you can consult the [official docs](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#maps) to get started. + +The `$utilities` map contains all utilities and is later merged with your custom `$utilities` map if present. The utility map contains a keyed list of utility groups which accept the following options: + +- `property`: Name of the property, this can be a string or an array of strings (needed for eg. horizontal paddings or margins). +- `responsive` _(optional)_: Boolean indicating if responsive classes need to be generated. `false` by default. +- `class` _(optional)_: Variable to change the class name if you don't want it to be the same as the property. +- `values`: This can be a list of values or a map if you don't want the class name to be the same as the value. If null is used as map key, it isn't rendered. +- `print` _(optional)_: Boolean indicating if print classes need to be generated. `false` by default. + + +## Adding utilities to the utility API + +All utility variables are added to the `$utilities` variable. Custom utility groups can added like this: + +```scss +$utilities: ( + "opacity": ( + property: opacity, + values: ( + 0: 0, + 25: .25, + 50: .5, + 100: 1, + ) + ) + ); +``` + +Output: + +```css +.opacity-0 { + opacity: 0; +} +.opacity-25 { + opacity: .25; +} +.opacity-75 { + opacity: .75; +} +.opacity-100 { + opacity: 1; +} +``` + + +## Changing the class prefix + +With the `class` option, the class prefix can be changed: + +```scss +$utilities: ( + "opacity": ( + property: opacity, + class: o, + values: ( + 0: 0, + 25: .25, + 50: .5, + 100: 1, + ) + ) + ); +``` + +Output: + +```css +.o-0 { + opacity: 0; +} +.o-25 { + opacity: .25; +} +.o-75 { + opacity: .75; +} +.o-100 { + opacity: 1; +} +``` + +## Responsive utilities + +With the `responsive` option, responsive utility classes can be generated: + +```scss +$utilities: ( + "opacity": ( + property: opacity, + responsive: true, + values: ( + 0: 0, + 25: .25, + 50: .5, + 100: 1, + ) + ) + ); +``` + +Output: + +```css +.opacity-0 { + opacity: 0; +} +.opacity-25 { + opacity: .25; +} +.opacity-75 { + opacity: .75; +} +.opacity-100 { + opacity: 1; +} +@media (min-width: 576px) { + .opacity-sm-0 { + opacity: 0; + } + .opacity-sm-25 { + opacity: .25; + } + .opacity-sm-75 { + opacity: .75; + } + .opacity-sm-100 { + opacity: 1; + } +} +@media (min-width: 768px) { + .opacity-md-0 { + opacity: 0; + } + .opacity-md-25 { + opacity: .25; + } + .opacity-md-75 { + opacity: .75; + } + .opacity-md-100 { + opacity: 1; + } +} +@media (min-width: 992px) { + .opacity-lg-0 { + opacity: 0; + } + .opacity-lg-25 { + opacity: .25; + } + .opacity-lg-75 { + opacity: .75; + } + .opacity-lg-100 { + opacity: 1; + } +} +@media (min-width: 1200px) { + .opacity-xl-0 { + opacity: 0; + } + .opacity-xl-25 { + opacity: .25; + } + .opacity-xl-75 { + opacity: .75; + } + .opacity-xl-100 { + opacity: 1; + } +} +``` + +## Changing utilities + +Overriding excising utilities is possible by using the same key. For example if you want more responsive overflow +utility classes you can do this: + +```scss +$utilities: ( + "overflow": ( + responsive: true, + property: overflow, + values: visible hidden scroll auto, + ), +); +``` + + +## Print utilities + +Enabling the `print` option will **also** generate utility classes for print. + +```scss +$utilities: ( + "opacity": ( + property: opacity, + class: o, + print: true, + values: ( + 0: 0, + 25: .25, + 50: .5, + 100: 1, + ) + ) + ); +``` + +Output: + +```css +.o-0 { + opacity: 0; +} +.o-25 { + opacity: .25; +} +.o-75 { + opacity: .75; +} +.o-100 { + opacity: 1; +} + +@media print { + .o-print-0 { + opacity: 0; + } + .o-print-25 { + opacity: .25; + } + .o-print-75 { + opacity: .75; + } + .o-print-100 { + opacity: 1; + } +} +``` + +## Removing utilities + +Utilities can also be removed by changing the group key to `null`: + +```scss +$utilities: ( + "float": null, +); +``` diff --git a/site/content/docs/4.3/utilities/borders.md b/site/content/docs/4.3/utilities/borders.md index 0cb9fc121..9f082f76a 100644 --- a/site/content/docs/4.3/utilities/borders.md +++ b/site/content/docs/4.3/utilities/borders.md @@ -3,7 +3,6 @@ layout: docs title: Borders description: Use border utilities to quickly style the border and border-radius of an element. Great for images, buttons, or any other element. group: utilities -aliases: "/docs/4.3/utilities/" toc: true --- diff --git a/site/content/docs/4.3/utilities/clearfix.md b/site/content/docs/4.3/utilities/clearfix.md deleted file mode 100644 index d89a55a68..000000000 --- a/site/content/docs/4.3/utilities/clearfix.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: docs -title: Clearfix -description: Quickly and easily clear floated content within a container by adding a clearfix utility. -group: utilities ---- - -Easily clear `float`s by adding `.clearfix` **to the parent element**. Can also be used as a mixin. - -{{< highlight html >}} -
...
-{{< /highlight >}} - -{{< highlight scss >}} -// Mixin itself -@mixin clearfix() { - &::after { - display: block; - content: ""; - clear: both; - } -} - -// Usage as a mixin -.element { - @include clearfix; -} -{{< /highlight >}} - -The following example shows how the clearfix can be used. Without the clearfix the wrapping div would not span around the buttons which would cause a broken layout. - -{{< example >}} -
- - -
-{{< /example >}} diff --git a/site/content/docs/4.3/utilities/embed.md b/site/content/docs/4.3/utilities/embed.md deleted file mode 100644 index e744f27c0..000000000 --- a/site/content/docs/4.3/utilities/embed.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: docs -title: Embeds -description: Create responsive video or slideshow embeds based on the width of the parent by creating an intrinsic ratio that scales on any device. -group: utilities -toc: true ---- - -## About - -Rules are directly applied to ` - -{{< /example >}} - -## Aspect ratios - -Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided: - -{{< highlight html >}} - -
- -
- - -
- -
- - -
- -
- - -
- -
-{{< /highlight >}} - -Within `_variables.scss`, you can change the aspect ratios you want to use. Here's an example of the `$embed-responsive-aspect-ratios` map: - -{{< highlight scss >}} -$embed-responsive-aspect-ratios: ( - "21by9": ( - x: 21, - y: 9 - ), - "16by9": ( - x: 16, - y: 9 - ), - "4by3": ( - x: 4, - y: 3 - ), - "1by1": ( - x: 1, - y: 1 - ) -); -{{< /highlight >}} diff --git a/site/content/docs/4.3/utilities/position.md b/site/content/docs/4.3/utilities/position.md index 1efaf4cf1..4af457da4 100644 --- a/site/content/docs/4.3/utilities/position.md +++ b/site/content/docs/4.3/utilities/position.md @@ -17,29 +17,3 @@ Quick positioning classes are available, though they are not responsive.
...
...
{{< /highlight >}} - -## Fixed top - -Position an element at the top of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add additional CSS. - -{{< highlight html >}} -
...
-{{< /highlight >}} - -## Fixed bottom - -Position an element at the bottom of the viewport, from edge to edge. Be sure you understand the ramifications of fixed position in your project; you may need to add additional CSS. - -{{< highlight html >}} -
...
-{{< /highlight >}} - -## Sticky top - -Position an element at the top of the viewport, from edge to edge, but only after you scroll past it. The `.sticky-top` utility uses CSS's `position: sticky`, which isn't fully supported in all browsers. - -**IE11 and IE10 will render `position: sticky` as `position: relative`.** As such, we wrap the styles in a `@supports` query, limiting the stickiness to only browsers that can render it properly. - -{{< highlight html >}} -
...
-{{< /highlight >}} diff --git a/site/content/docs/4.3/utilities/screen-readers.md b/site/content/docs/4.3/utilities/screen-readers.md deleted file mode 100644 index 7781b11fb..000000000 --- a/site/content/docs/4.3/utilities/screen-readers.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: docs -title: Screen readers -description: Use screen reader utilities to hide elements on all devices except screen readers. -group: utilities ---- - -Hide an element to all devices **except screen readers** with `.sr-only`. Use `.sr-only-focusable` to show the element only when it's focused (e.g. by a keyboard-only user). Can also be used as mixins. - -{{< example >}} -

Title for screen readers

-Skip to main content -{{< /example >}} - -{{< highlight scss >}} -// Usage as a mixin - -.sr-only-title { - @include sr-only; -} - -.skip-navigation { - @include sr-only-focusable; -} -{{< /highlight >}} diff --git a/site/content/docs/4.3/utilities/stretched-link.md b/site/content/docs/4.3/utilities/stretched-link.md deleted file mode 100644 index ad8a703ca..000000000 --- a/site/content/docs/4.3/utilities/stretched-link.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -layout: docs -title: Stretched link -description: Make any HTML element or Bootstrap component clickable by "stretching" a nested link via CSS. -group: utilities ---- - -Add `.stretched-link` to a link to make its [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block) clickable via a `::after` pseudo element. In most cases, this means that an element with `position: relative;` that contains a link with the `.stretched-link` class is clickable. - -Cards have `position: relative` by default in Bootstrap, so in this case you can safely add the `.stretched-link` class to a link in the card without any other HTML changes. - -Multiple links and tap targets are not recommended with stretched links. However, some `position` and `z-index` styles can help should this be required. - -{{< example >}} -
- {{< placeholder width="100%" height="180" class="card-img-top" text="false" title="Card image cap" >}} -
-
Card with stretched link
-

Some quick example text to build on the card title and make up the bulk of the card's content.

- Go somewhere -
-
-{{< /example >}} - -Most custom components do not have `position: relative` by default, so we need to add the `.position-relative` here to prevent the link from stretching outside the parent element. - -{{< example >}} -
- {{< placeholder width="144" height="144" class="flex-shrink-0 mr-3" text="false" title="Generic placeholder image" >}} -
-
Custom component with stretched link
-

Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.

- Go somewhere -
-
-{{< /example >}} - -Columns are `position: relative` by default, so clickable columns only require the `.stretched-link` class on a link. However, stretching a link over an entire `.row` requires `.position-static` on the column and `.position-relative` on the row. - -{{< example >}} -
-
- {{< placeholder width="100%" height="200" class="w-100" text="false" title="Generic placeholder image" >}} -
-
-
Columns with stretched link
-

Cras sit amet nibh libero, in gravida nulla. Nulla vel metus scelerisque ante sollicitudin. Cras purus odio, vestibulum in vulputate at, tempus viverra turpis. Fusce condimentum nunc ac nisi vulputate fringilla. Donec lacinia congue felis in faucibus.

- Go somewhere -
-
-{{< /example >}} - -## Identifying the containing block - -If the stretched link doesn't seem to work, the [containing block](https://developer.mozilla.org/en-US/docs/Web/CSS/Containing_block#Identifying_the_containing_block) will probably be the cause. The following CSS properties will make an element the containing block: - -- A `position` value other than `static` -- A `transform` or `perspective` value other than `none` -- A `will-change` value of `transform` or `perspective` -- A `filter` value other than `none` or a `will-change` value of `filter` (only works on Firefox) - -{{< example >}} -
- {{< placeholder width="100%" height="180" class="card-img-top" text="false" title="Card image cap" >}} -
-
Card with stretched links
-

Some quick example text to build on the card title and make up the bulk of the card's content.

-

- Stretched link will not work here, because position: relative is added to the link -

-

- This stretched link will only be spread over the p-tag, because a transform is applied to it. -

-
-
-{{< /example >}} diff --git a/site/content/docs/4.3/utilities/text.md b/site/content/docs/4.3/utilities/text.md index 76708e831..514018e76 100644 --- a/site/content/docs/4.3/utilities/text.md +++ b/site/content/docs/4.3/utilities/text.md @@ -45,22 +45,6 @@ Prevent text from wrapping with a `.text-nowrap` class. {{< /example >}} -For longer content, you can add a `.text-truncate` class to truncate the text with an ellipsis. **Requires `display: inline-block` or `display: block`.** - -{{< example >}} - -
-
- Praeterea iter est quasdam res quas ex communi. -
-
- - - - Praeterea iter est quasdam res quas ex communi. - -{{< /example >}} - ## Word break Prevent long strings of text from breaking your components' layout by using `.text-break` to set `overflow-wrap: break-word` (and `word-break: break-word` for IE & Edge compatibility). -- cgit v1.2.3