# “jSlider”

Created: 4/16/2015
By: Thuy Nguyen
Email: ducthuy@gmail.com

## Table of Contents

1. HTML Structure
2. CSS Files and Structure
3. JavaScript

### A) HTML Structure - top

Basicly, you will need to include the CSS files & JS files within a HEAD tag. I suggest you to use the latest jQuery. Download from here.
You need to make sure "jSlider.css", "jQuery" & "jquery.jSlider.js" are included & loaded correctly. (For JS files, you are allowed to place them at the bottom of the page to keep the page rendering wihout being blocked.)

    <link rel="stylesheet" type="text/css" href="assets/css/jSlider.css" />
    <script type="text/javascript" src="assets/js/jquery-latest.min.js"></script>
    <script type="text/javascript" src="assets/js/jquery.jSlider.js"></script>

For responsive layout, you need to have "viewport" meta setup as in the screenshot above.

This jSlider is generated using a DIV tag. You will need a wrapper which have the class name "jSlider". Then, inside the wrapper, each slide will be place in a sub DIV. Mostly, the content is image but you still can use other tags to display other things.

    <div id="slider1" class="jSlider" data-loop="true">
    	<div><img src="images/photo1.jpg" alt="" /></div>
    	<div><img src="images/photo2.jpg" alt="" /></div>
    	<div>
    		<img src="images/photo3.jpg" alt="" />
    		<div class="sub-content-sample">
    			<p>Lorem ipsum dolor sit amet, <a href="http://jquery.com/" target="_blank">consectetur adipiscing elit</a>, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
    		</div>
    	</div>
    	<div><img src="images/photo4.jpg" alt="" /></div>
    	<div><img src="images/photo5.jpg" alt="" /></div>
    	<div><img src="images/photo6.jpg" alt="" /></div>
    </div>

Do not specify slide image dimension (width & height).

Done! the slider is ready!

Animated content

If you wish to have some nice & simple animated content showed when a slide is active, please add some special classes to the elements as showed in the below screenshot. Remember to specify the position:absolute as well as top, left position of each "appear-*" element.

    <div id="slider1" class="jSlider" data-delay="0">
    	<div><img src="images/photo1.jpg" alt="" /></div>
    	<div class="selected">
    		<h3 class="appear-top">This is the slide title!</h3>
    		<h4 class="appear-right">This can be moved after the slide is showed...</h4>
    		<p  class="appear-left">...in different directions...</p>
    		<p  class="appear-bottom">...and with different animation effects</p>
    		<h5 class="appear-fade">powered by jSlider!</h5>
    		<img src="images/photo2.jpg" alt="" />
    	</div>
    	<div><img src="images/photo3.jpg" alt="" /></div>
    	<div><img src="images/photo4.jpg" alt="" /></div>
    	<div><img src="images/photo5.jpg" alt="" /></div>
    	<div><img src="images/photo6.jpg" alt="" /></div>
    </div>

#### Customization by using DATA Properties

This jSlider options are managed using "data-*" properties. You can add them to the wrapper as below:

    <div id="slider1" class="jSlider" data-navigation="always" data-indicator="none">

Here is the document about "data-*" options:

- data-navigation: this manages the display of previous / next buttons.
  This can be set to "always", "none" or "hover".
  "hover" is set by default which means the buttons will appear when users move their mouse hover the slider.
  On mobile, "hover" is equal to "none".
- data-indicator: this manages the display of pagination buttons at the bottom of the slider.
  This can be set to "always", "none" or "hover".
  "always" is set by default.
  On mobile, "hover" is equal to "none".
- data-speed: this manages transition speed of the slider in milliseconds.
  The default value is "500".
- data-delay: this manages autoplay delay time between each transition of the slider in milliseconds.
  The default value is "5000". (5 seconds)
  If you do not want the autoplay, set it to "0" (zero)
- data-transition: this manages transition type of the slider.
  This can be set to "slide" or "fade".
  "slide" is set by default.
- data-loop: this manages slide loop. If set to "true", when the slider reach to the end the next slide will be first slide. Vice versa.
  This can be set to "true" or "false".
  "false" is set by default.
  "true" is best use for fade effect & in background mode.
- data-group: this manages slide group. You will define the group of elements in each slide. This is a specialize property for gallery mode. In "fade" transition, the value is always "1".
  The default value is "1".

### B) CSS Files and Structure - top

Normally, the CSS of jSlider is just fine. You will not need to modify it except the slider dimension (width & height), the display of the buttons (previous / next buttons & pagination buttons.)

You are recommended not to modify the "jSlider.css" file which is the main core CSS file of jSlider. It contains many important CSS rules.

To specify the slider dimension & modify the previous / next buttons as well as the pagination buttons at the bottom of the slider, I suggest you to use another CSS file & override the CSS rules.

Slider dimension
The slider width & height are managed by using CSS rule. You can use reponsive rules to resize the slider width & height for each screen size.
Auto height: You can the slider height to AUTO. The slider height will automatically set to the height of the first image in the first slide.

### C) JavaScript - top

Acctually, you don't need to do Javascript code except you have to generate the slider from Ajax content or you have to force the slider to move to the specific slide.
Below is the list of API functions:

Methods:

- sliderInit: generate a new slider. Remember that, you should not have class "jSlider" in the wrapper. You can specify the slider options in the function *.

      $('#sliderId').sliderInit({settings});

- sliderStop: cancel autoplay

      $('#sliderId').sliderStop();

- sliderGo: go to next or previous slide.

      $('#sliderId').sliderStop(direction);

  You must specify the direction value (1 or -1): go forward 1, go backward -1.
- sliderUpdate: go to a specific slide

      $('#sliderId').sliderUpdate(index);

  You must specify the slide index. The first slide index is "0" (zero).

*About settings: {settings} is an object value which is the same as "data-*" properties mentioned earlier in the DATA Properties. Below is the default settings.

    {
        'navigation':   'hover'       /* hover | always | none */
        , 'indicator':  'always'      /* hover | always | none */
        , 'speed':       500
        , 'delay':       5000
        , 'transition': 'slide'       /* slide | fade */
        , 'loop':        false        /* false | true */
        , 'group':       1
    }

Events:

- slideCreated: this event is fired when the slider is created.

      $('#sliderId').on('slideCreated', function(evt) {
          /* do something */
      });

- slideStart: this event is fired when the slider begin a transition.

      $('#sliderId').on('slideStart', function(evt) {
          /* do something */
      });

- slideComplete: this event is fired when the slider finish a transition. You can access the current slide index in event value.

      $('#sliderId').on('slideComplete', function(evt) {
          alert(evt.current);    /* return the current slide index */
      });

- slideCancelAutoPlay: this event is fired when the autoplay is canceled.

      $('#sliderId').on('slideCancelAutoPlay', function(evt) {
          /* do something */
      });

##### Thuy Nguyen