II. Installation

As I mentioned earlier, it’s not much of an installation, but I felt I needed to include it in the doc anyway.

Just copy slider.js in your scripts folder and include it in your page, just after jQuery:

III. Getting Started

Enough words, let’s see Slider.js in action. We are going to build a really simple slider in this Chapter and I’ll introduce you to the basic workflow of using this framework. It might be confusing at first, but I promise you it will make sense in the next Chapters.

The HTML

Let’s throw it some HTML for a start. As I said, we’ll keep it simple for now:

Pay attention to the classes - they need to have those names if you want to avoid redefining class names (more on that in Chapter 8. We have a wrapper and four slides in it. As simple as it gets. As for the CSS, I believe you can figure it out (hint: slides are absolutely positioned at 0,0).

That’s all there is to the HTML.

The JavaScript

Now, the JavaScript. First of all, what do we want our slider to do? We want every 3 seconds the next slide to fade in. Here we go:

And that is all. 10-15 lines of code is all we need to make this slider work.

Now let’s go through each step and see what we did and why:

Not much to explain here, you are making a new object, named “slider” which will be the reference to the actual slider. You will need that object in order to use hooks, redefine classes, etc.

In the first line we are basically saying: for the slider named slider, when the event show_slide occurs, call the function my_transition_effect. That’s how you hook in the slider’s functionality, and that’s an example of where you’ll need that object named “slider” that you made earlier.

There are many hooks available, for example transition_complete, which fires when, well, the transition completes. See Chapter 6 for all hooks that are available.

In the second line we are hooking to the view_init event and we are calling the function initial_settings when it occurs.

Next, we are firing up the slider:

Only after this line it will actually start ticking. We are calling the method init on our slider object and as arguments we are passing the interval for changing the slides and how long the transition takes, in milliseconds. We need to specify the length of the transition if we want to avoid that annoying animation stacking, or queueing. There is a built-in mechanism in the framework that prevents that, but we need to tell it how long each transition lasts.

Finally, we are defining the two functions “initial_settings” and “my_transition_effect”:

Here we are using the API that the framework provides in order to access useful information about the current state of the slider, and we are also using a method, provided by the framework.

When you are inside a hook function, you have access to the this object, which gives you the API. For example, we are calling the z_move_to_top method, which takes an index as an argument and moves the slider with that index on top of all slides, by using the “z-index” style. We get the index of the currently active slide with this.current_slide_index and pass it on to the method.

We will talk more about the z_move_to_top method later, it does so much more that it seems. More of that in Chapter 7.

In the second function my_transition_effect we are telling the slider to put the currently active slide on top (we need to do that on each transition in order to see the new slide) and we are referencing the element itself to do some basic jQuery animations: we hide it and then fade it in. Nothing fancy (yet). The important note here: when the transition occurs, the current_slide is now the slide that is supposed to transition in.

One more thing that the API provides - a reference to some key slides like - current, “breadcrum”, next, previous, first, last. We’ll talk about these in Chapter 7.

Conclusion

I really hope you got a basic idea of how much work Slider.js actually saves you. In the next couple of Chapters we’ll find out more about what components Slider.js can work with and we’ll dig deep to see how it... ticks. I highly recommend you read it carefully, as it will give you a better idea of the power of this framework. Moving on...

IV. Components of a Slider

Components? You know, next/prev arrows, ticker, etc. Here is a nice illustration of pretty much everything that Slider.js understands, as of version 1.0:

1. Wrapper

Not much to explain here, it’s just the main element that holds everything in the slider.

Usage:

2. Slide

By “slides” Slider.js understands the elements that will cycle. You can put whatever content you want in that element - image, text, video, doesn’t matter.

Usage:

3. Ticker

That’s an interesting one. In it’s most basic form, it has a number of elements inside, one for each slide, and one of those elements has a class, indicating that the corresponding slide is the currently active one. It’s a simple, but powerful concept and you can use it in many ways. Please refer to the demo page to see it used in a few different ways.

Usage:

NOTE: Make sure that the number of tickers is the same as the number of slides!

4. Next/Prev arrows

Easy one. When you click “next”, the next slides transitions in. I assume I don’t have to explain what “prev” does.

Usage:

5. Play/Pause button

Pressing it once will stop the slider in it’s current state. Pressing it again will fire it up again.

Usage:

6. Inner content

That’s a little bit specific element. It’s useful in the situation where you have one element inside the slide, which you have to animate or do things with. It’s just there for a bit of conveniece if you happen to have that scenario.

Usage:

NOTE: The inner content box must be inside the main element of the slide!

7. Outer content

An “outer content” is an element, linked to a specific slide. For example: a piece of text, relevant to the contents of the slide. Because the “outer content” sits outside of the slide, it can be animated separately, which is very useful and adds many possibilities.

There’s a slider utilizing this component in the Demo page. Please check it, you’ll get a better idea of what it does.

Usage:

8. Pagination

Simple one. Shows the index of the current slide and the total number of slides.

Usage:

9. Grid

The grid is probably one of the most powerful features of this framework, and it saves you loads of work and hair pulling in order to make it work. A couple parameters (rows and columns) when you initialize the plugin and there you go - every slide is sliced up in a grid.

From there on, a simple loop through every piece of the grid will give you a beatifully animated transition and it’s ridiculously easy to pull off, thanks to Slider.js.

Usage: see Chapter 7!

10. Loader

This could be a loading bar, a circle, you decide. You can read more about how to utilize the loader in the next Chapter, where I explain in detail how it works.

Usage:

Conclusion

That’s all, as you can see it’s a simple but solid concept, used by many, if not all sliders out there. In Chapter 5 I will explain in detail how each component is used in the framework in order to make the slider work.

V. Under the Hood

Moving on, let’s actually find out more about the framework’s logic. In the following illustration you will see a generalized version of what actually happens while the slider is working. I haven’t included every single function, only the hooks that you can ... hook up to. In the next Chapter we’ll learn how to use the hooks, for now we’ll just talk about when to use them. Let’s have a look:

In Chapter 3 we used two of those hooks - view_init and transition_in and now you know where they are in the event chain. Now is the time to say, that some of those hooks are pure abstractions and it doesn’t matter too much if you use transition_in or show_slide to animate the currently active slide. It doesn’t matter in terms of functionality, but it will just look cleaner and the code will be easier to read and will make more sense.

For example, if you have a ticker and you want to do something cool with it whenever it updates, you’d want to put that code in the update_ticker hook. You get the idea.

The illustration pretty much explains it all, but let me say a few words about it as well.

The cycle starts with view_init, which is called only once, when you initialize the slider, like we did in Chapter 3 with the method init(). That’s the place where you’d want to make the initial setup, like we did. In our example we only wanted to put the first slide (in view_init that’s this.current_slide) on top, so it gets shown first when the slider fires up.

Before view_init gets called, the controller (yes, I coded everything using the MVC model) has already set up the main interval, so show_slide eventually gets called, which calls a series of functions. I already explained why it’s not only a single function, but anyway, here’s what code you’d want to put in each hook:

transition_in : code dealing with how the next slide appears;

transition_out : code dealing with how the current slide disappears;

busy : that’s an interesting one. It takes the transition_length parameter (you set that parameter when you initialize the slider) and it “locks” the slider, so it won’t accept any commands, until the transition completes. That’s done so we can avoid that nasty animation queueing or in some cases, braking the slider if we went all out on the animations.

The important thing to note about the busy hook is that when the “busy” state ends, it calls transition_complete. More on that below.

update_ticker : not much to explain here, put the code that deals with the ticker in this hook;

update_pagination : same as above;

start_loading, loading_update, loading_complete : put the code that handles the loading bar in start_loading, if you have it in your slider. That’s the place that you’d want to show the bar, or anything that deals with it’s initial setup. Similarly, put the code that you want to execute when the loading finishes in loading_complete.

This is the place to explain how the loader works. When it fires up, it will start calling loading_update and with each call it will pass you a number, starting from 0. When that number reaches 100, loading_complete gets called. The time it takes for that number to reach 100 depends on the transition_length parameter, which you specify when you initialize the slider.

transition_complete : gets called when the slider leaves the “busy” state. This hook is really useful, you can achieve really nice effects with it. For example in one of the sliders in the Demo page I made it so the outer contents update only after the new slide animates in. That’s only one use of it, of course you can do whatever you want with that hook, the possibilities are endless.

At this point the cycle waits for the main interval (the one that switches the slides) and then resets.

Now let’s talk about the user-triggered events:

arrow_next_click, arrow_prev_click, ticker_click : all three of those call show_slide when the event occurs, and tell it which slide to show, depending on the event.

Before show_slide gets called, the main interval is reset. For example, if the delay between switching slides is 3 seconds and the user clicks the “next” arrow after two seconds, the next slide appears immediately, and it will take 3 more seconds before the slide after that appears automatically.

play_pause_click : not much to explain here. When the user presses that button, the main interval is cleared. When the user presses it again, the interval is reset and the main loop starts all over again width the show_slide hook.

Conclusion

That’s pretty much it for this Chapter, I hope that now you have a good idea of how this framework works and you should be able to take full advantage of it’s functionality.

In the next two Chapters we will go into how to use the hooks and how to get access to tons of useful information, DOM element references and methods through the API that the framework provides.

VI. Hooks

In the last Chapter we learned about the different hooks available in the framework, now let’s see how to actually use them. I’m a big fan of learning through practice, so let’s consider an example.

You have a slider and you want to show additional information to the user when he presses the pause button. No problem, we’ll use the play_pause_click hook.

First of all, let’s define a function that will actually show the content. For the sake of simplicity, we are just going to call show() on an element which supposedly has the content that we want to show:

Now we want this function to get called whenever the user presses the play/pause button. Here’s how you use hooks:

And in our case:

For the event name we used “play_pause_click”, and we are calling the function show_content when that event occurs. If you have developed plugins for WordPress, you will be immediately familiar with this workflow.

Following there’s a list of all hooks available. They are split in two categories, depending on the source of the event.

Triggered by the main cycle

User-triggered

In the previous Chapter I explained when it’s appropriate to use each hook, if you need a refresher, here is the illustration again:

Conclusion

That’s pretty much everything you need to know to use the hooks properly. In the next Chapter, we’ll discuss the API - the stuff that you have access to from the functions that you attach to the hooks. It’s good stuff, don’t skip the next Chapter! :)

VII. API

Let’s consider the example from the previous Chapter:

We skipped one important thing there. We want the #content element to be shown only when the sliders is paused, not every time the user clicks the play/pause button. We can get the current state of the slider (if it’s playing or paused) through the API, like this:

And now we can modify out function to show the extra content only when the user has clicked pause:

Now to summarize, two important things to note:

1. this will point to the API only when you are inside a function that is attached to a hook with sliderjs_event().

2. The API that “this” points to is different in the user-triggered events! For more information to what you have access to in that case, please look at the list of all properties below.

List of all API properties and methods

id : the unique ID of the slider

current_slide : jQuery reference to the slide that is currently active. Have in mind, that in the transition_in hook for example, this will point to the slide that is supposed to appear!

next_slide : jQuery reference to the slide after the active one;

prev_slide : jQuery reference to the slide that sits before the active one. IMPORTANT: this does NOT point to the last active slide, but to the one that sits just before the currently active one

breadcrum_slide : jQuery reference to the last active slide. Example: if we are at slide 4 and the user clicks the ticker, pointing to slide 1, the current_slide property will point to 4, and breadcrum_slide will point to 1

first_slide : jQuery reference to the first slide

last_slide : jQuery reference to the last slide

slides : an array containing jQuery references to all slides

current_slide_index : the index of the currently active slide

next_slide_index : the index of the slide that’s supposed to come after the currently active one

prev_slide_index : the index of the slide that sits before the currently active one. NOT the same as breadcrum_slide!

breadcrum_slide_index : the index of the last active slide

first_slide_index : the index of the first slide

last_slide_index : the index of the last slide

grid_rows : two-dimentional array with jQuery references to all rows in the grid and their elements. For example, you would get the 8th grid piece from the 3rd row like this: grid_rows[3][8]

grid_cols : two-dimentional array with jQuery references to all columns in the grid and their elements. For example, you would get the 6th grid piece from the 2rd row like this: grid_rows[2][6]

rows : the total number of rows in the grid

cols : the total number of columns in the grid

inner_content_box : jQuery reference to the current slide’s inner content box.

inner_content_boxes : array with jQuery references to all slides’ inner content boxes

outer_content_box : jQuery reference to the element that holds the outer contents

outer_contents : array containing jQuery references to all slides’ outer contents

current_outer_content : jQuery reference to the element which has the current slide’s outer contents

next_outer_content : jQuery reference to the element which has the next slide’s outer contents

prev_outer_content : jQuery reference to the element which has the previous slide’s outer contents

breadcrum_outer_content : jQuery reference to the element which has the last active slide’s outer contents

first_outer_content : jQuery reference to the element which has the first slide’s outer contents

last_outer_content : jQuery reference to the element which has the last slide’s outer contents

active_ticker : jQuery reference to the currently active ticker element

prev_ticker : jQuery reference to the ticker element before the currently active one

next_ticker : jQuery reference to the ticker element after the currently active one

first_ticker : jQuery reference to the first ticker element

last_ticker : jQuery reference to the first ticker element

breadcrum_ticker : jQuery reference to the last active ticker element

loader_wrap : jQuery reference to the element which holds the loading bar (if it’s a bar at all)

pagination_current_slide : the number of the current slide

pagination_slides_count : the count of all slides

play_pause_button : jQuery reference to the play/pause button

arrow_next : jQuery reference to the “next” arrow

arrow_prev : jQuery reference to the “prev” arrow

state_play : the current play state of the slider. Either true or false

z_move_to_top : a method, which accepts a slide’s index as an argument and moves it on top of all slides.

List of API properties in the user-triggered hooks

event : the actual event object of the event.

state_play : the current play state of the slider. Either true or false

NOTE: I wasn’t really sure whether to include the properties related to the slides’ inner content, as they seem kind of useless to me, but I’ll leave them like this for now. It’s very possible that they get removed in future versions.

Important

I want to spend an extra minute to properly explain what’s the deal with that “breadcrum” property. In the following illustration you will see how Slider.js looks at the slides - which one is first, last, breadcrum and so on:

Please go through the illustration a couple of times, it’s really important that you understand it properly.

Conclusion

So now we know everything about the hooks and the API. We are almost good to go! There’s only one key element left - what if you want to have mroe than one slider on the same page? Or you want to use different class names? That will be the topic of the next Chapter, it will be a short one.

VIII. Custom Class Names

There are two cases where you’ll need to use custom class names:

• you want to have more than one slider on the same page;
• you want to use different class names.

That’s easily done with the define_class method, which is in the slider’s object.

Let’s consider a very simple example. You have a slider in the page, but for layout purposes you want the main wrapper’s class name to be different than sliderjs-wrap. You proceed like this:

Again, slider_object is the object that you created in the first line of JavaScript code in Chapter 3. You call it’s define_class method and you pass two arguments - the class identifier and the new class name. You can do this for every pre-defined class that Slider.js uses.

In our example, the identifier that we will need is slider_wrap:

Here is a list of all class identifiers and their defaults:

Conclusion

Now you know how to use custom class names, and that pretty much concludes this documentation. In the next Chapter you’ll find out about the various learning resources that I’ve provided, like examples, a handy quick reference and video tutorials.

IX. Learning Resources

Video Tutorials

I have recorded four video tutorials for building every slider from the Demo page, step by step. If you are still confused about a certain feature, I suggest watching those!

Quick Reference

In the Quick Reference page you will find a list of all available hooks, API properties and pre-defined classes, with a short description. Really handy for... quick reference.

Examples

These are three sliders, taken from the Demo page and below every slider you will find it’s HTML and JavaScript code. Pay attention that the JavaScript code is less than the HTML!

Example 1:

Example 2:

Slider.js Demo

Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney

Slider.js Demo

Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney

Slider.js Demo

Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney

Example 3:

1

2

3

4

5

6

This is a demonstration of Slider.js

This box sits outside of the slides, and after every transition the content specific to the current slide...

... is animated in.

Also, there are many ways that you can use the ticker.

Here we are just indicating on which slide we are on, and when we click on a ticker we go to that slide.

The example below shows another cool way of using tickers!