1. Qu'est donc la Milkbox ?

La Milkbox est un clone de la lightbox mais écrite pour les versions 1.3.x et 1.4.x de Mootools (sauf la version 1.4.3 qui contient un bogue sur la méthode getProperty). La première personne à avoir créé une lightbox est Lokes Dhakar, dont la Milkbox s'inspire.

2. Caractéristiques principales

  • Prêt pour le HTML5. La Milkbox est testée sous le doctype HTML5 et en utilise les nouvelles propriétés.

  • Support swf. Vous pouvez visualiser les fichiers swf avec la Milkbox. Grâce à l'attribut data-milkbox-size, vous pouvez préciser la largeur et la hauteur que la Milkbox doit avoir pour visionner le fichier swf.

  • Support HTML. Vous pouvez aussi visualiser des pages HTML locales ou distantes avec la Milkbox. Elles sont alors chargées dans une iFrame, et vous devez également utiliser l'attribut data-milkbox-size pour préciser la largeur et la hauteur que la Milkbox doit avoir pour visionner les pages.

  • Les variables. Vous pouvez transmettre des variables aux fichiers swf ou HTML simplement en les ajoutant à l'URL des fichiers.

  • Les options AutoSize et autoSizeMaxHeight. L'AutoSize est appliquée par défaut ; si nécessaire, cela rend les photos plus petites afin qu'elles soient adaptées à la fenêtre du navigateur. Si vous ne désirez pas qu'elles soient plus grandes qu'une certaine hauteur, alors utilisez l'option autoSizeMaxHeight.

  • Les options AutoPlay et autoPlayDelay. Vous pouvez les positionner de manière globale ou bien propre à chaque galerie, comme dans les appels JavaScript.

  • L'option Centered. Si vous le voulez, la Milkbox peut être centrée sur l'écran.

  • Les galeries XML. Au lieu d'écrire des liens HTML et de laisser la Milkbox les collecter automatiquement, vous pouvez écrire une ou plusieurs galeries via le XML et les charger avec la méthode addgaleries(). Vous pouvez alors visionner chaque fichier de chaque galerie avec un simple appel JavaScript.

  • Les galeries JSON. Au lieu d'écrire des liens HTML et de laisser la Milkbox les collecter automatiquement, vous pouvez lui faire construire des galeries par l'intermédiaire d'objets JSON via la méthode addgaleries(). Vous pouvez alors visionner chaque fichier de chaque galerie avec un simple appel JavaScript.

  • Lancement depuis JavaScript. Vous pouvez utiliser la méthode open() pour lancer une galerie avec les options paramétrables d'autoplay de JavaScript et même de Flash via l'interface ExternalInterface. Vous pouvez également utiliser la méthode openWithFile() pour visualiser un fichier sur le tas sans devoir construire une galerie.

  • La Milkbox cache les tags select et textarea lors de l'animation ; de même, il y a une option (removeTitle) qui vous laisse décider si le navigateur peut afficher ou non les tooltips lorsque vous survolez les liens de la Milkbox. Par défaut, il est à true.

  • L'option ImageOfText. Si votre langue maternelle n'est pas l'anglais et que vous ne voulez pas voir "1 of 15", utilisez cette option pour positionner la valeur de "of". Si je suis italien, je le positionne à "di". Si je suis français, je le positionne à "de". Par défaut il est à "of".

  • Les transitions sont minimes (en fait, avec la version 3, il n'y en a qu'une pour chaque fichier) : j'aime la navigation rapide. Quoi qu'il en soit, vous pouvez utiliser n'importe quel effet de transition de MooTools (Fx.Transitions). Pour cela, positionnez l'option resizeTransition.

  • Les boutons next et prev sont dans la section du bas, près du bouton close. De cette façon, je pense que je la rends plus utilisable en ne cachant pas quelque chose et en maintenant toute la navigation dans un seul endroit. Il y a également une boucle au niveau boutons next et prev : si la Milkbox montre la dernière image de la galerie et que vous cliquez sur le bouton next, vous allez voir la première image de la galerie ; de manière similaire, si vous voyez la première image et que vous cliquez sur le bouton prev, vous verrez la dernière image de la galerie.

  • La navigation clavier :
    - Next image (image suivante) : flèche droite ou bien barre d'espace ;
    - Previous image (image précédente) : flèche gauche ;
    - Close Milkbox (fermer la Milkbox) : touche Esc (Escape).

  • Le bouton de fermeture est simplement une croix, il n'y a pas le mot "close" : ainsi, aucune langue n'est impliquée. En fait, il y a trois manières pour fermer la Milkbox : le clic sur la croix, le clic sur le recouvrement, l'appui sur la touche Escape.

  • Toute l'interface graphique est paramétrable via CSS ou via des options JavaScript. Vous pouvez même télécharger les boutons (.psd et .ai) et les modifier !

3. Comment utiliser la Milkbox (basic) ?

1. Soyez sûr que le doctype est bien déclaré pour le HTML5 tout en haut de la page, pour que les propriétés soient valides. Si la validation n'est pas un souci, employez un doctype du xhtml.

 
Sélectionnez
<!DOCTYPE html>



2. Incluez le fichier milkbox.css dans votre page. Vérifiez l'emplacement des images. Je propose de les laisser dans css/milkbox/milkbox.css, le dossier CSS de la Milkbox.

3. Ajoutez la bibliothèque Mootools. Le fichier milkbox.js nécessite les bibliothèques suivantes pour fonctionner correctement :

- le Mootools Core ;
- les composants Assets, Measure et QueryString de Mootools More.

 
Sélectionnez
<script src="js/mootools-core.js"></script>
<script src="js/mootools-more.js"></script>


4. Incluez le fichier milkbox.js ou (c'est peut-être mieux) le fichier milkbox-yc.js.

 
Sélectionnez
<script src="js/milkbox.js"></script>


5. Ajoutez l'attribut data-milkbox à chaque lien "milkbox". Si le fichier référencé par le lien n'est pas une galerie, alors positionnez la propriété data-milkbox à single ; autrement, choisissez arbitrairement un nom pour la galerie. Optionnellement, vous pouvez mettre une légende sur le lien en positionnant la propriété title. Si vous désirez ajouter des tags dans la propriété title (par exemple un lien), utilisez les entités HTML et non les quotes, et stylisez-les éventuellement avec du CSS : l'id approprié est #mbox-caption.

 
Sélectionnez
<a href="img/01b.jpg" data-milkbox="single" title="Caption goes here...">image #1</a>
<a href="img/02b.jpg" data-milkbox="gall1" title="Caption goes here...">image #2</a>
<a href="img/03b.jpg" data-milkbox="gall1" title="Caption goes here...">image #3</a>



Si un lien pointe vers un fichier swf ou vers un fichier HTML, ajoutez l'attribut data-milkbox-size avec les valeurs width et height, séparées par une virgule :

 
Sélectionnez
<a href="swf/banner.swf" data-milkbox="gall1" data-milkbox-size="width:600,height:200" title="Caption goes here...">image #1</a>

4. Comment paramétrer la Milkbox ?

4-A. Les propriétés CSS

Vous pouvez paramétrer les propriétés CSS suivantes simplement en modifiant le fichier milkbox.css (lisez les commentaires qui y figurent) ou bien en modifiant les éléments du DOM via les méthodes setStyle/setStyles. Les éléments du DOM concernés sont écrits entre parenthèses (à titre informatif pour les développeurs) :

  • la couleur de recouvrement (milkbox.display.overlay) ;

  • la couleur du background (milkbox.display.mainbox) ;

  • l'image du background principal (milkbox.display.mainbox) -> s'entend "ajouter" une image ;

  • la couleur et l'épaisseur de la border (milkbox.display.mainbox) ;

  • le padding de la boîte (milkbox.display.mainbox) ;

  • les propriétés intérieures de la boîte (milkbox.display.filebox) ;

  • toutes les images (attention : si vous changez les dimensions des boutons, vous devez savoir manier le CSS) ;

  • toutes les propriétés sur le texte (milkbox.display.caption et milkbox.display.count) ;

  • la border-left du contrôle de navigation (milkbox.display.controls).

Vous pouvez aussi ajouter border et padding aux images (ou aux fichiers swf) via les options JavaScript globales. Pour positionner des propriétés CSS via le JavaScript, vous pouvez faire quelque chose qui ressemble à ceci :

 
Sélectionnez
window.addEvent('domready', function(){
   milkbox.display.mainbox.setStyle('borderColor','#00ff00');
   milkbox.display.mainbox.setStyle('backgroundColor','#aabbcc');    
});

4-B. Les options JavaScript globales

Voici la liste des options globales que vous pouvez modifier. Les valeurs par défaut sont écrites entre parenthèses :

  • overlayOpacity (0.7) ;

  • marginTop (50) : adéquat pour les grandes images parce qu'il change le décalage à partir du haut de la page ;

  • initialWidth (250) ;

  • initialHeight (250) ;

  • fileboxBorderWidth ("0px") : lorsque vos images ont la même couleur de fond que celle utilisée pour la Milkbox et que vous voulez ajouter une bordure, vous n'avez pas besoin de le faire avec Photoshop ;

  • fileboxBorderColor ("#000000") ;

  • fileboxPadding ("0px") ;

  • resizeDuration (.5) ;

  • resizeTransition ('sine:in:out') : vous pouvez utiliser une fonction (exemple : Transitions.Sine.easeIn) ou une chaine de caractères (exemple : 'quint:out'). Voir la documentation Mootools ;

  • autoPlay (false) ;

  • autoPlayDelay (7) : positionnée en secondes, pas en millisecondes ;

  • removeTitle (false) : s'il est à true, vous ne verrez pas apparaitre les titles sur les liens de la Milkbox (comportement par défaut des navigateurs tels que Firefox) ;

  • autoSize (true) : réduit les images si elles ne cadrent pas bien dans le navigateur ;

  • autoSizeMaxHeight (0) : positionne la hauteur maximale pour un redimensionnement automatique. Ne fonctionne que si la valeur est > 0 et que la propriété autoSize est à true ;

  • centered (false) : true si la Milkbox doit être centrée sur la fenêtre ;

  • imageOfText ('of') : change le mot entre les compteurs pour l'avoir dans sa langue ;

  • onXmlgaleries (function(){}) : précise une fonction optionnelle utilisée lorsqu'une galerie XML est chargée ;

  • onClosed (function(){}) : précise une fonction optionnelle utilisée immédiatement après que la Milkbox soit fermée ;

  • onFileReady (function(){}) : précise une fonction optionnelle utilisée lorsque le fichier courant est chargé et prêt à être montré.

En changeant les options globales, vous changez les options pour toutes les galeries de votre page. Vous pouvez les positionner de trois manières.

1. Dans le fichier .js, au début des classes.

2. Dans le fichier .js, en bas, là où la Milkbox est instanciée :

 
Sélectionnez
window.addEvent('domready', function(){
 milkbox = new Milkbox({ resizeTransition:'back:out', topPosition:30, centered:true });
});

3. Dans un script JavaScript, après que le DOM est prêt (domready), en utilisant la méthoderefreshDisplay(options:Object,keepBackup:Boolean = false) :

 
Sélectionnez
window.addEvent('domready', function(){
 milkbox.refreshDisplay({ 
    fileboxBorderWidth:'5px',
    fileboxBorderColor:'#ffcc00',
    resizeTransition:'bounce:out',
    resizeDuration:1
 });
});

Le refreshDisplay() prend les nouvelles options en premier argument, et un booléen en second argument (passez true si vous voulez utiliser les nouvelles options une fois seulement).

5. Comment utiliser la Milkbox (avancé) ?

5-A. Paramétrer les événements

La Milkbox a trois événements paramétrables : onXmlgaleries, onClosed et onFileReady.

  • Utilisez onXmlgaleries lorsque vous voulez savoir si un fichier XML est complètement chargé. Pour plus de détails, voir le chapitre ;

  • Utilisez onClosed lorsque vous voulez faire quelque chose immédiatement après que la Milkbox est fermée ;

  • Utilisez onFileReady lorsque vous voulez faire quelque chose quand le fichier courant est chargé et est prêt à être affiché. Le fichier courant est milkbox.currentFile.

5-B. AutoPlay

Vous pouvez le positionner de manière globale via les options autoPlay et autoPlayDelay comme décrit dans le chapitre . Si vous utilisez une galerie XML, vous pouvez positionner une option autoplay différente pour chaque galerie. Enfin, vous pouvez changer les options sur une galerie par l'utilisation de setAutoPlay() (décrit ci-dessous).

Mais en fait, qu'est-ce que l'autoPlay ? Et bien, oui, c'est ça !

La Milkbox va afficher séquentiellement les fichiers d'une galerie avec un délai prédéfini entre chaque affichage. Vous êtes capable d'arrêter ou de redémarrer la séquence en cliquant sur les boutons play ou pause ou bien sur les boutons next ou prev. Dans ce cas, vous devez utiliser le bouton play pour la redémarrer.

Utilisation de setAutoPlay(objet ou tableau d'objets)

Vous aurez l'utilité de setAutoPlay() si vous voulez redéfinir de manière permanente les options autoplay gobales pour une ou plusieurs galeries. Vous pouvez lui passer un objet ou bien un tableau d'objets. Chaque objet doit avoir trois propriétés : la galerie (chaine de caractères), le flag autoplay (booléen), le délai (nombre).

 
Sélectionnez
window.addEvent('domready', function(){
 milkbox.setAutoPlay([
    { gallery:'gall1', autoplay:true, delay:10 },
    { gallery:'gall2', autoplay:false },
    { gallery:'gall3', autoplay:true, delay:7 }
 ]);
});

5-C. Démarrer la Milkbox depuis JavaScript

Au lieu de cliquer sur un lien, vous pouvez démarrer la Milkbox directement depuis le JavaScript (et de même depuis le Flash via l'interface ExternalInterface) en utilisant la méthode open() pour les galeries ou la méthode openWithFile() pour les fichiers seuls sans avoir besoin de construire une galerie.

Utilisation de open(galerie (chaine de caractères ou instance de MilkboxGallery),index)

Vous aurez l'utilité de open() si vous voulez démarrer la Milkbox directement depuis JavaScript. Vous pouvez lancer n'importe quelle galerie à partir de n'importe quel fichier. En paramètre, vous pouvez passer à open() le nom de la galerie (une chaine de caractères) ou, si vous êtes un développeur averti et pour certaines raisons qui vous sont propres, vous pouvez directement passer une instance de MilkboxGallery.

 
Sélectionnez
window.addEvent('domready', function(){
 $('testbutton').addEvent('click', function(e){
    e.preventDefault();
    milkbox.open('mygallery',3);
 });
});


Si vous désirez démarrer la Milkbox depuis Flash, utilisez alors l'interface ExternalInterface :

 
Sélectionnez
import flash.external.ExternalInterface;

//Si besoin, chargement de fichiers XML :
ExternalInterface.call("milkbox.addgaleries",'galeries.xml');

//AS2 : ////////////////////////////////////
sampleButton.onRelease = function(){
 ExternalInterface.call("milkbox.open",['mygallery',3]);
}

//ou AS3 : /////////////////////////////////
function openMilkboxFromAS(e:MouseEvent){
 ExternalInterface.call("milkbox.open",['mygallery',3]);
}

sampleButton.addEventListener(MouseEvent.CLICK,openMilkboxFromAS);


Utilisation de openWithFile({objet avec href, propriétés de taille et de titre}, {options de la Milkbox})

Vous aurez l'utilité de openWithFile() si vous voulez ouvrir un fichier avec la Milkbox directement depuis JavaScript sans devoir construire un élément XML ou une galerie JSON.

 
Sélectionnez
window.addEvent('domready', function(){
 $('testbutton').addEvent('click', function(e){
    e.preventDefault();
    milkbox.openWithFile({ href:'img/01b.jpg', title:'Test text'});
 });
});


Ou bien avec quelques options supplémentaires ?

 
Sélectionnez
window.addEvent('domready', function(){

 $('testbutton').addEvent('click', function(e){
    e.preventDefault();
    milkbox.openWithFile(
       { 
          href:'swf/flash.swf', 
          title:'openWithFile() with some layout and transitions tweaks',
          size:'width:600,height:350'
       }, 
       {
          overlayOpacity:1, 
          resizeTransition:'bounce:out', 
          centered:true
       }
    );  //fin openWithFile
 });  //fin click event

});  //fin domready event

5-D. Galeries externes

Si vous n'avez pas besoin d'écrire des liens HTML mais que vous désirez quand même utiliser la Milkbox pour afficher des galeries, vous devez les définir d'une autre manière. Découvrons ensemble les galeries externes (XML et JSON). Les deux types sont chargés dans la Milkbox en utilisant la méthode addgaleries(chaine de caractères ou objet).

Galeries XML

Pour utiliser les galeries XML, la première chose à faire est d'écrire un fichier XML, par exemple :

 
Sélectionnez
<?xml version="1.0" encoding="utf-8"?>
<div id="galeries">
    <div class="gallery" name="xmlG1" autoplay="true" delay="7" >
       <a href="swf/testswf1.swf" rev="width:550, height:400" title="Lorem ipsum..." />

       <a href="swf/testswf2.swf" rev="width:650, height:250" title="Lorem ipsum..." />
       <a href="img/01b.jpg" title="Lorem ipsum..." />
       <a href="img/03b.jpg" title="Lorem <a href=#>ipsum...</a>" />
    </div>

    <div class="gallery" name="xmlG2" >

       <a href="img/01b.jpg" title="Lorem ipsum..." />
       <a href="img/03b.jpg" title="Lorem <a href=#>ipsum...</a>" />
       <a href="swf/testswf1.swf" rev="width:550, height:400" title="Lorem ipsum..." />
       <a href="swf/testswf2.swf" rev="width:650, height:250" title="Lorem ipsum..." />
    </div>
</div>


Comme vous le constatez, vous devez avoir pour chaque galerie un tag div de class="gallery" et positionner la propriété name. De plus, vous pouvez ajouter les options du paramètre autoplay pour chaque galerie. Notez qu'étant dans un document XML, les tags ne sont pas réellement des tags HTML et les tags "a" doivent être des tags vides. Donc vous devez les fermer avec un espace suivi d'un slash ((un espace)/>), et non pas avec un tag de fermeture de lien "/a". Une fois que vous avez votre fichier XML, chargez-le avec la méthode addgaleries() :

 
Sélectionnez
milkbox.addgaleries('galeries.xml');


Maintenant, vous pouvez utiliser toutes les méthodes de la Milkbox pour votre nouvelle galerie. Je pense que vous allez au minimum utiliser la méthode open(), mais avant cela, il est plus sûr de vérifier que le fichier XML est réellement chargé. Donc vous devriez envelopper cela dans l'événement onXmlgaleries :

 
Sélectionnez
milkbox.addEvent('xmlgaleries',function(){
 $('testButton').addEvent('click', function(e){
    e.preventDefault();
    milkbox.open('xmlG2');
 });
});

milkbox.addgaleries('galeries.xml');


Galeries JSON

Pour utiliser les galeries JSON, vous devez passer l'objet JSON à la méthode addgaleries(). L'objet JSON doit avoir cette forme :

 
Sélectionnez

 [
 { 
    name:'gall1', autoplay:true, autoplay_delay:7, 
    files:[
          {href:'file1.jpg', size:'width:900,height:100', title:'text'},
          {href:'file2.html', size:'w:800,h:200', title:'text'},
          {...},
          {...}
    ]
 },
 { 
    name:'gall2', 
    files:[
          {href:'file1b.swf', size:'width:500,height:200', title:'text'},
          {href:'file3.html', size:'w:800,h:200', title:'text'},
          ]
 }
 ]


Vous pouvez, par exemple, le sauver dans une variable et passer cette variable à la méthode addgaleries(), ou bien le passer directement :

 
Sélectionnez
var gallery = [
 { 
    name:'obj-gall1', autoplay:true, autoplay_delay:4, 
    files:[ 
             { href:'img/01b.jpg', title:'Test title' }, 
             { href:'swf/testswf1.swf?var1=yellow&var2=300' } 
          ]
  }
]

milkbox.addgaleries(gallery);


Alors, vous pouvez utiliser les méthodes habituelles de la Milkbox telles que open().

5-E. Recharger les galeries

Souvent, en utilisant l'Ajax, les liens et les galeries changent sans rafraîchir complètement la page principale et sans mettre à jour les galeries internes de la Milkbox. Pour solutionner ce genre de problèmes, vous pouvez simplement utiliser la méthode reloadPagegaleries(). Par exemple, une application Ajax générique pourrait faire quelque chose du genre :

 
Sélectionnez
app.ajaxRequest.onSuccess(response){
 addResponseToHtml(); 
 milkbox.reloadPagegaleries();
}


Il existe également une méthode utilitaire pour recharger toutes les galeries externes déjà chargées (XML ou JSON) et, pourquoi pas, en charger de nouvelles. Cette méthode est resetExternalgaleries(liste : chaine de caractères/objet ou tableau d'objets) ; vous passez les nouvelles galeries en paramètre.

6. Remarques

Tests effectués (sous Windows et Mac Os X) :

  • IE 7/8/9 ;

  • Firefox ;

  • Safari ;

  • Chrome.



Si votre page contient des vidéos Flash

Si vous utilisez la Milkbox dans une page qui contient des objets Flash, il est préférable de positionner les propriétés wmode "opaque" ou bien "transparent".


Compression JavaScript

Si votre site tourne sur un serveur Apache avec un module de dézippage (il est généralement activé par défaut, ou bien vous pouvez demander au fournisseur de l'activer gratuitement) vous pouvez lui préciser d'utiliser vos fichiers JS/CSS zippés. En faisant cela, j'écris d'habitude une de ces lignes dans un fichier .htaccess (publié dans le répertoire principal du site) :

 
Sélectionnez

AddOutputFilterByType DEFLATE text/html text/css application/x-javascript
#ou
AddOutputFilterByType DEFLATE text/html text/css application/javascript


Le fichier milkbox-yc.js aura alors une taille de seulement 5.5Kb.

7. Logiciels, plugins et communauté

La Milkbox est également utilisée par d'autres développeurs du monde entier pour divers logiciels et plugins. Notamment :

  • Feindura - Flat file cms
    Feindura est un système Open Source de gestion de contenu (fichiers) pour les concepteurs Web. Idéal pour les petits et moyens sites Web. Il n'y a pas besoin de base de données et c'est facile à intégrer sur votre site Web. Ils utilisent la Milkbox pour les galeries d'images ;

  • Mootools-FileManager
    Un gestionnaire de fichiers pour le Web basé sur MooTools qui vous permet de regarder, télécharger et modifier des fichiers et des dossiers par l'intermédiaire de votre navigateur ;

  • Gerrit E.G. Hobbelt
    Ger Hobbelt utilise la Milkbox dans plusieurs de ses projets et m'a beaucoup aidé pour la version 3.0.0. Il a plus de 20 ans d'expérience en tant que software engineer, appréciant l'architecture de systèmes et le développement d'inconditionnel avec un focus certain sur la sécurité, la stabilité et la survie du produit. Actuellement (selon 2011), son action se centre sur une analyse financière et sur un pronostic concernant la technologie Web et la nécessité d'utiliser des mathématiques pour coder ;

  • ScrollBox Pro - Plugin pour Joomla
    La Milkbox est utilisée par Nikita Zonov dans son diaporama pour Joomla.

8. Télécharger la Milkbox

  • Vous trouverez ici les fichiers de la Milkbox avec les démonstrations, ainsi que la version yui-compressed.

  • Tandis qu'ici se trouvent les boutons [5 Mb (.psd et .ai)].

  • N'hésitez pas à soutenir Luca Reghellin et son produit.

9. Remerciements

Je tiens à remercier chaleureusement Luca Reghellin pour m'avoir autorisé à traduire son article.
Je remercie également dourouc05 pour son aide à la rédaction, ainsi que ClaudeLELOUP et _Max_ qui me corrigent patiemment une fois encore.