1.4.1
Slider Framework
Renato Ćorluka
October 7, 2024
The Slider Framework is a wrapper code for the Breakdance Builder that allows users to easily create and customize responsive sliders using the Swiper.js library. It integrates seamlessly, offering extensive options for layout, navigation, and effects, event for making highly customizable slider creation simple and flexible even for non-developers.
For developers we are providing code examples how you could use full Swiper.js API and connect it to Slider element.
Getting Started
Slider framework architecture
It is important to understand following terms:
- Carousel
- Main Slider (master)
- Components
- Thumbnail slider (slave)
- Connected Sliders (slave)
1. Carousel
Special div which is uses as reference for all of the components. If you put components outside this div, they won’t work. Please check structure and locate element named 0. carousel this is where all magic happens.
2. Main Slider
Inside Carousel we could have multiple sliders in some configuration. Only one can act as master and other are slave sliders. This is important because master has bi-directional event connection to slave sliders, and slave sliders have uni-directional connection to Main slider. This slider has data-swiper=”main”custom attribute. If you have more than one slider with this attribute, the first slider in DOM will become master. All custom components needs to be inside Carousel and they will show progress data, and controls for the Main Slider.
If you add slave sliders, you should keep in mind that they should have same number of the slides as the Main or controls will correspond just to Main slider data and other slave sliders could show irrelevant content.
3. Components
Components are special block which are acting as custom controls for Main Slider. Some of them include functions like:
- Prev/Next navigation
- Play/Pause controls for autoplay
- Bullet navigation
- Fractional pagination
- Active teleport
- or could be combined in hybrid when placed in another div like fraction + bullet
4. Thumbnail slider
This slider functions as a slave slider. The content within this slider cannot be manually controlled; instead, it automatically extracts segments of content from the main slide. By setting data-swiper-thumbnail=”true” the content will be transferred into a thumbnail. The fallback option is a complete copy of the entire slide.
From a UX/A11Y perspective, this serves as a replacement for bullet or numbered navigation. Therefore, refrain from using those if you are already utilizing thumbnails.
5. Connected sliders
If you insert an additional slider within the Carousel div, it will function as a connected slider. Please ensure that it does not possess the data-swiper=”main” attribute, as there should only be one master slide. In the event of having two master sliders, the initial one will serve as the master, while the subsequent slider will act as the slave.
Components
We have different components which will work with Main slider based
Advanced slider setup
Setup docs for Advanced Slider
Post list setup
Coming soon: Setup docs for Dynamic Slider.
Components
Table – components overview
When you copy/paste Slider framework component, in structure panel you will see numbered elements. This table below explains each of them.
| No | Name | Description |
|---|---|---|
| 0 | Carousel | Carousel is a special div where magic happens. Everything here works when it is placed within the Carousel div. This is used to distinguish which controls should control which slider in case you are using more than one slider. |
| 0.1 | Skip link | This is link which is invisible until users enters Carousel by using keyboard. It will give users option to skip carousel and enhance accessibility. |
| 0.2 | Framework API | Main code which enables all the magic. Don’t remove it or move outside Carousel div [0]. |
| 0.3 | Main slider | All controls are connected to this slider |
| 0.4 | Thumb slider | Secondary slider which teleports all elements from Main Slider [0.3] or you could select manually content to teleport by using attribute data-swiper=”teleport” |
| ELEMENTS | ||
| 1 | Controls | |
| 1.1 | Next/Prev controls | Buttons that are switching to next or previous slide |
| 1.2 | Pause/Play controls | Buttons that control slider autoplay. If you’re using autoplay, you should incorporate them in the design. |
| 2 | Pagination | |
| 2.1 2.2 | Numbered pagination | Gives an indicator of the active slide and also provides the option to switch slides. |
| 2.3 2.4 | Steps pagination | Gives indication about the current slide and where it is placed among all slides. |
| 3 | Indicators | |
| 3.1 3.2 | Fraction Indicator | Non-interactive element. Gives feedback about the current slide and the count of slides. |
| 3.3 | Progress indicator | Non-interactive element. Gives feedback about the % of slides from the total count of slides. |
| 4 | Autoplay elements | |
| 4.1 | Autoplay duration circular progress bar | Gives feedback on how much time is left until autoplay switches to new slide |
| 4.2 | Autoplay duration circular progress bar with textual feedback in seconds | Gives feedback on how much time is left until autoplay switches to new slide |
| 4.3 | Autoplay duration textual feedback in seconds | Gives feedback on how much time is left until autoplay switches to new slide |
| 4.4 | Next/Prev slide controls with autoplay progress bar | – Buttons that are switching to next or previous slide – Gives feedback on how much time is left until autoplay switches to new slide |
| 4.5 | Autoplay duration progress bar | Gives feedback on how much time is left until autoplay switches to new slide |
| 4.6 | Fraction indicator with autoplay duration progress bar | – Non-interactive element. Gives feedback about the current slide and the count of slides. – Gives feedback on how much time is left until autoplay switches to new slide |
| 4.7 | Steps navigation with autoplay duration circular progress bar | – Gives indication about the current slide and where it is placed among all slides. – Gives feedback on how much time is left until autoplay switches to new slide |
| 4.8 | Pause/Play controls with autoplay duration circular progress bar | – Buttons that control slider autoplay. If you’re using autoplay, you should incorporate them in the design. – Gives feedback on how much time is left until autoplay switches to new slide |
Style guide
When you copy/paste Slider framework component, in structure panel you will see numbered elements. This table below explains each of them.
Next/Prev controls [1.1]
Style them as you would normally style buttons in Breakdance.
Pause/Play controls [1.2]
Style them as you would normally style buttons in Breakdance.
Numbered pagination [2.1, 2.2, 2.3, 2.4]
This element is dynamically made so you need to style it under Advanced > Custom CSS. We have prepared.
There are 3 comments explaining which styles it affect:
- Active – styles related to active slider
- Focus – style related to focus state
- Default – style applied to all elements
Fractional indicator [3.1, 3.2]
Style them as you would normally style text elements in Breakdance.
Progress indicator [3.3]
There are 2 comments explaining which styles it affect:
- Progress bar styles
- Track under progress bar styles
Circular autoplay progress [4.1]
There are 2 comments explaining which styles it affect:
- Circular progress bar styles
- Size styles (max-width)
Circular autoplay progress with countdown [4.2]
Countdown element you should style as you would any text element
There are 2 comments explaining which styles it affect for circular progress:
- Circular progress bar styles
- Size styles (max-width)
Circular autoplay progress with countdown [4.3]
Countdown element you should style as you would any text element.
Next/Prev buttons with circular progress [4.4]
Style them as you would normally style buttons in Breakdance.
Circular progress element you style with Custom CSS, there is one comment which points where you could change color. Style stroke to adjust.
Autoplay progress line [4.5]
There are 2 comments explaining which styles it affect:
- Progress bar styles
- Track under progress bar styles
Fraction indicators with autoplay progress line [4.6]
Style fraction elements as you would style Breakdance text element
There are 2 comments explaining which styles it affect:
- Progress bar styles
- Track under progress bar styles
Dot navigation with circular autoplay progress [4.7]
There are 4 comments explaining which styles it affect:
- Active dot style
- Progress color
- Focus dot styles
- Default dot styles (applies to all dots, active and focus override it)
Pause/Play buttons with circular progress [4.8]
Style them as you would normally style buttons in Breakdance.
Circular progress element you style with Custom CSS, there is one comment which points where you could change color. Style stroke to adjust.
Magics
Magic attributes
Magic attributes
Magics within the Slider Framework are unique custom attributes that transform Breakdance elements into Slider functionalities. These include displaying the number of the current slide, the total count of all slides, an autoplay countdown, and features such as pausing and playing autoplay.
| Attribute | Element | Description |
|---|---|---|
| data-swiper=”currentSlideNum” | Text | This magic attribute will convert any text element to show current slide number on any text element. |
| data-swiper=”countSlideNum” | Text | This magic attribute will convert any text element to show total slide number. |
| data-swiper-autoplay=”countdown” | Text | This magic attribute will convert any text element to show autoplay slide time left. It will count down each second. |
| data-swiper=”stop” | Button | This magic attribute will convert any button element to act as autoplay pause button. |
| data-swiper=”start” | Button | This magic attribute will convert any button element to act as autoplay play button. |
Events
Additional events
Accessibility
Overview – todo
dasd
UX Guidlines
0. Avoid sliders
Sliders are notoriously bad for UX and A11Y. If you could use alternative design, please consider this. If you really want or need to use them please take points below to make it less sucking UX for users.
1. Use bigger dots, or even thumbnails
Usually slider dots are small and hard to click. Clickable area should be at least 24×24 pixels.
2. Alternatives to dots navigation
As alternative approach you could use thumbnail component for navigation instead just dots. Dots don’t provide much information. Also you could use number page navigation instead of dots (bullets) which would at least give more clue about slide numbers.
3. Use only one pagination pattern
Within Slide Framework there are many pagination patterns (bullets-dots, numbers, fraction, and thumbnail). We recommend usage of only one pattern as using dots and thumbnails would make usage of two element with same purpose and lead to harder navigation. Fraction pagination is only exception because it does not offer navigation option, rather just visual indication.
4. Avoid autoplay
Autoplay/autorotation sliders are notoriously hard to use avoid them if you can. If you need autoplay please consider this list:
- Autoplay duration should be at least 5-7s to give users enough time
- Pause button is must, and should be placed above slider in HTML order, if you need it at another position use CSS. Before entering autorotation slider, user should have option to pause it for easier navigation.
- Place next/previous arrows below slider at mobile because this way user interacting with slider will not cover slides by hand in order to navigate. Tip: You could use two sets of elements, and display: none to hide desktop arrows on mobile, and show mobile ones below at smaller screens
- Pause on interaction – when user hovers or interacts with slider, you should pause autoplay as probably he wants to interact and autoplay could move desired content to interact off visible portion of the screen
Autoplay
Autoplay/autorotation sliders are notoriously hard to use avoid them if you can. If you need autoplay please consider this list:
Pause on interaction – when user hovers or interacts with slider, you should pause autoplay as probably he wants to interact and autoplay could move desired content to interact off visible portion of the screen
Autoplay duration should be at least 5-7s to give users enough time
Pause button is must, and should be placed above slider in HTML order, if you need it at another position use CSS. Before entering autorotation slider, user should have option to pause it for easier navigation.
Place next/previous arrows below slider at mobile because this way user interacting with slider will not cover slides by hand in order to navigate. Tip: You could use two sets of elements, and display: none to hide desktop arrows on mobile, and show mobile ones below at smaller screens
Bullet navigation – todo
dasd
Pause/Play Controls – todo
dasd
Previous/Next Controls – todo
dasd
Examples
Autoplay
const scope = document.querySelector('.breakdance .bde-rich-text-393-105').previousElementSibling;
const swiper = scope.querySelector('.swiper').swiper;
swiper.params.autoplay.delay = 1000;
swiper.params.autoplay.reverseDirection = true;
swiper.autoplay.start();