Skip to content

Commit c903ef6

Browse files
ivanvermeyenivanvermeyen
committed
Add documentation to readme
1 parent ca83115 commit c903ef6

File tree

1 file changed

+280
-2
lines changed

1 file changed

+280
-2
lines changed

‎README.md‎

Lines changed: 280 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,286 @@
22

33
[View Demo](https://codezero-be.github.io/jquery-slider/) - [Tinker with CodePen](https://codepen.io/ivanvermeyen/pen/yMWvOR)
44

5-
## Work in progress!
6-
This plugin is not officially released yet.
5+
Is this the best, most advanced slider out there? No, not at all…
6+
But even with all its features, the slider I was using before didn’t do exactly what I was looking for. So here we are.
7+
8+
## The main goal of this slider is to…
9+
- be able to horizontally traverse through slides,
10+
- allow any HTML content in a slide,
11+
- also be an image slider right out of the box,
12+
- allow slides with fixed and auto widths and heights,
13+
- move 1 slide at a time and center it in the viewport,
14+
- move 70% of the viewport, if the widest slide is less than 30%,
15+
- align slides left, center or right when the viewport is wider than the slides,
16+
- make all of this as customizable as possible…
17+
18+
## Contents
19+
- [Requirements](#requirements)
20+
- [Installation](#installation)
21+
- [Usage](#usage)
22+
- [Basic Setup](#basic-setup)
23+
- [Slide Backgrounds](#slide-backgrounds)
24+
- [Image Slides](#image-slides)
25+
- [Auto Width Image Slides](#auto-width-image-slides)
26+
- [Full Width Image Slides](#full-width-image-slides)
27+
- [Covered Width Image Slides](#covered-width-image-slides)
28+
- [Image Hover Overlay](#image-hover-overlay)
29+
- [Image Caption](#image-caption)
30+
- [Options](#options)
31+
- [Development](#development)
32+
- [License](#license)
33+
34+
## Requirements
35+
- [jQuery](https://jquery.com/)
36+
- [jQuery.scrollTo](https://github.com/flesler/jquery.scrollTo)
37+
- [jQuery-Touch-Events](https://github.com/benmajor/jQuery-Touch-Events) (if you want swiping)
38+
- Modern browser (**not** IE 9 or less)
39+
40+
## Installation
41+
42+
### Via Bower
43+
```
44+
Coming soon
45+
```
46+
47+
### Via NPM
48+
```
49+
Coming soon
50+
```
51+
52+
### Include JS and CSS
53+
```html
54+
<!-- Important slider styling -->
55+
<link rel="stylesheet" href="css/slider.css">
56+
57+
<!-- Required 3rd party scripts -->
58+
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js"></script>
59+
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-scrollTo/2.1.0/jquery.scrollTo.min.js"></script>
60+
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-touch-events/1.0.8/jquery.mobile-events.js"></script>
61+
62+
<!-- Slider script -->
63+
<script src="js/slider.js"></script>
64+
65+
<!-- Kickoff the slider -->
66+
<script>
67+
$('.slider').slide();
68+
</script>
69+
```
70+
71+
## Usage
72+
73+
### Basic Setup
74+
The following snippet is the base skeleton of a slider.
75+
76+
```html
77+
<div class="slider">
78+
79+
<a href="#" class="slider-prev">&langle;</a>
80+
<a href="#" class="slider-next">&rangle;</a>
81+
82+
<div class="slider-viewport">
83+
<div class="slider-track">
84+
85+
<div class="slide">
86+
<!-- Slide Content -->
87+
</div>
88+
89+
</div>
90+
</div>
91+
92+
</div>
93+
```
94+
95+
By default, each slide will have an **auto width and height**.
96+
You can specify a fixed width and height in CSS yourself,
97+
or [change some variables](src/scss/_variables.scss) if you are compiling SCSS.
98+
99+
If you want every slide to take up 100% width of the viewport, simply add the `slide-full-width` class to the `.slider`.
100+
Or if you want only specific slides to be 100% wide, you can add the `slide-full-width` class to that `.slide`.
101+
The latter is probably less useful...
102+
103+
The slide content can really be anything. Paragraphs, headings, images, ... Style it however you want.
104+
105+
Remember the `.slide` is a `flex` child, so you might want to wrap your content
106+
in another `<div>` for easier styling or positioning...
107+
108+
### Slide Backgrounds
109+
You can [change some variables](src/scss/_variables.scss) to choose default backgrounds for your slides,
110+
write your own styles or use a `data-background` attribute to set a specific background image on a slide.
111+
112+
If you want the background to zoom in when you hover over it, use `data-zoom-background` instead.
113+
You can set your own zoom effect in the [variables file](src/scss/_variables.scss),
114+
as long as it's a valid CSS `transform` value.
115+
116+
```html
117+
<div class="slider slide-full-width">
118+
119+
<a href="#" class="slider-prev">&langle;</a>
120+
<a href="#" class="slider-next">&rangle;</a>
121+
122+
<div class="slider-viewport">
123+
<div class="slider-track">
124+
125+
<div class="slide" data-background="path/to/bg-image.jpg">
126+
<!-- Slide Content -->
127+
</div>
128+
129+
</div>
130+
</div>
131+
132+
</div>
133+
```
134+
135+
### Image Slides
136+
Image slides have specific markup and default styling out of the box.
137+
The only thing you might want to hook up yourself is any lightbox you prefer.
138+
139+
#### Auto Width Image Slides
140+
To restrain the image size, you might want to specify a `max-height` for the `<img>`.
141+
If you set the `$slide-height` [variable in SCSS](src/scss/_variables.scss),
142+
this is done automatically.
143+
144+
```html
145+
<div class="slider">
146+
147+
<a href="#" class="slider-prev">&langle;</a>
148+
<a href="#" class="slider-next">&rangle;</a>
149+
150+
<div class="slider-viewport">
151+
<div class="slider-track">
152+
153+
<div class="slide">
154+
<a href="path/to/original-image.jpg" class="slide-image">
155+
<img src="path/to/image-thumb.jpg">
156+
</a>
157+
</div>
158+
159+
</div>
160+
</div>
161+
162+
</div>
163+
```
164+
165+
> Note that the `.slide-image` doesn't have to be a link.
166+
> It can also just be a `<div>`.
167+
168+
#### Full Width Image Slides
169+
Again, you can make each slide full width by adding the `slide-full-width` class.
170+
The clickable `.slide-image` element will be centered inside the slide.
171+
172+
```html
173+
<div class="slider slide-full-width">
174+
175+
<a href="#" class="slider-prev">&langle;</a>
176+
<a href="#" class="slider-next">&rangle;</a>
177+
178+
<div class="slider-viewport">
179+
<div class="slider-track">
180+
181+
<div class="slide">
182+
<a href="path/to/original-image.jpg" class="slide-image">
183+
<img src="path/to/image-thumb.jpg">
184+
</a>
185+
</div>
186+
187+
</div>
188+
</div>
189+
190+
</div>
191+
```
192+
193+
#### Covered Width Image Slides
194+
To make the `.slide-image` element also full width, replace the `slide-full-width` class with `slide-cover-width`.
195+
Now only the image is still centered inside the `.slide-image` element, which makes sense since we don't want to stretch it out.
196+
197+
However, to set the image as a background, covering the entire slide,
198+
simply add the `slide-image-background` class to the `<img>`.
199+
Note that this will probably crop the image to fit the slides dimensions.
200+
201+
```html
202+
<div class="slider slide-cover-width">
203+
204+
<a href="#" class="slider-prev">&langle;</a>
205+
<a href="#" class="slider-next">&rangle;</a>
206+
207+
<div class="slider-viewport">
208+
<div class="slider-track">
209+
210+
<div class="slide">
211+
<a href="path/to/original-image.jpg" class="slide-image">
212+
<img src="path/to/image-thumb.jpg" class="slide-image-background">
213+
</a>
214+
</div>
215+
216+
</div>
217+
</div>
218+
219+
</div>
220+
```
221+
222+
#### Image Hover Overlay
223+
Want to show a zoom icon when you hover over the image? Just add it...
224+
225+
```html
226+
<div class="slide">
227+
<a href="path/to/original-image.jpg" class="slide-image">
228+
<!-- Note: this icon requires Font Awesome... -->
229+
<!-- Use any library you like... -->
230+
<i class="fa fa-search-plus slide-image-hoverlay"></i>
231+
<img src="path/to/image-thumb.jpg">
232+
</a>
233+
</div>
234+
```
235+
236+
Or just show some text...
237+
238+
```html
239+
<div class="slide">
240+
<a href="path/to/original-image.jpg" class="slide-image">
241+
<span class="slide-image-hoverlay">VIEW</span>
242+
<img src="path/to/image-thumb.jpg">
243+
</a>
244+
</div>
245+
```
246+
247+
#### Image Caption
248+
Same as the hoverlay, if you would like to display an image caption, just add the element...
249+
250+
```html
251+
<div class="slide">
252+
<a href="path/to/original-image.jpg" class="slide-image">
253+
<img src="path/to/image-thumb.jpg">
254+
<span class="slide-image-caption">
255+
Beautiful example image!
256+
</span>
257+
</a>
258+
</div>
259+
```
260+
261+
## Options
262+
If you are using SASS/SCSS, there are a bunch of variables you can tweak to change the behavior of the slider.
263+
I have added comments, so I hope it will be clear what each option will do.
264+
Just take a look at the [variables file](src/scss/_variables.scss).
265+
266+
The javascript side also has some options. These are also commented so I would again suggest to
267+
take a look at the `defaults` object in the [javascript source file](src/js/slider.js).
268+
269+
Overriding the defaults would take the form of:
270+
271+
```javascript
272+
$('.slider').slide({
273+
slideSpeed: 300,
274+
enableSwipe: false
275+
});
276+
```
277+
278+
## Development
279+
I am using a tool called [Laravel Mix](https://github.com/JeffreyWay/laravel-mix) to compile javascript and SCSS.
280+
Make sure you have the latest version of [NodeJS](https://nodejs.org/en/) installed and then run `npm install`.
281+
282+
- To compile run `npm run dev`.
283+
- To compile and watch for changes run `npm run watch`.
284+
- To compile for production (minify/uglify) run `npm run production`.
7285

8286
## License
9287
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

0 commit comments

Comments
 (0)