Milkbox v3.0.2 - lightbox pour Mootools 1.4.x

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 :

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

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 :

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) :

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).

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.

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).

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

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.

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 :

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.

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 ?

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

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 :

<?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() :

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 :

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 :

 [
 { 
    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 :

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().

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 :

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.