What it is?
This is a niche plugin for building a side slider, this plugin is optimized and designed specifically for use in situations where the cards are placed beyond the horizon of the window and should appear on click or autoplay.
Before use:
- This plugin does not style the tape container and its internal blocks, but only animate them move.
- When switching elements, the slider moves the element to the end or the beginning of the collection of DOM elements, so it works with DOM elements.
- If you need a simple slider, it is better to choose another plugin.
Install:
Usage:
Note
For the plugin to work properly, it needs to be wrapped in a "load" event because it needs to load the entire page to calculate the size.
Advanced:
Don't ignore the comments, they can help you better understand what's going on ;)
Animation to offset the first/last slide
cast-out: "@saschati/side-slider/src/animate/animation/runner/cast-out"
down: "@saschati/side-slider/src/animate/animation/runner/down"
hide: "@saschati/side-slider/src/animate/animation/runner/hide"
left: "@saschati/side-slider/src/animate/animation/runner/left"
right: "@saschati/side-slider/src/animate/animation/runner/right"
scale: "@saschati/side-slider/src/animate/animation/runner/scale"
tornado: "@saschati/side-slider/src/animate/animation/runner/tornado"
up: "@saschati/side-slider/src/animate/animation/runner/up"
fly: "@saschati/side-slider/src/animate/animation/runner/fly"
Animation for shifting adjacent slide elements
hide: "@saschati/side-slider/src/animate/animation/next/hide"
run: "@saschati/side-slider/src/animate/animation/next/run"
scale: "@saschati/side-slider/src/animate/animation/next/scale"
twist: "@saschati/side-slider/src/animate/animation/next/twist"
Documentation
Description of fields and methods and behavior when manipulating them.
Property
The list of possible properties at initialization of the designer.
wrapper: DOM Element object
The DOM Element of the ribbon, all the elements it contains will be ribbon elements. For the correct operation of this container, its position must be different from position: static.
direction: Left | Right
The field responsible for the direction currently has 2 directions, by default Right. The direction should be indicated according to the position from which the tape is located. When changing sides, all effects and logic will be adjusted to this change, in which the first element becomes the last and vice versa.
options.autoplay: Object
A parameter object with which all available slider autoplay options are configured.
options.autoplay.active: boolean
Determines whether the slider should be active by default. After initialization, it will start.
Default: true.
options.autoplay.reverse: boolean
The direction of the ribbon determines whether the ribbon element should appear or disappear.
Default: false.
options.autoplay.duration: number
The time to switch to the next element of the slider. This time will also indicate the playback speed of the animation.
Default: 3000.
options.autoplay.delay: number
The delay before the animation of adjacent slider elements should play.
Default: 1500.
options.autoplay.calculateDelayFromOther: boolean
With the active value will calculate the delay from the values of the user click. Useful when you have determined the ideal delay time for a click and would like this time to have an appropriate autoplay delay.
Default: false.
options.autoplay.chain: boolean
With the active value, the time spent on the animation of the adjacent elements of the slider displacement will be distributed by ACTIVE elements of the slider displacement and will be performed alternately.
Default: true.
options.autoplay.delayedStart: Object
A property that defines the delay after a client click to start autoplay again.
options.autoplay.delayedStart.disabled: boolean
When set to active, the feed will no longer autoplay after a client clicks to promote the slider.
Default: false.
options.autoplay.delayedStart.delay: number
The time after which the feed should be restarted, the time indicated by the delay after the end of the execution of the user's last click.
Default: 10000.
options.runner: Object
A parameter object used to configure the animations and delay of the main element of the slider.
options.runner.wait: number
The time delay before switching slides at the DOM level is necessary for the animation to work before the slider changes the order of elements in the DOM.
Default: 100.
options.runner.animates: function | Array
A parent element's animation function or object to change it. You can see more details about writing your own animations at the #link.
Default: runnerHide.
options.next: Object
A parameter object used to configure the options of the adjacent elements of the slider offset.
options.next.visible: null | number
The number of visible adjacent elements of the tape, the time will be divided by this number, and it will be determined which can move and which cannot. With a default value of null, the ribbon itself will calculate the number of visible elements according to the window, but if each element has its own width, the calculation will not be accurate, and in this case it is better to specify the most optimal value manually.
Default: null.
options.next.optimize: boolean
This value determines whether to optimize the operation of neighboring elements if they are not visible to users, that is, if the user does not see the elements of the ribbon, they do not waste resources and simply stand still, this is useful if there are many graphic actions on the page.
Default: false.
options.next.animates: function | Array
A function or object to animate adjacent slider offset elements. You can see more details about writing your own animations at the #link.
Default: nextRun.
options.client: Object
A parameter object used to configure client click options for slider movement.
options.client.duration: number
The time to switch to the next element of the slider. This time will also indicate the playback speed of the animation.
Default: 750.
options.client.delay: number
The delay before the animation of adjacent slider elements should play.
Default: 375.
options.client.calculateDelayFromOther: boolean
When the value is active, it will calculate the delay from the autoplay values. Useful when you've determined the ideal delay time for autoplay and would like that time to have an appropriate click delay.
Default: false.
options.client.chain: boolean
With the active value, the time spent on the animation of the adjacent elements of the slider offset will be distributed to the ACTIVE elements of the slider offset and will be performed alternately.
Default: true.
options.client.flexibleClick: boolean
When the value is active, the scrolling speed of the slider will be determined by the speed of clicking on the button by the user. Depends on minDuration and prevent options.
Default: true.
options.client.minDuration: number
When the flexibleClick value is active, the minimum threshold for the scrolling speed of the slider when the user clicks on the button will be determined.
Default: 250.
options.client.prevent: boolean
Does not allow acceleration of the slider, but waits for the end of the click. That is, if the value is false, the tape will stop switching only when it reproduces all clicks on the client's button or when the direction is changed.
Default: true.
options.client.button: Object
This option defines the controls of the slider by the client.
options.client.button.prev: HTMLElement | null
A slider control that displays an element.
Default: null.
options.client.button.next: HTMLElement | null
A slider control that hides an element.
Default: null.
options.client.speedUp: Object
This option defines slider acceleration controls during autoplay.
options.client.speedUp.active: boolean
If the value is active, it will speed up the autoplay of the tape to the speed specified in the click settings.
Default: true.
options.client.speedUp.forceNext: boolean
If the value is active, after the acceleration of the tape, it also performs a click, accordingly, in the disabled mode, only acceleration will be performed.
Default: true.
options.mutation: Object
A parameter object with which slider mutations are configured. Mutations are pseudo events when an element goes into one of the states, is used for additional customization of elements by the user. Mutations must be fast because they perform the role of customization an element or adding certain elements to it. Mutations are useful in that the user is not limited by a set of user customizations.
options.mutation.onRun: function | null
A mutation that is triggered when the main element of the slider is hidden/appeared.
Default: null.
options.mutation.onDone: function | null
A mutation that is triggered when the main element of the slider is hidden/revealed.
Default: null.
options.mutation.onActive: function | null
A mutation that is triggered when the neighboring elements of the slider become the main one.
Default: null.
options.mutation.onUnActive: function | null
A mutation that is triggered when the neighboring elements of the slider that became the main one goes into the stage of hiding/manifesting or becomes secondary.
Default: null.
options.mutation.onVisible: function | null
A mutation that is triggered when the elements of the tape are visible to the user.
Default: null.
options.mutation.onUnVisible: function | null
A mutation that is triggered when the elements of the tape are NOT visible to the user.
Default: null.
options.mutation.onSwitched: function | null
By default, this is a reserved mutation that is performed after a slide switch and clears all element styles. Changing it can lead to undesirable results, so try to extend this mutation, not replace it.
Default: null.
options.mutation.onClickStart: function | null
A mutation that is triggered when the user clicks on the slider control element.
Default: null.
options.mutation.onClickFlushed: function | null
A mutation that is launched after the control element clicked by the user has worked.
Default: null.
options.timing: function
A time function that determines the animation's running time. You can see an example of how time functions work in the documentation.
Default: linage.
options.reverse: function
An inverted time function according to the normal function required for reverse animation. This value must be a function that takes a time function and inverts it.
Default: reverse.
options.animate: function
A class for working with animation. This class can be expanded and rewritten to suit your needs, see the class code at the link.
Default: Animate.
options.optimize: boolean
Optimize the slider operation process when the user does not see it.
Default: true.
Methods
List of available methods.
async boot(): void
Downloading the configuration and preparing the plugin to work.
async triggerClientClick(reverse = false): void
Params:
async triggerAutoplay(reverse = false): void
Params:
stopAutoplay(): void
Stops the autoplay of the slider.
async delayedAutoplay(): void
Stops autoplay and starts a timer to restart according to the slider's autoplay settings.
API
Utilities for creating your own animations, etc.
Animations
You can create your own animations and pass them to the plugin for playback. In total, there are two types of creating animations: an anonymous function, or an array of objects, like how animations work with css.
function (info = NextInfo|RunnerInfo, progress = number): void
Params:
An example of the code above. With the help of the callback function, we wrote a primitive animation that will work both for showing and hiding. Also an important point is the work of the function info.getReverseFinishedPosition(), this function returns the final position of the element in x, when it is hidden it returns 0, but when it is displayed there will be a required distance, it is the basis for reverse animation.
RunnerInfo: class
Methods:
NextInfo: class
Methods:
[{progress: number, draw: function, timing: function}, ...]: Array
Properties:
An example of the code above. With the help of an array of objects, we have already written a more complex animation that will work both for showing and hiding. Another important point is the work of the info.getSiblingDistance() function, this function returns the final position of the element in x regardless of the size and other parameters of the neighboring object.
Styling tips:
Because the library translates the stylization and shaping of the tape flow to the user, there are some rules that it must follow in order for the tape to behave stably.
The tape must position itself differently from static.
Why do it? - Because the positions of the tape elements calculate their position and the required distance using the offset(Left|Top|Width|Height) properties, and these properties work according to the element in which the position is not static. You can read more at the link.
You can significantly increase the performance of the plugin if you add the following css code according to your mutations.
You can read more about it at the link.
Also:
If you know how to solve the problems above, or you find another bug, you can:
- Create a pull request with changes.
- Write about a bug or suggestion in issues.
- Also, if you have created a cool animation using this plugin, you can also share it and add it to the plugin collection :)