Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
feat(carousel): Use b-img component and id Mixin (#945)
* [carousel]: update docs to use b-img for blank image

* [carousel-slide] use b-img component

* [img] Add block prop for adding class d-block

* [carousel-slide]: Allow auto-generation of blank images

* [carousel] add global img-width & img-height props for sniffing by slides

* [carousel-slide] use id mixin

* [carousel] incorporate id mixin

* Update README.md

* Update img.js

* [carousel-slide]: Enable local image if img-blank set

* Rename events: slide => sliding-start, slid => sliding-end

* Update README.md

* Update meta.json

* Update README.md
  • Loading branch information
tmorehouse committed Aug 29, 2017
1 parent 4666b37 commit d95321b
Show file tree
Hide file tree
Showing 4 changed files with 122 additions and 57 deletions.
62 changes: 38 additions & 24 deletions docs/components/carousel/README.md
Expand Up @@ -2,7 +2,7 @@

> The carousel is a slideshow for cycling through a series of content, built with CSS 3D transforms.
It works with a series of images, text, or custom markup. It also includes support for previous/next
controls and indicators.
controls and indicators. Please be aware that nested carousels are **not** supported.

```html
<template>
Expand All @@ -13,39 +13,41 @@ controls and indicators.
indicators
background="#ababab"
:interval="4000"
img-width="1024"
img-height="480"
v-model="slide"
@slide="onSlide"
@slid="onSlid"
@sliding-start="onSlideStart"
@sliding-end="onSlideEnd"
>

<!-- Text slides with image -->
<b-carousel-slide caption="First slide"
text="Nulla vitae elit libero, a pharetra augue mollis interdum."
img="https://lorempixel.com/1024/480/technics/2/"
img-src="https://lorempixel.com/1024/480/technics/2/"
></b-carousel-slide>

<!-- Slides with custom text -->
<b-carousel-slide img="https://lorempixel.com/1024/480/technics/4/">
<b-carousel-slide img-src="https://lorempixel.com/1024/480/technics/4/">
<h1>Hello world!</h1>
</b-carousel-slide>

<!-- Slides with image only -->
<b-carousel-slide img="https://lorempixel.com/1024/480/technics/8/">
<b-carousel-slide img-src="https://lorempixel.com/1024/480/technics/8/">
</b-carousel-slide>

<!-- Slides with img slot -->
<!-- Note the classes .d-block and .img-fluid to prevent browser default image alignment -->
<b-carousel-slide>
<img slot="img" class="d-block img-fluid"
<img slot="img" class="d-block img-fluid w-100" width="1024" height="480"
src="https://lorempixel.com/1024/480/technics/5/" alt="image slot">
</b-carousel-slide>

<!-- Slide with blank image to maintain aspect ratio -->
<b-carousel-slide caption="Blank Image" :img="blankImg(1024,480)">
<!-- Slide with blank fluid image to maintain slide aspect ratio -->
<b-carousel-slide caption="Blank Image" img-blank img-alt="Blank image">
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
eros felis, tincidunt a tincidunt eget, convallis vel est. Ut pellentesque
ut lacus vel interdum. Nulla bibendum tincidunt erat, sed tincidunt
magna finibus ac.
ut lacus vel interdum.
</p>
</b-carousel-slide>

Expand All @@ -66,17 +68,10 @@ export default {
sliding: null
},
methods: {
blankImg(x, y) {
// Return a blank SVG image with specified width and height
// Handy for maintaining aspect ratio for text only slides
return "data:image/svg+xml;charset=utf-8,%3Csvg xmlns%3D" +
"'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg' " +
"viewBox%3D'0 0 " + x + " " + y + "'%2F%3E";
},
onSlide(slide) {
onSlideStart(slide) {
this.sliding = true;
},
onSlid(slide) {
onSlideEnd(slide) {
this.sliding = false;
}
}
Expand All @@ -85,17 +80,33 @@ export default {
<!-- carousel-1.vue -->
```


### Sizing
Carousels don’t automatically normalize slide dimensions. As such, you may need to use
additional utilities or custom styles to appropriately size content. When using images
in each slide, ensure they all have the same dimensions (or aspect ratio).

When using `img-src` or `img-blank` on `<b-carousel-slide>`, you can set the image
width and height via the `img-width` and `img-height` props on `<b-carousel>` and
have these values automatically applied to each `carousel-slide` image.

Note that images will still be responsive and automatically grow or shrink to fit
within the width of its parent container.

Internally, `<b-carousel-slide>` uses the [`<b-img>`](/docs/components/img)
component to render the images. The `img-*` props map to the corresponsing props
available to `<b-img>`.


### Interval
Carousel defults to an interval of `5000`ms (5 seconds). To pause the caurousel from
Carousel defaults to an interval of `5000`ms (5 seconds). To pause the carousel from
auto sliding, set the `interval` prop to `0`. To restart a paused carousel, set the
`interval` back to the number of ms.

In browsers where the [Page Visibility API](https://www.w3.org/TR/page-visibility/)
is supported, the carousel will avoid sliding when the webpage is not visible to
the user (such as when the browser tab is inactive, the browser window is minimized, etc.).


### Controls and Indicators
Set the prop `controls` to enable the previous and next control buttons.
Expand All @@ -106,13 +117,16 @@ Both indicators and controls can be set at the same time or independently.


### V-model support
Programaticaly xontrol which slide is showing via `v-model` (which binds to the
`value` prop). Note slides are indexed starting at `0`.
Programmaticaly control which slide is showing via `v-model` (which binds to the
`value` prop). Note, that slides are indexed starting at `0`.


### Accessibility
Carousels are generally not fully compliant with accessibility standards, although
we try to make them as accessible as possible.

By providing a document unique value via the `id` prop, `<b-carousel>` will enable
accessibility features. It is highly recommended to always add an ID to all components.

All carousel controls and indicateors have aria labels. These can be customized by
All carousel controls and indicators have aria labels. These can be customized by
setting the various `label-*` props.
6 changes: 3 additions & 3 deletions docs/components/carousel/meta.json
Expand Up @@ -4,7 +4,7 @@
"components": ["bCarouselSlide"],
"events": [
{
"event": "slide",
"event": "sliding-start",
"description": "Emitted when transitioning to a new slide has started.",
"args": [
{
Expand All @@ -14,8 +14,8 @@
]
},
{
"event": "slid",
"description": "Emitted when transitioning to a new slide has finished.",
"event": "sliding-end",
"description": "Emitted when transitioning to a new slide has ended.",
"args": [
{
"arg": "slide",
Expand Down
60 changes: 51 additions & 9 deletions lib/components/carousel-slide.vue
@@ -1,11 +1,19 @@
<template>
<div class="carousel-item"
role="listitem"
:id="id || null"
:style="{background,height}"
:id="safeId()"
:style="{background}"
>
<slot name="img">
<img class="d-block img-fluid" v-if="img" :src="img" :alt="imgAlt">
<b-img v-if="imgSrc || imgBlank"
fluid-grow
block
:blank="imgBlank"
:blank-color="imgBlankColor"
:src="imgSrc"
:width="computedWidth"
:height="computedHeight"
:alt="imgAlt"></b-img>
</slot>
<div :is="contentTag" :class="contentClasses">
<h3 v-if="caption" :is="captionTag" v-html="caption"></h3>
Expand All @@ -16,17 +24,46 @@
</template>

<script>
import bImg from './img';
import { warn } from '../utils';
import { idMixin } from '../mixins';
export default {
components: { bImg },
mixins: [ idMixin ],
props: {
id: {
type: String
imgSrc: {
type: String,
default() {
if (this && this.src) {
// Deprecate src
warn("b-carousel-slide: prop 'src' has been deprecated. Use 'img-src' instead");
return this.src;
}
return null;
}
},
img: {
src: {
// Deprecated: use img-src instead
type: String
},
imgAlt: {
type: String
},
imgWidth: {
type: [Number, String]
},
imgHeight: {
type: [Number, String]
},
imgBlank: {
type: Boolean,
default: false
},
imgBlankColor: {
type: String,
default: 'transparent'
},
contentVisibleUp: {
type: String
},
Expand All @@ -50,9 +87,6 @@
},
background: {
type: String
},
height: {
type: String
}
},
computed: {
Expand All @@ -62,6 +96,14 @@
this.contentVisibleUp ? 'd-none' : '',
this.contentVisibleUp ? `d-${this.contentVisibleUp}-block` : ''
];
},
computedWidth() {
// Use local width, or try parent width
return this.imgWidth || this.$parent.imgWidth;
},
computedHeight() {
// Use local height, or try parent height
return this.imgHeight || this.$parent.imgHeight;
}
}
};
Expand Down

0 comments on commit d95321b

Please sign in to comment.