doc/page.md

   1 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
   2 <script type="text/javascript" src="../SVGAnimation.js"></script>
   3 <script type="text/javascript" src="../SVGPlayerOne.js"></script>
   4 <script type="text/javascript">
   5   function charge(i,p,a,b) {
   6     var anim = new Animation(i,p,a,b);
   7     anim.loopOnload();
   8     var player = new Controle(anim);
   9     player.connect();
  10   }
  11   function charge_anim2() {
  12     var a = new Animation('anim2','../ellipsographe/svg/ellipsographe-',1,91);
  13     a.loopOnload();
  14     var b = new Controle(a);
  15     b.connect();
  16   }
  17   $(window).load(function() {
  18     anim = new Animation('XXXX','../ellipsographe/svg/ellipsographe-',1,91);
  19     anim.loopOnload();
  20     player = new Controle(anim);
  21     player.connect();
  22     });
  23 </script>
  24
  25
  26 **Participants :** Chupin Maxime, Sarlat Jean-Michel.
  27
  28 **Interface du dépôt Git :** <http://melusine.eu.org/syracuse/G/git/?p=svganimation.git;a=summary>
  29
  30 L'objectif est de développer, en particulier, du code Javascript afin de
  31 présenter des animations de fichiers SVG produits, en particulier, par
  32 MetaPost. Ce développement n'étant pas tout à fait prédéterminé, il sera
  33 constitué à partir de l'exploration de différents scénarios de
  34 présentation de ces animations et des modes de construction des fichiers
  35 SVG.
  36
  37 <div class="alert alert-warning">
  38 <p>Les différents exemples se chargent en cliquant sur le bouton
  39 dédié. Ceci **n'est pas** le comportement par défaut, c'est du code
  40 JavaScript qui permettra de choisir quand l'animation se charge. Il
  41 s'agit
  42 d'éviter de charger toutes les animations présentes sur cette page,
  43 cela serait bien trop lourd.</p>
  44 <p>Nous présentons, dans la section <a
  45 href="#chargement-différé">Chargement différé</a>, le code qui permet de
  46 charger l'animation sur demande.</p>
  47 </div>
  48
  49 ## Installation
  50
  51 Le fichier `SVGAnimation.js` (que l'on supposera dans un répertoire
  52 nommé `js`) est à charger dans la page `html` en mettant les lignes
  53 suivantes :
  54
  55     <script type="text/javascript" src="js/SVGAnimation.js"></script>
  56
  57
  58 ## Principe
  59
  60 Le principe est simple : on dispose d'un ensemble d'images au format
  61 SVG qui constituent, par une suite chronologique, une animation à
  62 visionner. La libraire `SVGAnimation` permet de visionner cette
  63 animation dans une page HTML grâce à JavaScript.
  64
  65 ### La famille d'images
  66
  67 Les différentes images composant l'animation doivent se nommer avec un
  68 *prefixe* suivi d'un nombre (indice), celui-ci pouvant être
  69 formater de différente façons :
  70
  71     monfichier-1.svg  monfichier-2.svg monfichier-3.svg ...
  72
  73 ou, autre exemple :
  74
  75     monfichier-001.svg  monfichier-002.svg monfichier-003.svg ...
  76
  77 Nous verrons comment gérer le formatage de l'indice des images dans
  78 les sections suivantes.
  79
  80 <div class="alert alert-info">
  81 <p>L'idée d'une telle librairie est venue du fait que le logiciel
  82 MetaPost permet de produire des images SVG, et nous l'utilisons
  83 abondamment pour la production d'animations.</p>
  84 </div>
  85
  86
  87 ## L'utilisation
  88
  89 ### Côté HTML
  90
  91 La librairie `SVGAnimation` définit le *prototype* javascript
  92 `Animation`. Pour l'utiliser il faut déclarer une balise HTML `div`
  93 avec un identifiant (`id`) unique. Choisissons pour l'exemple `XXXX`.
  94 À l'intérieur de ces balises, il
  95 faut&#8239;:
  96
  97 * une balise `img` contenant un image `svg` qui servira de vignette à
  98   l'animation;
  99 * une balise `div` avec l'identifiant `id="XXXX_message"` où `XXXX` est
 100   l'identifiant de la balise englobante. Dans cette balise *message*,
 101   on y met, si on le souhaite, un message à afficher avant le
 102   chargement de l'animation;
 103 * une balise `div` avec l'identifiant `id="XXXX_boutons"`.
 104
 105
 106 En supposant que les images SVG se trouvent dans un répertoire nommé
 107 `svg`, voici un exemple d'une telle structure :
 108
 109 ~~~~~~~ { .html }
 110 <div id="anim1">
 111   <img src="svg/ellipsographe-1.svg" alt="animation1"/>
 112   <div class="message" id="anim1_message">Chargement</div>
 113   <div id="anim1_boutons"></div>
 114 </div>
 115 ~~~~~~~
 116
 117 ### Côté JavaScript
 118
 119 Une fois qu'on a la structure HTML présentée ci-dessus, il est
 120 nécessaire d'ajouter un peu de code JavaScript pour permettre à l'animation
 121 de se jouer.
 122
 123 #### Construire l'objet `Animation`
 124
 125 Le *constructeur* du prototype JavaScript s'utilise, pour l'exemple
 126 donné à la section précédente, de la façon
 127 suivante :
 128
 129 ~~~~~~~ { .javascript }
 130 var anim = new Animation('XXXX','svg/ellipsographe-',1,91);
 131 anim.loopOnload();
 132 ~~~~~~~
 133
 134 `XXXX` est l'identifiant de la balise `div` HTML *englobante*,
 135 `svg/ellipsographe-` est le préfixe dont on a parlé plus haut, `1` est
 136 l'indice de la première image à animer, et `91` l'indice de la
 137 dernière.
 138
 139 `anim.loopOnload()` permet le chargement de l'animation.
 140
 141 Une fois celle-ci chargée, il faut en permettre la lecture qui se fait
 142 grâce à un nouvel objet nommé `Controle`. Ce contrôle s'utilise en
 143 fait comme ceci :
 144
 145 ~~~~~~~ { .javascript }
 146 var anim = new Animation('XXXX','svg/ellipsographe-',1,91);
 147 anim.loopOnload();
 148 var player = new Controle(anim);
 149 player.connect();
 150 ~~~~~~~
 151
 152 Nous verrons par la suite comment personnaliser le contrôle de la
 153 lecture de l'animation.
 154
 155 Tout ceci n'est toujours pas suffisant car il faut exécuter ce code
 156 JavaScript. Ceci peut être fait grâce à `JQuery` par exemple, en
 157 exécutant ces quatre lignes de code à l'ouverture de la fenêtre :
 158
 159 ~~~~~~~ { .javascript }
 160 $(window).load(function() {
 161     var anim = new Animation('XXXX','svg/ellipsographe-',1,91);
 162     anim.loopOnload();
 163     var player = new Controle(anim);
 164     player.connect();
 165 });
 166 ~~~~~~~
 167
 168 Bien sûr, ceci nécessite le chargement, dans la page HTML, de la
 169 librairie `JQuery`.
 170
 171
 172
 173
 174
 175 #### Le résultat
 176
 177 Tout ceci donne le code suivant
 178
 179 ~~~~~~~ { .html }
 180 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
 181 <script type="text/javascript" src="../SVGAnimation.js"></script>
 182 <script type="text/javascript">
 183 $(window).load(function() {
 184     var anim = new Animation('XXXX','svg/ellipsographe-',1,91);
 185     anim.loopOnload();
 186     var player = new Controle(anim);
 187     player.connect();
 188 });
 189 </script>
 190 <!--[...]-->
 191 <div id="XXXX">
 192   <img src="svg/ellipsographe-1.svg" alt="animation1"/>
 193   <div class="message" id="XXXX_message">Chargement...</div>
 194   <div id="XXXX_boutons"></div>
 195 </div>
 196 ~~~~~~~
 197
 198 dont l'affichage est :
 199
 200 <div id="XXXX">
 201   <img src="../ellipsographe/svg/ellipsographe-1.svg" alt="animation1"/>
 202   <div class="message" id="XXXX_message">Chargement...</div>
 203   <div id="XXXX_boutons"></div>
 204 </div>
 205
 206
 207 #### Chargement différé
 208
 209 On peut laisser le chargement d'une animation à la demande en créant une
 210 fonction Javascript.
 211
 212 ~~~~~~~ { .javascript }
 213 function charge_anim2() {
 214   var a = new Animation('anim2','svg/ellipsographe-',1,91);
 215   a.loopOnload();
 216   var b = new Controle(a);
 217   b.connect();
 218 }
 219 ~~~~~~~
 220
 221 Fonction qui sera liée à l'*événement* `onclick` d'un bouton proposant
 222 justement le chargement de l'animation...
 223
 224 ~~~~~~~ { .html }
 225 <div id="anim2"
 226   style="margin:10px auto;padding:10px;width:354px;border:2px solid #AAA;border-radius:4px">
 227  <img src="../ellipsographe/svg/ellipsographe-1.svg" alt="animation1" style="width:330px;height:240px"/>
 228  <div class="message" id="anim2_message">Ellipsographe</div>
 229  <div id="anim2_boutons"><button onclick="charge_anim2();">Charger l'animation</button></div>
 230 </div>
 231 ~~~~~~~
 232
 233 Dans le même temps, le *style* des éléments englobants a été adapté.
 234
 235 <div id="anim2"  style="margin:10px auto;padding:10px;width:354px;border:2px solid #AAA;border-radius:4px">
 236   <img src="../ellipsographe/svg/ellipsographe-1.svg" alt="animation1" style="width:330px;height:240px"/>
 237   <div class="message" id="anim2_message">Ellipsographe</div>
 238   <div id="anim2_boutons"><button onclick="charge_anim2()">Charger l'animation</button></div>
 239 </div>
 240
 241
 242
 243 ### Les paramètres
 244
 245 L'objet `Animation` ne possède que deux propriétés configurables, autres
 246 que celles (4) qui lui sont passées en argument.
 247
 248 &bull; **delai** *(valeur par défaut : 50)* &mdash; C'est la durée, en millisecondes, entre deux images.
 249
 250 ~~~{.javascript}
 251 var a = new Animation('anim','svg/pre',1,100);
 252 a.delai = 200;
 253 a.loopOnload();
 254 ~~~
 255 Ceci fixera le défilement à 5 images/s. Un *player* comme ceux que nous vous proposons ci-dessous peut
 256 modifier cette valeur.
 257
 258 &bull; **pad** *(valeur par défaut : 0)* &mdash; Ce paramètre n'a d'effet
 259 que s'il est supérieur ou égal à 2, il permet de fixer la longueur des
 260 index des images en complétant avec des 0.
 261
 262 ~~~{.javascript}
 263 var a = new Animation('anim','svg/pre',1,100);
 264 a.pad = 3;
 265 a.loopOnload();
 266 ~~~
 267 Les images chargées seront, successivement, `svg/pre001.svg`, `svg/pre002.svg`, ..., `svg/pre100.svg`.
 268
 269 ## Les *players*
 270
 271 Le fichier `SVGAnimation.js` contient le constructeur `Controle` qui est
 272 la base des *players*. S'il est invoqué directement, il fournit un
 273 contrôle *simpliste* de l'animation, comme cela a été vu
 274 [ci-dessus](#côté-javascript).
 275
 276 ### `SVGPlayerOne.js`
 277
 278 Pour utiliser un *player* plus *sophistiqué*, il faut surcharger la
 279 méthode `Initialisation` de l'objet `Controle`. Pour plus de détails
 280 sur les *players*, nous vous invitons à consulter la page dédiée.
 281
 282 L'idée que nous présentons ici est de construire un objet JavaScript
 283 qui mettra des boutons de contrôle (lecture, stop, etc.).
 284
 285 Ceci peut se faire de la façon suivante :
 286
 287 ~~~~~~~ { .javascript }
 288 function SVGPlayerOne(a) { // déclaration de l'objet
 289   Controle.call(this,a); // construit à partir de l'objet Controle
 290   SVGPlayerOne.prototype.connect = Controle.prototype.connect // et de
 291   // la méthode connect du Controle
 292 }
 293 ~~~~~~~
 294
 295 Une fois déclaré un tel objet, il suffit de surcharger la méthode
 296 `Initialisation` de l'objet `Controle` fourni dans `SVGAnimation.js`.
 297 Dans l'exemple ci-dessous, on « vide » la `div` `XXXX_message`, et on
 298 ajoute des boutons à la `div` `XXXX_boutons` qui réagissent aux
 299 `onclick` pour lancer les fonctions JavaScript adéquates définies dans
 300 le fichier `SVGAnimation.js`.
 301
 302 ~~~~~~~ { .javascript }
 303 // Surcharge de la méthode [Initialisation]
 304 SVGPlayerOne.prototype.Initialisation = function() {
 305   var a = this.a; // l'animation courante
 306   var self = this.me; // le player
 307   a.image.style.display = 'inline';
 308   a.message.parentNode.removeChild(a.message); // on supprime la
 309       //balise d'id=XXXX_message
 310   var play = document.createElement('button'); // on crée un bouton
 311   play.className = "SVGplay playBtn"; // ajout de classe pour le style
 312   play.innerHTML = "Play"; // on y met du texte
 313   play.onclick = function(){a.action = true; a.rotate(self.a)}; // on
 314       // associe une fonction JS
 315   // on recommence
 316   var stop = document.createElement('button');
 317   stop.className = "SVGplay stopBtn";
 318   stop.innerHTML = "Stop";
 319   stop.onclick = function(){a.action = false;};
 320   var debut = document.createElement('button');
 321   debut.className = "SVGplay debutBtn";
 322   debut.innerHTML = "Début";
 323   debut.onclick = function(){a.action = false; a.first(self.a)};
 324   var fin = document.createElement('button');
 325   fin.className = "SVGplay finBtn";
 326   fin.innerHTML = "Fin";
 327   fin.onclick = function(){a.action = false; a.last(self.a)};
 328   var moins = document.createElement('button');
 329   moins.className = "SVGplay moinsBtn";
 330   moins.innerHTML = "-";
 331   moins.onclick = function(){a.delai = a.delai > 2000 ? 2000 : a.delai * 1.414};
 332   var plus = document.createElement('button');
 333   plus.className = "SVGplay plusBtn";
 334   plus.innerHTML = "+";
 335   plus.onclick = function(){a.delai = a.delai < 30 ? 30 : a.delai / 1.414};
 336   // placement des boutons
 337   a.boutons.appendChild(play);
 338   a.boutons.appendChild(stop);
 339   a.boutons.appendChild(debut);
 340   a.boutons.appendChild(fin);
 341   a.boutons.appendChild(moins);
 342   a.boutons.appendChild(plus);
 343 }
 344 ~~~~~~~
 345
 346 Un fois déclaré tout ceci (le mieux étant dans un fichier externe), on
 347 associe le *player* `SVGPlayerOne` à l'animation de la même façon que
 348 le *player* `Controle` :
 349
 350 ~~~~~~~ { .javascript }
 351 var anim = new Animation('anim2','svg/ellipsographe-',1,91);
 352 anim.loopOnload();
 353 var player = new SVGPlayerOne(anim);
 354 player.connect();
 355 ~~~~~~~
 356
 357 <script type="text/javascript">
 358   function charge_anim3() {
 359     var anim = new Animation('anim3','../ellipsographe/svg/ellipsographe-',1,91);
 360     anim.loopOnload();
 361     var player = new SVGPlayerOne(anim);
 362     player.connect();
 363   }
 364 </script>
 365
 366 <div id="anim3"  style="margin:10px auto;padding:10px;width:354px;border:2px solid #AAA;border-radius:4px">
 367   <img src="../ellipsographe/svg/ellipsographe-1.svg" alt="animation1" style="width:330px;height:240px"/>
 368   <div class="message" id="anim3_message">Ellipsographe</div>
 369   <div id="anim3_boutons"><button onclick="charge_anim3()">Charger l'animation</button></div>
 370 </div>
 371
 372 Le fichier `SVGPlayerOne.js` est fourni à la racine du projet SVGAnimation.
 373
 374
 375
 376 ## Exemples d'utilisation