Si vous appréciez ce plugin, pensez à faire un don : http://www.kyrielles.net/sliderkit, cliquer sur "Donation".
Documentation
Comme beaucoup de plugins jQuery, Slider Kit est un mélange subtil (et indissociable) de HTML, CSS et jQuery. Le code jQuery en lui-même ne se préoccupe ni du design ni du CSS (hormis le calcul nécessaire de certaines tailles). Pour obtenir le design souhaité, il vous faudra donc travailler sur une feuille de style CSS personnalisée.
Mais avant tout, étudions rapidement le code HTML.
HTML
Eléments HTML
Conteneur principal
Classe CSS : [cssprefix].
Ce conteneur englobe tous les autres. Sauf exception, sa hauteur et sa largeur doivent être spécifiées dans le CSS (car les conteneurs enfants ont une position absolue).
Panneau de contenu
Classe CSS : [cssprefix]-panel.
Placer dans cet élément le contenu à animer. Cela peut être n'importe quoi : images, texte, actus, etc.
Bouton précédent
Classe CSS : [cssprefix]-go-btn [cssprefix]-go-prev.
Ce bouton va à l'élement précédent. Il peut être placé n'importe où dans le conteneur principal.
Bouton suivant
Classe CSS : [cssprefix]-go-btn [cssprefix]-go-next.
Ce bouton va à l'élement suivant. Il peut être placé n'importe où dans le conteneur principal.
Commentaire/Boite texte
Classe CSS : [cssprefix]-panel-textbox.
Cet élément est surtout utilisé comme commentaire sur les photos. Il peut être placé n'importe où au-dessus du panneau de contenu.
Conteneur de navigation / Carrousel
Classe CSS : [cssprefix]-nav.
Ce bloc contient les vignettes pour la navigation. Le contenu des vignettes peut être du texte ou des images.
Bouton de ligne précédente
Classe CSS : [cssprefix]-nav-btn [cssprefix]-nav-prev.
Ce bouton fait défiler le carrousel vers la droite. Il doit être placé dans le conteneur de navigation.
Bouton de ligne suivante
Classe CSS : [cssprefix]-nav-btn [cssprefix]-nav-next.
Ce bouton fait défiler le carrousel vers la gauche. Il doit être placé dans le conteneur de navigation.
[cssprefix] la valeur par défaut du préfixe CSS est "sliderkit". Vous pouvez la remplacer par ce que vous voulez.
Le code HTML
Voici une stucture HTML représentative à utiliser avec Slider Kit:
<div class="sliderkit">
<!-- Conteneur de navigation -->
<div class="sliderkit-nav">
<!-- Conteneur "lucarne" -->
<div class="sliderkit-nav-clip">
<ul>
<li><a href="#" rel="nofollow" title="[link title]">~content</a></li>
<li><a href="#" rel="nofollow" title="[link title]">~content</a></li>
<li><a href="#" rel="nofollow" title="[link title]">~content</a></li>
<li><a href="#" rel="nofollow" title="[link title]">~content</a></li>
</ul>
</div>
<!-- Boutons de ligne -->
<div class="sliderkit-nav-btn sliderkit-nav-prev"><a rel="nofollow" href="#" title="Previous line"><span>Previous</span></a></div>
<div class="sliderkit-nav-btn sliderkit-nav-next"><a rel="nofollow" href="#" title="Next line"><span>Next</span></a></div>
</div><!-- // fin de Conteneur de navigation -->
<!-- Conteneur de panneaux -->
<div class="sliderkit-panels">
<!-- Boutons 'Go' -->
<div class="sliderkit-go-btn sliderkit-go-prev"><a rel="nofollow" href="#" title="Previous"><span>Previous</span></a></div>
<div class="sliderkit-go-btn sliderkit-go-next"><a rel="nofollow" href="#" title="Next"><span>Next</span></a></div>
<!-- Panneaux de contenu -->
<div class="sliderkit-panel">
~content
</div>
<div class="sliderkit-panel">
~content
</div>
<div class="sliderkit-panel">
~content
<!-- Placer ici les boites de texte (si besoin) -->
<div class="sliderkit-panel-textbox">
<div class="sliderkit-panel-text">
<h4>Caption title</h4>
<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</p>
</div>
<div class="sliderkit-panel-overlay"></div>
</div>
</div>
</div><!-- // fin de Conteneur de panneaux -->
</div><!-- // fin de Conteneur principal -->
- Le code HTML est flexible : vous pouvez utiliser seulement the carrousel, ou seulement les panneaux de contenu. Les boutons et les commentaires sont optionnels.
- Les boutons 'Go' (sliderkit-go-btn) peuvent être placés n'importe où dans le conteneur principal.
CSS
Styles fondamentaux
La feuille de style principale de Slider Kit est sliderkit-core.css.
Elle regroupe les styles nécessaires au fonctionnement du plugin. Ces styles peuvent biensûr être copiés, déplacés et adaptés à votre convenance.
Habillages personnalisés
En complément de la feuille de styles principale, vous devez écrire une CSS personnalisée ("skin") afin d'obtenir un design sur mesure.
Pour vous aider dans cette tâche (parfois difficile !), j'ai fabriqué plusieurs exemples de skins CSS (consulter la section "Démos" plus haut).
La feuille de style des démos est sliderkit-demos.css. N'hésitez pas à parcourir ce fichier !
Compatibilité
Par souci de compatibilité inter-navigateurs, j'ai ajouté 3 fichiers CSS pour gérer les exceptions d'Internet Explorer de Microsoft (essentiellement pour gérer les effets d'opacité et de transparence) :
- sliderkit-demos-ie6.css.
- sliderkit-demos-ie7.css.
- sliderkit-demos-ie8.css.
Conseils CSS
- La hauteur et la largeur du conteneur principal doivent être spécifiées dans votre feuille de style (sauf dans le cas où vous utilisez Slider Kit pour fabriquer un menu par onglets).
- Sur la balise <li> du carrousel, les valeurs des marges internes et externes doivent être en pixels (px).
Dans la partie <head> de la page HTML :
<link rel="stylesheet" type="text/css" href="../css/sliderkit-core.css" media="screen, projection" />
<link rel="stylesheet" type="text/css" href="../css/sliderkit-demos.css" media="screen, projection" />
<!-- Compatibilité -->
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../css/sliderkit-demos-ie6.css" />
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="../css/sliderkit-demos-ie7.css" />
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="../css/sliderkit-demos-ie8.css" />
<![endif]-->
Javascript
Librairie
Le fichier javascript principal est actuellement jquery.sliderkit.1.9.1.pack.js (packed).
En option, vous pouvez inclure les plugins suivants:
- jquery.easing.1.3.min.js, pour les effects de "easing" sur les transitions.
Plus d'info sur le site : easing plugin homepage - jquery.mousewheel.min.js, pour la navigation avec la molette de souris.
Plus d'info sur le site : Brandon Aaron website.
Ou des extensions de Slider Kit :
- sliderkit.counter.js, pour afficher des compteurs.
- sliderkit.delaycaptions.js, pour temporiser et animer les boites de texte.
- sliderkit.timer.js.
- sliderkit.imagefx.js, pour ajouter des transitions sur les images.
Voir la liste des extensions disponibles.
Usage
Dans la partie <head> de la page HTML :
<script type="text/javascript" src="your_js_path/jquery-1.6.2.min.js"></script>
<!-- Extensions jQuery (optionnelles) -->
<script type="text/javascript" src="your_js_path/jquery.easing.1.3.min.js"></script>
<script type="text/javascript" src="your_js_path/jquery.mousewheel.min.js"></script>
<!-- Slider Kit core -->
<script type="text/javascript" src="your_js_path/jquery.sliderkit.1.9.1.pack.js"></script>
<!-- Extensions de Slider Kit (optionnelles) -->
<script type="text/javascript" src="your_js_path/sliderkit.counter.js"></script>
<script type="text/javascript" src="your_js_path/sliderkit.delaycaptions.js"></script>
<script type="text/javascript" src="your_js_path/sliderkit.timer.js"></script>
<script type="text/javascript" src="your_js_path/sliderkit.imagefx.js"></script>
<!-- Lancement de Slider Kit -->
<script type="text/javascript">
$(window).load(function(){
$(".anytagselector").sliderkit();
});
</script>
Vous pouvez alors paramétrer et lancer le plugin :
<script type="text/javascript">
$(window).load(function(){
$(".anytagselector").sliderkit({
shownavitems:5,
auto:false
});
});
</script>
Consultez la liste 'Options' ci-dessous.
Options
cssprefix
(string) valeur par défaut : "sliderkit". Le préfixe à utiliser sur les noms de classe CSS.
start
(int) valeur par défaut : 0. Définit sur quel élément commencer (le premier étant 0).
auto
(boolean) valeur par défaut : true. Active le défilement automatique.
autospeed
(int) valeur par défaut : 4000. Vitesse du défilement automatique (ms).
autostill (à partir de v1.8)
(boolean) valeur par défaut : false. Si la valeur est "true", le défilement automatique ne s'arrêtera pas au survol de la souris.
mousewheel
(boolean) valeur par défaut : false. Active la navigation avec la molette de souris.
keyboard
(boolean) valeur par défaut : false. Active la navigation au clavier. Très basique pour le moment (flèche gauche/droite).
circular
(boolean) valeur par défaut : false. Active le défilement en boucle (le carrousel revient tout seul en fin ou début de lecture).
shownavitems
(int) valeur par défaut : 5. Définit combien de vignettes seront visibles dans la "lucarne" de navigation.
navitemshover
(boolean) valeur par défaut : false. Si la valeur est "true", l'animation des panneaux de contenu sera déclenchée au survol des vignettes (plutôt qu'au clic).
navclipcenter
(boolean) valeur par défaut : false. Si la valeur est "true", le plugin fera en sorte de centrer la "lucarne" de navigation dans le conteneur de navigation.
navcontinuous (à partir de v1.3)
(boolean) valeur par défaut : false. Si la valeur est "true", cette option fera défiler le carrousel en continu au survol des boutons de ligne (en parallèle, l'option 'scrolleasing' doit avoir la valeur "linear").
navscrollatend (à partir de v1.5)
(boolean) valeur par défaut : false. Si la valeur est "true", cette option fera défiler le carrousel au clic sur les premières et dernières vignettes d'une ligne.
navpanelautoswitch (à partir de v1.6)
(boolean) valeur par défaut : true. Si la valeur est "false", cette option permet de faire défiler la barre de navigation indépendamment des panneaux de contenu.
navfx
(string) valeur par défaut : "sliding". Définit le type d'animation pour le défilement du carrousel. Valeurs possibles : "sliding", "none".
navfxbefore (à partir de v1.7)
(function) valeur par défaut : function(){}. Fonction appelée avant l'animation du carrousel.
navfxafter (à partir de v1.7)
(function) valeur par défaut : function(){}. Fonction appelée après l'animation du carrousel.
scroll
(int) valeur par défaut : égale à la valeur de l'option 'shownavitems'. Définit combien de vignettes seront déplacées lors du défilement du carrousel (en cliquant sur les boutons de ligne). Ce nombre doit être inférieur ou égal à la valeur de l'option 'shownavitems'.
scrollspeed
(int) valeur par défaut : 600. Vitesse du défilement du carrousel (ms).
scrolleasing
(string) valeur par défaut : "swing".
Ajoute un effet de 'easing' sur le mouvement du carrousel.
Les fonctions de 'easing' par défaut de jQuery sont "swing" et "linear". D'autres fonctions sont disponibles en utilisant le plugin jQuery Easing : http://gsgd.co.uk/sandbox/jquery/easing/.
panelfx
(string) valeur par défaut : "fading". Définit le type de transition lors de l'animation des panneaux de contenu. Valeurs possibles : "fading", "sliding", "none". Depuis v1.9 : "fancy" (voir plus bas l'option "imagefx")
panelfxspeed
(int) valeur par défaut : 700. Vitesse de la transition entre les panneaux de contenu (ms).
panelfxeasing
(string) valeur par défaut : "swing".
Ajoute un effet de 'easing' sur la transition entre les panneaux de contenu.
Effets disponibles : .
Les fonctions de 'easing' par défaut de jQuery sont "swing" et "linear". D'autres fonctions sont disponibles en utilisant le plugin jQuery Easing : http://gsgd.co.uk/sandbox/jquery/easing/.
panelfxfirst (à partir de v1.5)
(string) valeur par défaut : "none". Ajoute un effet de transition sur le premier panneau de contenu affiché. Pour le moment il n'y a que 2 valeurs possibles : "fading" ou "none".
panelfxbefore
(function) valeur par défaut : function(){}. Fonction appelée avant l'animation des panneaux de contenu.
panelfxafter
(function) valeur par défaut : function(){}. Fonction appelée après l'animation des panneaux de contenu.
panelbtnshover
(boolean) valeur par défaut : false. Si la valeur est "true", les boutons 'Go' apparaitront au survol de la souris sur les panneaux de contenu.
panelclick
(boolean) valeur par défaut : false. Active la navigation au clic sur les panneaux de contenu.
verticalnav
(boolean) valeur par défaut : false. Carrousel vertical.
verticalslide
(boolean) valeur par défaut : false. Défilement vertical des panneaux de contenu (avec l'option "panelfx" égale à "sliding").
tabs
(boolean) valeur par défaut : false. Nécessaire pour construire un menu par onglets.
freeheight
(boolean) valeur par défaut : false. Dans un menu par onglets, permet de libérer la hauteur des panneaux de contenu (ils sont placés en position relative). Dans ce cas l'option "panelfx" ne peut pas prendre la valeur "sliding").
fastchange
(boolean) valeur par défaut : true. Permet à l'utilisateur de faire défiler rapidement les éléments du slider. Si cette option est définit en 'false', l'utilisateur devra attendre la fin d'une transition pour pouvoir lancer la suivante.
counter (à partir de v1.7.1)
(boolean) valeur par défaut : false. Active l'extension Slider Kit 'Counter'.
delaycaptions (à partir de v1.7.1)
(boolean/array) valeur par défaut : false. Active l'extension Slider Kit 'DelayCaptions'.
timer (à partir de v1.8)
(boolean/array) valeur par défaut : false. Active l'extension Slider Kit 'Timer'.
imagefx (à partir de v1.9)
(array) valeur par défaut : false. Paramètres de l'extension Slider Kit 'ImageFx'. A utiliser avec la transition 'fancy'.
debug
(boolean) valeur par défaut : false. En mode 'debug', le script s'arrête sur les erreurs d'exécution et renvoie un code d'erreur. Voir la rubrique Dépannage.
Extensions de Slider Kit
A partir de la version 1.7, les nouvelles fonctionnalités de Slider Kit seront ajoutées en tant qu'extensions, afin de limiter le poids du plugin principal.
Activer une extension
1. Consulter les sections suivantes sur les extensions existantes pour récupérer le code HTML nécessaire à chacune.
2. Appeler le fichier d'extension dans la page HTML.
Prenons l'exemple de l'extension 'Counter' :
<script type="text/javascript" src="your_js_path/jquery.sliderkit.1.9.1.pack.js"></script>
<!-- Extensions Slider Kit -->
<script type="text/javascript" src="your_js_path/sliderkit.counter.js"></script>
3. Il est à présent possible d'utiliser l'extension dans Slider Kit, en la déclarant dans les paramètres du plugin :
<script type="text/javascript">
$(window).load(function(){
$(".anytagselector").sliderkit({
counter:true
});
});
</script>
Extension 'Counter'
Permet d'affichier des compteurs de panneaux ou de lignes. Voir la page de démo pour plus de détails.
Balises HTML à utiliser
<div class="sliderkit-count sliderkit-count-lines">
page <span class="sliderkit-count-current"></span>
<span class="sliderkit-count-sep">/</span>
<span class="sliderkit-count-total"></span>
</div>
<!-- Compteur de panneaux -->
<div class="sliderkit-count sliderkit-count-items">
<span class="sliderkit-count-current"></span>
<span class="sliderkit-count-sep">/</span>
<span class="sliderkit-count-total"></span>
</div>
- Les compteurs peuvent être placés n'importe où dans le conteneur principal.
- La classe sliderkit-count-sep est optionnelle.
Extension 'DelayCaptions'
Permet d'animer l'apparition des boites de texte sur les panneaux de contenu. Voir la page de démo pour plus de détails
Balises HTML à utiliser
<a title="[title]" href="#"><img alt="[Alternative text]" src="your_image.jpg"></a>
<div class="sliderkit-panel-textbox">
<div class="sliderkit-panel-text">
<h4>Caption title</h4>
<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.</p>
</div>
<div class="sliderkit-panel-overlay"></div>
</div>
</div>
- Les boites de texte doivent être placées dans les conteneurs de panneaux.
- Les boites de texte doivent avoir des valeurs de hauteur/largeur spécifiées dans le CSS
Dans la partie <head> de la page HTML :
<script type="text/javascript">
$(window).load(function(){
$(".anytagselector").sliderkit({
delaycaptions:{
delay:400,
position:"bottom",
transition:"sliding",
duration:300,
easing:"easeOutExpo"
hold:true
}
});
});
</script>
Options disponibles
delay
(int) valeur par défaut : 400. Délai d'attente avant d'afficher la boite de texte (en ms).
position
(string) valeur par défaut : "bottom". Uniquement pour la transition "sliding" : détermine le point de départ du slide. Valeurs possibles : "top", "right", "bottom", "left".
transition
(string) valeur par défaut : "sliding". Type de transition. Valeurs possibles : "sliding", "fading".
duration
(int) valeur par défaut : 300. Durée de la transition (ms).
easing
(string) valeur par défaut : "linear". Effet optionnel sur la transition.
hold (v1.8) obsolète à partir de v1.9
(boolean) valeur par défaut : false. Si vrai, empêche le changement de panneau durant l'animation de la boite de texte.
Extension 'Timer'
Permet d'afficher le temps restant entre 2 photos, sous la forme d'une barre de progression animée. Voir la page de démo pour plus de détails.
Balises HTML à utiliser (en dehors du conteneur de panneaux)
<div class="sliderkit-timer"></div>
<!-- Exemple de bloc 'timer' personnalisé -->
<div class="sliderkit-timer-wrapper">
<div class="sliderkit-timer"></div>
</div>
- Si aucun bloc HTML 'timer' n'est trouvé par l'extension, c'est le bloc par défaut qui sera généré par le script.
- Si vous ajoutez votre propre bloc, attention à le placer en dehors du conteneur de panneaux ('sliderkit-panels').
Dans la partie <head> de la page HTML :
<script type="text/javascript">
$(window).load(function(){
$(".anytagselector").sliderkit({
timer:{
fadeout:0.2
}
});
});
</script>
Options disponibles
fadeout
(float) valeur par défaut : 1. Valeur d'opacité sur la fin de l'animation. Valeurs possibles : nombres à une décimale entre 0 à 1. Ex : 0.2.
Extension 'ImageFx'
'ImageFx' est inspiré du plugin jQuery 'jqFancyTransitions', créé par Ivan Lazarevic (exemples et documentation ici: http://www.workshop.rs/projects/jqfancytransitions).
Cette extension propose 4 types de transitions pour les images.
Elle ne s'applique qu'aux images. Voir la page de démo pour plus de détails.
Dans la partie <head> de la page HTML :
<script type="text/javascript">
$(window).load(function(){
<!-- Usage simple -->
$(".anytagselector").sliderkit({
panelfx: 'fancy',
imagefx: {
fxType: 'zipper'
}
});
<!-- Usage avancé -->
$(".anytagselector").sliderkit({
panelfx: 'fancy',
imagefx: {
fxType: 'curtain',
fxDelay: 50,
fxDuration: 1000,
strips: 8,
stripOrientation: 'reverse',
stripPosition: 'default',
stripDirection: 'default'
}
});
});
</script>
Options disponibles
fxType
(string) valeur par défaut : 'curtain'. Type de transition. Valeurs possibles : 'curtain', 'zipper', 'wave', 'fountain', 'random' (aléatoire).
fxDelay
(int) valeur par défaut : 60. Temps d'attente entre 2 bandes, en ms. Plus cette valeur est élevée, moins rapide est l'animation.
fxDuration
(int) valeur par défaut : 500. Durée de l'animation de chacune des bandes, en ms. Plus cette valeur est élevée, moins rapide est l'animation.
strips
(int) valeur par défaut : 10. Nombre de bandes.
stripOrientation
(string) valeur par défaut : 'default'. Valeurs possibles : 'default' (bandes verticales), ou 'reverse' (bandes horizontales).
stripPosition
(string) valeur par défaut : 'default'. Position de départ des bandes. Valeurs possibles : 'default' (la position par défaut est 'haut' si l'orientation des bandes est verticale, et 'gauche' si l'orientation est horizontale), ou 'reverse' (la position inversée est 'bas' si l'orientation des bandes est verticale, et 'droite' si l'orientation est horizontale).
stripDirection
(string) valeur par défaut : 'default'. Valeurs possibles : 'default' (la direction par défaut est 'haut ver bas' si l'orientation des bandes est verticale, et 'gauche vers droite' si l'orientation est horizontale), ou 'reverse' (la direction inversée est 'bas vers haut' si l'orientation des bandes est verticale, et 'droite vers gauche' si l'orientation est horizontale). Valeur supplémentaire : 'auto' (pour l'effet 'curtain' seulement).
Compléter Slider Kit
Récupérer l'objet Slider Kit
Afin d'ajouter des fonctionnalités à votre slider, vous pouvez récupérer un objet Slider Kit et l'utiliser dans un code personnalisé.
var mySliderkit = $(".anyclassorid").data("sliderkit"); // 'mySliderkit' est maintenant une instance de l'objet 'sliderkit'
$('#play').click(function() {
mySliderkit.autoScrollStart(); // Cette méthode applique un autoscroll au clic sur le lien '#play'
});
Voir la page de démo pour plus de détails.
Méthodes de l'API
autoScrollStart()
Démarre l'auto-scrolling.
autoScrollStop()
Arrête l'auto-scrolling.
playBtnStart()
Démarre l'auto-scrolling et change la classe CSS du bouton 'Play'.
playBtnPause()
Arrête l'auto-scrolling et change la classe CSS du bouton 'Play'.
navPrev()
Anime le conteneur de navigation vers la ligne précédente.
navNext()
Anime le conteneur de navigation vers la ligne suivante.
stepBackward()
Affiche le panneau précédent (ou le dernier si on est au début).
stepForward()
Affiche le panneau suviant (ou le premier si on est à la fin).
changeWithId( index )
Affiche un panneau en fonction de la valeur 'index' (position).
selectThumbnail( index )
Met un élément de la navigation en surbrillance, en fonction de la valeur 'index' (position).
A propos
Remerciements
Lors du développement de Slider Kit, d'excellents travaux jQuery m'ont aidé (et inspiré), dont :
jCarousel,
jCarousel Lite,
Galleria,
Gallery view,
Contentflow,
Nivo Slider,
jQuery Cycle.
La version compressée de Slider Kit est générée grâce au packer de Dean Edwards.
Les photos utilisées dans les pages de démos sont l'oeuvre de Camille (New York, 2008).
Compliments
